Delete a session

DELETE /v1/sessions/{session_id}

Permanently deletes a session and its data.

Deleting removes the session’s task in the Context app and the tasks of its subagents, with their events and transcripts. It also removes the session’s inputs/ copies and outputs, its sandbox and saved workspace, its LLM traces, and the memories its runs saved. The session no longer appears in the task history in the Context app, and any open stream on the session ends. Response lists what stays.

Delete a session with the owner’s personal key or with the service account key that created it. Keys don’t have sessions:delete by default. The key’s owner must grant it when creating the key, and an existing key can’t gain it.

Nothing deletes a session for you. Your deployment keeps a session and its history until you delete it with this request, and archiving a session keeps its history too.

If a turn is running, the request returns 409 and the turn keeps running. Send a user.interrupt, wait for the session to go idle, then delete it. A session waiting for a tool approval counts as idle. If another change to the session is in progress, for example an event you sent, the delete can return 409. The session still exists, but its traces, saved workspace and recordings may already be deleted. Retry the delete. Files you uploaded with Upload a file are kept. Delete them with Delete a file.

The key must have the sessions:delete capability. For what each capability allows, see Keys.

Path parameters

Name	Type	Required	Default	Description
`session_id`	`string`	Yes		The ID of the session to delete.

Response

Returns 200 with a receipt whose type is session_deleted.

removed counts what was deleted:

Field	What it counts
`tasks`	The session’s task and its subagents’ tasks.
`runs`	The runs of those tasks, with their events, transcripts and state.
`sandboxes`	The sandboxes the runs still held, now shut down.
`dispatch_rows_scrubbed`	Dispatch history rows whose prompt, title and output text were cleared.
`approval_previews_purged`	Approval cards whose preview of the action’s content was cleared.
`billing_events_unlinked`	Billing usage rows whose link to the session’s runs was cleared.
`agent_memories_deleted`	Memories the session’s runs saved.
`traces`	`deleted`, or `no_trace_store` when your deployment keeps no traces.

kept lists each store that stays, with a store and a reason:

`store`	What stays
`billing_meter_events`	Billing usage and each run’s billed cost, kept for invoicing. They hold counts and prices, not conversation content.
`audit_log`	Audit records of who did what, when, and with what outcome.
`dispatch_ledger_rows`	Dispatch history, with its prompt, title and output text cleared and its task link removed.
`uploaded_files`	Files uploaded with Upload a file. The session’s own copy in its `inputs/` folder is deleted.
`agent_memory_notes`	Notes in the agent’s own `.memory` folder in Drive. They belong to the agent and aren’t linked to any run. Memories the session’s runs saved are deleted.
`storage_residue`	Deleted data that storage keeps for a while: trace rows until the trace store’s next merge, and earlier versions of removed files on storage that keeps versions, until they expire. No API returns them.

{
  "id": "dd13d728-93e3-440a-874c-4efeb58c97e0",
  "type": "session_deleted",
  "removed": {
    "tasks": 1,
    "runs": 1,
    "sandboxes": 1,
    "dispatch_rows_scrubbed": 1,
    "approval_previews_purged": 0,
    "billing_events_unlinked": 2,
    "agent_memories_deleted": 3,
    "traces": "deleted"
  },
  "kept": [
    {
      "store": "billing_meter_events",
      "reason": "..."
    },
    {
      "store": "audit_log",
      "reason": "..."
    },
    {
      "store": "dispatch_ledger_rows",
      "reason": "..."
    },
    {
      "store": "uploaded_files",
      "reason": "..."
    },
    {
      "store": "agent_memory_notes",
      "reason": "..."
    },
    {
      "store": "storage_residue",
      "reason": "..."
    }
  ]
}

Errors

This endpoint can return these errors as well as the common errors.

Status	`error.type`	Cause and fix
400	`invalid_request_error`	The request sends a query parameter. Remove it.
403	`permission_error`	The key lacks `sessions:delete`. Create a key that has `sessions:delete`. Only the key’s owner can grant it.
403	`permission_error`	The key doesn’t act for the session’s owner. Use the owner’s personal key or the service account key that created the session.
403	`permission_error`	The session’s owner doesn’t have permission to delete it in the Context app, or is no longer an active member. No key can delete the session in that case.
404	`not_found_error`	No session with this ID exists, it is already deleted, or this key can’t read it. Check the session ID.
409	`invalid_request_error`	A turn is running. Send a `user.interrupt`, wait until the session is idle, then delete it.
409	`invalid_request_error`	Another change to the session was in progress. The session still exists, but its traces, saved workspace and recordings may already be deleted. Retry the delete.
500	`api_error`	The session’s traces couldn’t be removed, so the session wasn’t deleted. Retry the delete.

Example

curl -sS -X DELETE "$CONTEXT_BASE_URL/v1/sessions/dd13d728-93e3-440a-874c-4efeb58c97e0" -H "x-api-key: $CONTEXT_API_KEY"

deleted = client.beta.sessions.delete("dd13d728-93e3-440a-874c-4efeb58c97e0")
print(deleted.type, deleted.removed)  # session_deleted {'tasks': 1, ...}

const deleted = await client.beta.sessions.delete("dd13d728-93e3-440a-874c-4efeb58c97e0")
console.log(deleted.type) // "session_deleted"; removed and kept are not in the SDK's types