Claude Platform Docs

List Sessions

GET/v1/sessions

List Sessions

Query parameters
agent_id: optional string

Filter sessions created with this agent ID.

agent_version: optional number

Filter by agent version. Only applies when agent_id is also set.

formatint32
"created_at[gt]": optional string

Return sessions created after this time (exclusive).

formatdate-time
"created_at[gte]": optional string

Return sessions created at or after this time (inclusive).

formatdate-time
"created_at[lt]": optional string

Return sessions created before this time (exclusive).

formatdate-time
"created_at[lte]": optional string

Return sessions created at or before this time (inclusive).

formatdate-time
deployment_id: optional string

Filter sessions created by this deployment ID.

include_archived: optional boolean

When true, includes archived sessions. Default: false (exclude archived).

limit: optional number

Maximum number of results to return.

formatint32
memory_store_id: optional string

Filter sessions whose resources contain a memory_store with this memory store ID.

order: optional "asc" or "desc"

Sort direction for results, ordered by created_at. Defaults to desc (newest first).

One of the following:
"asc"
"desc"
page: optional string

Opaque pagination cursor from a previous response.

statuses: optional array of "rescheduling" or "running" or "idle" or "terminated"

Filter by session status. Repeat the parameter to match any of multiple statuses.

One of the following:
"rescheduling"

Transient error occurred, retrying automatically.

"running"

Agent is actively executing.

"idle"

Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle.

"terminated"

Session has ended, either due to an error or completion.

Headers
"anthropic-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.

One of the following:
string
"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more
One of the following:
"message-batches-2024-09-24"
"prompt-caching-2024-07-31"
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"pdfs-2024-09-25"
"token-counting-2024-11-01"
"token-efficient-tools-2025-02-19"
"output-128k-2025-02-19"
"files-api-2025-04-14"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"extended-cache-ttl-2025-04-11"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"skills-2025-10-02"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"cache-diagnosis-2026-04-07"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"ce-user-management-2026-07-13"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"anthropic-workspace-id": optional string

Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).

Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

Returns
data: optional array of BetaManagedAgentsSession { type: "session", id, agent, 14 more }

List of sessions.

type: "session"
id: string
agent: BetaManagedAgentsSessionAgent { type: "agent", id, description, 8 more }

Resolved agent definition for a session. Snapshot of the agent at session creation time.

archived_at: string or null

A timestamp in RFC 3339 format

formatdate-time
budget: BetaManagedAgentsBudgetLimit { type: "limit", max_list_cost } or null

A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.

type: "limit"
max_list_cost: BetaMonetaryAmount { amount, currency }

A monetary amount in a specific currency.

amount: string

Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

currency: BetaCurrency

Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

created_at: string

A timestamp in RFC 3339 format

formatdate-time
environment_id: string
metadata: map[string]
outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource { type: "outcome_evaluation", completed_at, description, 4 more }

Per-outcome evaluation state. One entry per define_outcome event sent to the session.

type: "outcome_evaluation"
completed_at: string or null

A timestamp in RFC 3339 format

formatdate-time
description: string

What the agent should produce.

explanation: string or null

Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.

iteration: number

0-indexed revision cycle the outcome is currently on.

formatint32
outcome_id: string

Server-generated outc_ ID for this outcome.

result: string

Current evaluation state. pending before the agent begins work; running while producing or revising; evaluating while the grader scores; satisfied/max_iterations_reached/failed/interrupted are terminal.

resources: array of BetaManagedAgentsSessionResource
One of the following:
BetaManagedAgentsGitHubRepositoryResource object{ type: "github_repository", id, created_at, 4 more }
BetaManagedAgentsFileResource object{ type: "file", id, created_at, 3 more }
type: "file"
id: string
created_at: string

A timestamp in RFC 3339 format

formatdate-time
file_id: string
mount_path: string
updated_at: string

A timestamp in RFC 3339 format

formatdate-time
BetaManagedAgentsMemoryStoreResource object{ type: "memory_store", memory_store_id, access, 4 more }

A memory store attached to an agent session.

stats: BetaManagedAgentsSessionStats { active_seconds, duration_seconds }

Timing statistics for a session.

active_seconds: optional number

Cumulative time in seconds the session spent in running status. Excludes idle time.

formatdouble
duration_seconds: optional number

Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

formatdouble
status: "rescheduling" or "running" or "idle" or "terminated"

SessionStatus enum

One of the following:
"rescheduling"

Transient error occurred, retrying automatically.

"running"

Agent is actively executing.

"idle"

Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle.

"terminated"

Session has ended, either due to an error or completion.

title: string or null
updated_at: string

A timestamp in RFC 3339 format

formatdate-time
usage: BetaManagedAgentsSessionUsage { active_seconds, cache_creation, cache_read_input_tokens, 4 more }

