> ## 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`, 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](https://deck.co/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](/concepts/tasks#run-timeout) for how to configure it on a task.

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                                                                |
| `storage_deduplicated` | Files skipped by [deduplication](/guides/storage#deduplication). Only returned for tasks with deduplication enabled. |
| `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 any time before it reaches a terminal state (`completed`, `canceled`, or `failed`), including while it's `queued`, `running`, or `interaction_required`.