Run a task now
Start a real run of an existing task right away, outside its schedule. It does everything a scheduled run does: writes go through, deliveries are sent, and it appears in the run history. Use it for “run my weekly report now” instead of creating a copy of the task.
Pass instructions to add something for this run only (“this time also break out refunds”). The run reads them as extra instructions on top of the task’s prompt; the saved task, its prompt and its schedule do not change, and later runs do not see them.
An inactive task can be run this way; the run does not switch it on. Called from an agent chat, the chat is signalled when the run ends, so it need not poll. 400 if instructions is not a string of at most 4000 characters; 422 if the task has expired or already has a run in flight, the account is already running its maximum number of task runs, or it is out of AI credits.
Authorizations
API key in the format: Bearer {api_token}
Headers
Makes this write safe to retry: a repeat with the same key replays the first response instead of creating a second resource. Scoped to the account, remembered for 24 hours; reusing a key with a different payload is an error.
255Path Parameters
Task id (task_...)
Body
Extra instructions for this run only, e.g. "This time also break out refunds by product." Not saved on the task.
4000Response
Accepted — the run executes in the background; poll GET /task_runs/{id}.
The run's own conversation (aichat_...): what it read, called and said. Read it with search_chats.
pending, running, completed, failed, needs_input, timed_out, unknown, skipped, cancelled When a stop was requested. The run stays running until it reaches its next step, then settles as cancelled.
condition, no_paid_plan_or_credits, no_recent_activity, no_task_activity, no_personal_sources, wake_gate, wake_limit, rate_limited, misfire, task_busy, account_at_capacity, member_credit_cap, agent_archived, null delivered, not_delivered, not_requested, unknown How the agent closed a completed run: verified (it re-checked the result), recorded (it reported without re-checking), or recovered (it never reported; summary is its last message). Null unless an agent turn completed the run.
verified, recorded, recovered, null scheduled, event, manual The event that started this run, {type, data}, exactly as the run received it; data matches the event's webhook payload. Null for a run no event started. POST /task_runs/{id}/replay runs the task again on it.
The run (trun_...) whose event this run replays. Null unless started by POST /task_runs/{id}/replay.
The agent's final reply, once the run settled. Present on single-run responses, not in lists.
The reply parsed and validated against the response_format the run was started with. Null when none was given or it did not validate.
Why the reply did not parse or validate against response_format.

