# Sessions (/concepts/sessions)



A **session** is the home for a single agent workflow over time. It holds a stable prefix of [bundles](/concepts/bundles), one or more [branches](/concepts/branches) of history, and the events those branches accumulate as the agent works.

The most important thing to understand about a session is what it is *not*.

<Warning>
  A session is not a cache entry. It is a causal state container. A cache entry is a physical optimization that can be discarded at any time; a session is durable customer state with lineage, ordering, and deletion semantics. The two live in different [identity layers](/concepts/identity-model).
</Warning>

## Shape [#shape]

```json
{
  "id": "ses_01jy...",
  "object": "session",
  "project_id": "prj_01jy...",
  "default_branch_id": "br_01jy...",
  "status": "active",
  "base_bundle_ids": ["bnd_agent_prefix"],
  "created_at": "2026-06-09T20:15:00Z"
}
```

* `base_bundle_ids` are the stable prefix bundles every branch inherits.
* `default_branch_id` is where events land unless you target another branch.
* `status` is one of `active`, `archived`, or `tombstoned`.

## Mutable metadata, immutable content [#mutable-metadata-immutable-content]

A session's *metadata* is mutable: status changes, labels, the set of base bundles can evolve. But the *content* it points at is immutable. The bundles are immutable, the events on its branches are immutable, and history only ever grows by appending. You change what a session is doing, never what it already did.

This split is deliberate. It means a session can be a long-lived, evolving object while every individual fact inside it stays fixed and auditable. When you later [purge](/concepts/retention-and-purge) a session, there is a precise, ordered set of immutable records to remove.

## How the pieces fit [#how-the-pieces-fit]

<Steps>
  <Step title="Create a session over your stable prefix">
    Attach the bundles that hold your system policy, tools, and schema as `base_bundle_ids`. These form the cacheable front of every request in the session.
  </Step>

  <Step title="Work on a branch">
    A session always has at least a default branch. Each turn appends an immutable event - a user message, a tool result, an assistant message - to a branch.
  </Step>

  <Step title="Compile a snapshot per request">
    When you generate, the platform compiles a [snapshot](/concepts/snapshots) of the branch head: the ordered logical state the model will see. A response pins exactly one snapshot.
  </Step>
</Steps>

## Why sessions raise your reuse [#why-sessions-raise-your-reuse]

Because a session keeps stable bundles separate from changing events, the platform can recognize the recurring prefix family across every turn. That recurrence is exactly what [reuse metrics](/concepts/reuse-metrics) measure and what drives the `session_continuity` component of the [Workload Reuse Score](/concepts/workload-reuse-score). Traffic that belongs to multi-turn sessions is, almost by definition, traffic with reuse to capture.

<CardGroup cols="2">
  <Card title="Branches" icon="code-branch" href="/concepts/branches">
    How history grows safely under concurrency.
  </Card>

  <Card title="Sessions and branching" icon="comments" href="/guides/sessions-and-branching">
    Build a multi-turn agent on `/v2`.
  </Card>
</CardGroup>