Skip to main content
A task run is what happens when you execute a task. Provide the task input, and Deck assigns an agent, runs the work, and returns structured output.

​
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 to task_run.completed or task_run.failed events to know when it finishes.

​
Task run statuses

​
Timeouts

Every task has a timeout that bounds the total wall-clock runtime of each run. If a run doesn’t finish within the window, it hard-stops and fails with a timeout error. Set the timeout per task with settings.timeout_seconds, a positive integer in seconds. If you don’t set one, the task uses your plan’s default timeout. The maximum you can set is determined by your plan — see pricing for the cap on each tier — and the overall ceiling is 8 hours (28800 seconds). Requesting a timeout above your plan’s maximum is rejected when you create or update the task with a 422 timeout_exceeds_plan_max error; a non-positive value is rejected with invalid_field_value. See run timeout for how to configure it on a task. When a run times out, the errors array contains:

​
Output and errors

On success, the output 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. Some sources use antibot defenses that can cause a run to fail with a blocked error. Detection can vary across runs on the same source, so handle this error gracefully. See stealth mode for details.

​
Including additional data

The default task run response returns core fields only. Use the include query parameter on GET /v2/task-runs/{run_id} to add optional data: Comma-separated values are supported:

​
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

The run transitions to canceling while the agent stops execution, then to canceled once complete. You can cancel a run any time before it reaches a terminal state (completed, canceled, or failed), including while it’s queued, running, or interaction_required.