Cumulative token usage for a session across all turns.

vault_ids: array of string

Vault IDs attached to the session at creation. Empty when no vaults were supplied.

deployment_id: optional string or null

Deployment ID when the session was created from a deployment reference. Null otherwise.

next_page: optional string or null

Opaque cursor for the next page. Null when no more results.

prev_page: optional string or null

Opaque cursor for the previous page. Null when on the first page. Pass as the page parameter to navigate backward.

List Sessions
curl https://api.anthropic.com/v1/sessions \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"
Returns Examples
Response 200
{
  "data": [
    {
      "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
      "agent": {
        "id": "agent_011CZkYpogX7uDKUyvBTophP",
        "description": "A general-purpose starter agent.",
        "mcp_servers": [
          {
            "name": "example-mcp",
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse"
          }
        ],
        "model": {
          "id": "claude-opus-5",
          "effort": {
            "type": "low"
          },
          "inference_geo": "inference_geo",
          "speed": "standard"
        },
        "multiagent": {
          "agents": [
            {
              "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
              "description": "A focused research subagent.",
              "mcp_servers": [
                {
                  "name": "example-mcp",
                  "type": "url",
                  "url": "https://example-server.modelcontextprotocol.io/sse"
                }
              ],
              "model": {
                "id": "claude-opus-5",
                "effort": {
                  "type": "low"
                },
                "inference_geo": "inference_geo",
                "speed": "standard"
              },
              "name": "Researcher",
              "skills": [
                {
                  "skill_id": "xlsx",
                  "type": "anthropic",
                  "version": "1"
                }
              ],
              "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
              "tools": [
                {
                  "configs": [
                    {
                      "enabled": true,
                      "name": "bash",
                      "permission_policy": {
                        "type": "always_allow"
                      },
                      "type": "bash"
                    }
                  ],
                  "default_config": {
                    "enabled": true,
                    "permission_policy": {
                      "type": "always_ask"
                    }
                  },
                  "type": "agent_toolset_20260401"
                }
              ],
              "type": "agent",
              "version": 1
            }
          ],
          "type": "coordinator"
        },
        "name": "My First Agent",
        "skills": [
          {
            "skill_id": "xlsx",
            "type": "anthropic",
            "version": "1"
          },
          {
            "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
            "type": "custom",
            "version": "2"
          }
        ],
        "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
        "tools": [
          {
            "configs": [
              {
                "enabled": true,
                "name": "bash",
                "permission_policy": {
                  "type": "always_allow"
                },
                "type": "bash"
              }
            ],
            "default_config": {
              "enabled": true,
              "permission_policy": {
                "type": "always_ask"
              }
            },
            "type": "agent_toolset_20260401"
          }
        ],
        "type": "agent",
        "version": 1
      },
      "archived_at": null,
      "budget": {
        "max_list_cost": {
          "amount": "2500",
          "currency": "USD"
        },
        "type": "limit"
      },
      "created_at": "2026-03-15T10:00:00Z",
      "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
      "metadata": {},
      "outcome_evaluations": [
        {
          "completed_at": "2026-03-15T10:02:31Z",
          "description": "Produce a 2-page summary as summary.md",
          "explanation": "All five sections present with inline citations.",
          "iteration": 0,
          "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
          "result": "satisfied",
          "type": "outcome_evaluation"
        }
      ],
      "resources": [
        {
          "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
          "created_at": "2026-03-15T10:00:00Z",
          "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
          "mount_path": "/uploads/receipt.pdf",
          "type": "file",
          "updated_at": "2026-03-15T10:00:00Z"
        },
        {
          "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
          "created_at": "2026-03-15T10:00:00Z",
          "mount_path": "/workspace/example-repo",
          "type": "github_repository",
          "updated_at": "2026-03-15T10:00:00Z",
          "url": "https://github.com/example-org/example-repo",
          "checkout": {
            "name": "main",
            "type": "branch"
          }
        }
      ],
      "stats": {
        "active_seconds": 0,
        "duration_seconds": 0
      },
      "status": "idle",
      "title": "Order #1234 inquiry",
      "type": "session",
      "updated_at": "2026-03-15T10:00:00Z",
      "usage": {
        "active_seconds": 0,
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 0
        },
        "cache_read_input_tokens": 0,
        "input_tokens": 0,
        "list_cost": {
          "amount": "2500",
          "currency": "USD"
        },
        "output_tokens": 0,
        "server_tool_use": {
          "web_fetch_requests": 0,
          "web_search_requests": 3
        }
      },
      "vault_ids": [
        "vlt_011CZkZDLs7fYzm1hXNPeRjv"
      ],
      "deployment_id": "deployment_id"
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=",
  "prev_page": "page_MjAyNS0wNS0xM1QwMDowMDowMFo="
}