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

# Task runs

> A task run is a single execution of a task.

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](/concepts/tasks) to a [session](/concepts/sessions). 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](/concepts/credentials) to authenticate the session. Runs emit [events](/events/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

| 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 is paused waiting for you to approve it before continuing |
| `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

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](https://deck.co/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:

```json theme={null}
{
  "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](/api/errors) 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](/platform/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:

| Value       | What it adds                                          |
| ----------- | ----------------------------------------------------- |
| `input`     | The input passed when the task was run                |
| `storage`   | Files captured during execution, with extraction data |
| `artifacts` | Screenshots taken during execution                    |

Comma-separated values are supported:

```bash theme={null}
GET /v2/task-runs/{run_id}?include=input,storage,artifacts
```

## 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

```text theme={null}
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.