Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.deck.co/llms.txt

Use this file to discover all available pages before exploring further.

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

StatusMeaning
queuedWaiting for an available session
runningThe agent is executing the task on the source
interaction_requiredThe source is asking for user input (MFA, verification)
review_requiredThe run has finished execution and is waiting for review before completing
completedFinished successfully. Output is available in the output field.
failedSomething went wrong. Check the errors array for details.
cancelingCancellation requested, the agent is stopping execution.
canceledYou canceled the run before it completed.

​
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. If you don’t specify one, Deck defaults to 30 minutes. The maximum depends on your plan — see pricing for the cap on each tier. Task creation is rejected if the requested timeout exceeds your plan’s cap. When a run times out, the errors array contains: 
{
  "errors": [
    {
      "type": "task",
      "code": "timeout",
      "message": "Task execution exceeded the timeout of X minutes."
    }
  ]
}

​
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.

​
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:
ValueWhat it adds
inputThe input passed when the task was run
storageFiles captured during execution, with extraction data
screenshotsScreenshots taken during execution
Comma-separated values are supported: 
GET /v2/task-runs/{run_id}?include=input,storage,screenshots

​
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

POST /v2/task-runs/{run_id}/cancel
The run transitions to canceling while the agent stops execution, then to canceled once complete. You can cancel a run in queued or running status.