Skip to main content
A task run is what happens when you execute a task. Provide a connection and 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 connection. The task defines what to do, the connection provides the authenticated session, and the task run is the execution. Runs emit events throughout their lifecycle so your application can react in real time.

​
Running a task

POST /v2/tasks/{task_id}/run

{
  "connection_id": "conn_a1b2c3d4...",
  "input": {
    "check_in_date": "2025-02-01"
  }
}
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 agent
runningThe agent is executing the task on the source
pendingWaiting for human approval, review, or intervention before completing
interaction_requiredThe source is asking for user input (MFA, verification)
completedFinished successfully. Output is available in the output field.
failedSomething went wrong. Check the errors array for details.
canceledYou canceled the run before it completed.

​
Timeouts

Each task has a configurable timeout. If the agent doesn’t complete within that window, the run fails. Runs also auto-timeout after 30 minutes of inactivity if the agent gets stuck.

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

​
Interactions

Task runs can pause for user input if the source requires verification during execution. The flow is the same as connection interactions. Collect the response from your user and submit it to resume.

​
Canceling a run

POST /v2/task-runs/{task_run_id}/cancel
The run transitions to canceled and the agent stops execution. You can cancel a run in pending, queued, or running status.