Claude Platform Docs

List Session Threads

GET/v1/sessions/{session_id}/threads

List Session Threads

Path parameters
session_id: string
Query parameters
limit: optional number

Maximum results per page. Defaults to 1000.

formatint32
page: optional string

Opaque pagination cursor from a previous response's next_page. Forward-only.

statuses: optional array of BetaManagedAgentsSessionThreadStatus

Return only threads that have one of these statuses.

Repeat the parameter to give more than one status. Leave it out to return threads of every status.

One of the following:
"running"
"idle"
"rescheduling"
"terminated"
Headers
"anthropic-version": optional string
"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"
"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"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"ce-plugins-2026-09-01"
"spend-limit-reads-2026-09-26"
"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 BetaManagedAgentsSessionThread { type: "session_thread", id, agent, 9 more }

Threads in the session, primary first then children in spawn order.

type: "session_thread"
id: string

Unique identifier for this thread.

agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor or BetaManagedAgentsInlineAgent

Resolved agent definition for this thread. Snapshot of the agent at thread creation time.

One of the following:
BetaManagedAgentsSessionThreadAgent object{ type: "agent", id, description, 7 more }

Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.

BetaManagedAgentsAdvisor object{ type: "advisor", model }

Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

type: "advisor"
model: string

The advisor model id.

BetaManagedAgentsInlineAgent object{ type: "inline", description, mcp_servers, 5 more }

An agent that has no Agent resource, and so no id or version. It is defined inline, in a workflow run's plan or when a session thread is spawned, and is not saved.

archived_at: string or null

When the thread was archived. Null if not archived.

formatdate-time
created_at: string

When the thread was created.

formatdate-time
parent_thread_id: string or null

Parent thread that spawned this thread. Null for the primary thread.

session_id: string

The session this thread belongs to.

stats: BetaManagedAgentsSessionThreadStats { active_seconds, duration_seconds, startup_seconds } or null

Timing statistics for this thread. Null until the thread's first status transition.

active_seconds: optional number

Cumulative time in seconds the thread spent actively running. Excludes idle time.

formatdouble
duration_seconds: optional number

Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

formatdouble
startup_seconds: optional number

Time in seconds for the thread to begin running. Zero for child threads, which start immediately.

formatdouble
status: BetaManagedAgentsSessionThreadStatus

Current execution status of the thread.

One of the following:
"running"
"idle"
"rescheduling"
"terminated"
updated_at: string

When the thread was last updated.

formatdate-time
usage: BetaManagedAgentsSessionThreadUsage { active_seconds, cache_creation, cache_read_input_tokens, 4 more } or null

Cumulative token usage for this thread. Null until the thread's first idle transition.

workflow_run_id: string or null

Identifier of the workflow run that created the thread, or null for any other thread.

next_page: optional string or null

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

List Session Threads
curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads \
    -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": "sthr_011CZkZVWa6oJjw1rgXZpnBt",
      "agent": {
        "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
      },
      "archived_at": null,
      "created_at": "2026-03-15T10:00:00Z",
      "parent_thread_id": null,
      "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
      "stats": {
        "active_seconds": 0,
        "duration_seconds": 0,
        "startup_seconds": 0
      },
      "status": "idle",
      "type": "session_thread",
      "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
        }
      },
      "workflow_run_id": null
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}