How task runs fit in
A task run ties a task to a session. The task defines what to do, the session is the compute environment, and the task run is the execution. You can optionally pass a credential to authenticate the session. Runs emit events throughout their lifecycle so your application can react in real time.Running a task
Execution is asynchronous. Subscribe totask_run.completed or task_run.failed events to know when it finishes.
Task run statuses
| Status | Meaning |
|---|---|
queued | Waiting for an available session |
running | The agent is executing the task on the source |
interaction_required | The source is asking for user input (MFA, verification) |
review_required | The run has finished execution and is waiting for review before completing |
completed | Finished successfully. Output is available in the output field. |
failed | Something went wrong. Check the errors array for details. |
canceling | Cancellation requested, the agent is stopping execution. |
canceled | You canceled the run before it completed. |
Timeouts
Runs auto-timeout after 30 minutes of inactivity if the agent gets stuck. If the agent doesn’t complete within that window, the run fails.Output and errors
On success, theoutput field contains structured JSON matching the task’s output schema. On failure, the errors array contains one or more error objects with type, code, and message. See API error handling for the full reference.
Including additional data
The default task run response returns core fields only. Use theinclude query parameter on GET /v2/task-runs/{run_id} to add optional data:
| Value | What it adds |
|---|---|
input | The input passed when the task was run |
storage | Files captured during execution, with extraction data |
screenshots | Screenshots taken during execution |
Interactions
Task runs can pause for user input if the source requires verification during execution. Collect the response from your user and submit it to resume.Canceling a run
canceling while the agent stops execution, then to canceled once complete. You can cancel a run in queued or running status.