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

# Sessions

> A session is an isolated compute environment where tasks are executed.

A session is an isolated compute environment where Deck executes tasks. Sessions are created automatically when you run a task, or you can reuse an existing session to run multiple tasks in the same environment.

## How sessions fit in

When you [run a task](/concepts/task-runs), Deck creates a session (or reuses one you specify) and executes the work. The session manages the compute lifecycle so your application doesn't have to.

## Session lifecycle

Sessions are created implicitly when a task runs. You don't need to create them ahead of time. The response includes a `session_id` you can reuse.

## Reusing a session

To run additional tasks in the same session, pass the `session_id` from a previous task run:

**POST /v2/tasks/`{task_id}`/run**

```json theme={null}
{
  "session_id": "sess_x9y8z7...",
  "input": {
    "check_in_date": "2026-05-01"
  }
}
```

Reusing a session runs the task in an already-open environment. This is faster and preserves any state from previous tasks.

## Session statuses

| Status       | Meaning                                      |
| ------------ | -------------------------------------------- |
| `queued`     | Waiting to be provisioned                    |
| `running`    | Active and executing work                    |
| `idle`       | No active tasks, waiting for new work        |
| `completing` | Work is done, session is shutting down       |
| `completed`  | All work finished and the session was closed |
| `failed`     | The session encountered an error             |

## Timeout

Sessions time out after **10 minutes of inactivity**. Inactivity means no task runs are executing in the session. When the timeout elapses, the session is torn down automatically and transitions to `completed`.

To keep a session alive across multiple tasks, start the next run before the 10-minute window elapses.

## Ending a session

```text theme={null}
POST /v2/sessions/{session_id}/end
```

This tears down the agent sandbox and transitions the session to `completed`. Any running task runs in the session will be canceled.

## When to reuse sessions

Reuse a session when you need to run multiple tasks for the same user in quick succession. A common pattern is to run a task and then immediately follow up with related tasks in the same session.