Sessions

A session is one conversation with an agent. Each session is a task in the Context app. The owner of the key that created it owns the task. A service account key can name another member as the owner with the x-context-owner-user-id or x-context-owner-user-email header. The task has the same transcript and tool permissions as a task started in the app. A session ends when you archive it, and its history stays readable. Nothing deletes a session for you: your deployment keeps it until you delete it. To remove a session and its data permanently, delete it with a key that has sessions:delete, which keys don’t have by default (see Choosing a key). To send messages to a session and stream the agent’s replies, see Events.

Endpoints

Endpoint	What it does
`POST /v1/sessions`	Creates a session for an agent, optionally with files and a first message.
`GET /v1/sessions`	Lists the sessions this key can see, newest first.
`GET /v1/sessions/{session_id}`	Returns a session with its status and token totals.
`POST /v1/sessions/{session_id}`	Changes a session’s title and returns the updated session.
`POST /v1/sessions/{session_id}/archive`	Ends a session permanently. Its history stays readable.
`DELETE /v1/sessions/{session_id}`	Permanently deletes a session and its data.

Status

`status`	Meaning
`idle`	The session is waiting for a message or a tool approval, or hasn’t started.
`running`	A turn is in progress.
`terminated`	The session is archived. Nothing else terminates a session.
`rescheduling`	This status is never returned. List sessions accepts it as a `statuses` filter, which then matches nothing.

The session object

Field	Type	Description
`id`	`string`	The session’s ID, a UUID. It is also the task’s ID in the app.
`type`	`string`	Always `session`.
`status`	`string`	The session’s status. One of `idle`, `running` or `terminated`. See Status.
`title`	`string \| null`	The session’s title. The maximum length is 280 characters.
`agent`	`object`	The agent the session runs, as in Agents without its timestamps and `metadata`.
`environment_id`	`string`	Where the session runs: `env_default`. See Environments.
`resources`	`array<object>`	The files attached when the session was created, each `{id, type: "file", file_id, mount_path, created_at, updated_at}`. If you sent a `mount_path`, this is the file’s absolute path on the agent’s disk. Otherwise it is `inputs/<filename>`, in the session’s `inputs/` folder. `id` equals `file_id`.
`usage`	`object`	The totals for the whole session, subagents included: `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation`, `active_seconds` and `list_cost`.
`usage.cache_creation`	`object`	Cache-write tokens, as `{ephemeral_5m_input_tokens, ephemeral_1h_input_tokens}`. `ephemeral_1h_input_tokens` is always `0`, because every cache write counts as a 5-minute write.
`usage.active_seconds`	`number`	The seconds the session spent working, to the millisecond. Time spent waiting for a tool approval isn’t counted. While a turn runs, the value grows on every read.
`usage.list_cost`	`object \| null`	The session’s cost at list price, as `{amount, currency: "USD"}`. `amount` is a whole number of cents, as a string. It covers model calls plus web search, image search and media generation, priced for the session’s owner. See the list below the table for when it is `null`.
`created_at`	`string`	When the session was created, as an RFC 3339 timestamp.
`updated_at`	`string`	When the session last changed, as an RFC 3339 timestamp.
`archived_at`	`string \| null`	For an archived session, the time it last changed, as an RFC 3339 timestamp. That is when it was archived, unless it was renamed after, which sets it to the time of the rename. `null` for a session that isn’t archived.

usage.list_cost is null in these cases:

A turn is running. A cost shown earlier returns to null while a later turn runs.
Billing hasn’t settled, which takes about 12 minutes after the session goes idle.
No model call was made.
Your organization counts usage in tokens.

Once it appears, usage.list_cost can still rise. A model call made outside a turn, such as one by a background job the agent started, is added when billing records it.

Some fields always hold the same value: budget is null, metadata and stats are {}, and outcome_evaluations and vault_ids are empty.

{
  "id": "dd13d728-93e3-440a-874c-4efeb58c97e0",
  "agent": {
    "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60",
    "description": "Answers questions about the sales pipeline",
    "execution_identity": {
      "type": "service_account"
    },
    "mcp_servers": [],
    "model": {
      "id": "default"
    },
    "multiagent": null,
    "name": "Research Assistant",
    "skills": [],
    "system": null,
    "tools": [],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "budget": null,
  "created_at": "2026-10-21T01:42:16.079Z",
  "environment_id": "env_default",
  "metadata": {},
  "outcome_evaluations": [],
  "resources": [
    {
      "id": "329409ba-f288-4b44-9c73-14a18150edee",
      "created_at": "2026-10-21T01:41:11.028Z",
      "file_id": "329409ba-f288-4b44-9c73-14a18150edee",
      "mount_path": "inputs/cities.csv",
      "type": "file",
      "updated_at": "2026-10-21T01:41:11.028Z"
    }
  ],
  "stats": {},
  "status": "idle",
  "title": "Quarterly city report",
  "type": "session",
  "updated_at": "2026-10-21T01:42:29.719Z",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 318,
    "cache_read_input_tokens": 133496,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 2210,
      "ephemeral_1h_input_tokens": 0
    },
    "active_seconds": 7.331,
    "list_cost": {
      "amount": "6",
      "currency": "USD"
    }
  },
  "vault_ids": []
}

Differences from Anthropic’s API

This API follows Anthropic’s Managed Agents API, with these differences:

Deleting a session needs the sessions:delete capability, which keys don’t have by default. Deleting a session while a turn runs returns 409: interrupt the turn, wait for idle, then delete it. The delete response lists what was removed and what was kept. See Delete a session.
POST /v1/sessions takes x-context-owner-user-id or x-context-owner-user-email, so a service account key can create a session for another member. Anthropic’s API has no such headers.
POST /v1/sessions returns 400 if the request overrides an agent field (any field in the agent object besides type, id and version), or sends a non-empty metadata, a non-empty vault_ids or a non-null budget.
initial_events takes at most one event, a user.message. Anthropic’s API takes up to 50 events of different types.
Only file resources are supported. Any other type returns 400.
A file sent without mount_path isn’t placed on the agent’s disk. Anthropic’s API copies it to /mnt/session/uploads/<file_id>. Here it stays in the session’s inputs/ folder in Drive, where the agent reads it, and its mount_path reads inputs/<filename>.
mount_path takes a path under /workspace/ or /mnt/session/uploads/. Any other absolute path is placed under /mnt/session/uploads: /data/a.csv becomes /mnt/session/uploads/data/a.csv, and mount_path reports the new path.
usage.server_tool_use isn’t sent.
title takes up to 280 characters, and a session takes up to 50 files. Anthropic’s API allows 500 of each.
A list response holds at most 100 sessions per page. Anthropic’s API allows up to 1,000.
On list, order=asc and the agent_version, deployment_id and memory_store_id filters return 400.

For every difference in one place, see Coming from Anthropic’s API.