> ## 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](https://docs.deck.co/concepts/task-runs.md), 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.

You can also start one yourself with `POST /v2/sessions`, then pass its `session_id` to a task or workflow run. See [Preparing a session](#preparing-a-session).

## 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}
{
  "credential_id": "cred_a1b2c3d4...",
  "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. The run request still requires a `credential_id` or `source_id`; the session doesn't supply them. Runs in a session against the same source must use the same credential. To run against that source with a different credential, start a new session.

## Preparing a session

To cut latency on the first run, start the session before your user is ready and pass a `source_id`:

**POST /v2/sessions**

```json theme={null}
{
  "source_id": "src_a1b2c3d4..."
}
```

Deck starts the session and sends the agent to that source's login page. When the user submits their credentials, run the task or [workflow](https://docs.deck.co/guides/workflows.md#running-a-workflow) with the returned `session_id`, and the agent can start the login from there. A workflow run ends the session when it finishes.

The session object includes `source_id` when one was passed. An unknown `source_id` returns `source_not_found`.

`source_id` is a hint, not a constraint:

* A run on the session can target any source. If it targets a different one, it still runs in the prepared session and the agent navigates to the run's source. The session's `source_id` stays as passed.
* The run still requires its own `credential_id` or `source_id`.
* A prepared session counts toward your organization's session limit, and follows the same [timeout](#timeout) as any other. If no run arrives within 10 minutes, it closes. [End it](#ending-a-session) if your user leaves before running anything.

## Staying logged in across sessions

Sessions always start from a clean environment, so a new session normally means a fresh login. If the credential has [credential persistence](https://docs.deck.co/concepts/credentials.md#credential-persistence) enabled, Deck restores the credential's saved login state into the new session, and the agent can pick up already logged in when the source honors it. This is a credential setting, not a session one: the session lifecycle described on this page is unchanged.

## 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 requests teardown of the agent sandbox. The session doesn't close instantly: it transitions to `completing` and then to `completed` once teardown finishes. Any running task runs in the session are canceled as part of teardown.

You can only end a session that is `queued`, `running`, or `idle`. Ending a session that has already finished (`completed` or `failed`) returns an error.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.