One change
List Session Threads
api/beta/sessions/threads/list
Nearest release: v2.1.245, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
api/beta/sessions/threads/list Changed · +93 / -128 lines
# List Session Threads ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Session Threads ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
---- -title: List Session Threads -url: https://platform.claude.com/docs/en/api/beta/sessions/threads/list ---- +# List Session Threads -## List Session Threads +**GET** `/v1/sessions/{session_id}/threads` -**get** `/v1/sessions/{session_id}/threads` - List Session Threads -### Path Parameters +## Path parameters - `session_id: string` -### Query Parameters +## Query parameters - `limit: optional number` Maximum results per page. Defaults to 1000. + format: int32 + - `page: optional string` Opaque pagination cursor from a previous response's next_page. Forward-only. -### Header Parameters +## Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 98
- `"mid-conversation-tool-changes-2026-07-01"` -### Returns +## Returns - `data: optional array of BetaManagedAgentsSessionThread`
from line 112
A session-resolved multiagent roster entry. - - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }` + - `BetaManagedAgentsSessionThreadAgent object` 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`.
from line 126
- `type: "url"` - - `"url"` - - `url: string` - `model: BetaManagedAgentsModelConfig`
from line 202
How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes. - - `BetaManagedAgentsEffortLow object { type }` + - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - - `"low"` + - `BetaManagedAgentsEffortMedium object` - - `BetaManagedAgentsEffortMedium object { type }` - Medium effort. Balances latency and reasoning depth. - `type: "medium"` - - `"medium"` + - `BetaManagedAgentsEffortHigh object` - - `BetaManagedAgentsEffortHigh object { type }` - High effort. Favors reasoning depth. - `type: "high"` - - `"high"` + - `BetaManagedAgentsEffortXhigh object` - - `BetaManagedAgentsEffortXhigh object { type }` - Extra-high effort. Not all models accept this level. - `type: "xhigh"` - - `"xhigh"` + - `BetaManagedAgentsEffortMax object` - - `BetaManagedAgentsEffortMax object { type }` - Maximum effort. Favors reasoning depth over latency. - `type: "max"` - - `"max"` - - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 248
- `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }` + - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill.
from line 256
- `type: "anthropic"` - - `"anthropic"` - - `version: string` - - `BetaManagedAgentsCustomSkill object { skill_id, type, version }` + - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill.
from line 266
- `type: "custom"` - - `"custom"` - - `version: string` - `system: string or null`
from line 272
- `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }` + - `BetaManagedAgentsAgentToolset20260401 object` - `configs: array of BetaManagedAgentsAgentToolConfig` - - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool.
from line 284
- `name: "bash"` - - `"bash"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - - `"always_allow"` + - `BetaManagedAgentsAlwaysAskPolicy object` - - `BetaManagedAgentsAlwaysAskPolicy object { type }` - Tool calls require user confirmation before execution. - `type: "always_ask"` - - `"always_ask"` - - `type: "bash"` - - `"bash"` + - `BetaManagedAgentsEditToolConfig object` - - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }` - Configuration for the edit tool. - `enabled: boolean`
from line 310
- `name: "edit"` - - `"edit"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "edit"` - - `"edit"` + - `BetaManagedAgentsReadToolConfig object` - - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }` - Configuration for the read tool. - `enabled: boolean`
from line 332
- `name: "read"` - - `"read"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "read"` - - `"read"` + - `BetaManagedAgentsWriteToolConfig object` - - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }` - Configuration for the write tool. - `enabled: boolean`
from line 354
- `name: "write"` - - `"write"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "write"` - - `"write"` + - `BetaManagedAgentsGlobToolConfig object` - - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }` - Configuration for the glob tool. - `enabled: boolean`
from line 376
- `name: "glob"` - - `"glob"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "glob"` - - `"glob"` + - `BetaManagedAgentsGrepToolConfig object` - - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }` - Configuration for the grep tool. - `enabled: boolean`
from line 398
- `name: "grep"` - - `"grep"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "grep"` - - `"grep"` + - `BetaManagedAgentsWebFetchToolConfig object` - - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }` - Configuration for the web_fetch tool. - `enabled: boolean`
from line 420
- `name: "web_fetch"` - - `"web_fetch"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "web_fetch"` - - `"web_fetch"` - - `allowed_domains: optional array of string` - `blocked_domains: optional array of string`
from line 440
- `max_content_tokens: optional number or null` - - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }` + format: int32 + - `BetaManagedAgentsWebSearchToolConfig object` + Configuration for the web_search tool. - `enabled: boolean`
from line 450
- `name: "web_search"` - - `"web_search"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "web_search"` - - `"web_search"` - - `allowed_domains: optional array of string` - `blocked_domains: optional array of string`
from line 476
Location precision. Only "approximate" is supported. - - `"approximate"` - - `city: optional string or null` City name. + minLength: 1, maxLength: 255 + - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase.
from line 490
Region or state name. + minLength: 1, maxLength: 255 + - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". + minLength: 1, maxLength: 255 + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools.
from line 508
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - - `"agent_toolset_20260401"` + - `BetaManagedAgentsMCPToolset object` - - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }` - - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean`
from line 530
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution.
from line 548
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution.
from line 560
- `type: "mcp_toolset"` - - `"mcp_toolset"` + - `BetaManagedAgentsCustomTool object` - - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }` - A custom tool as returned in API responses. - `description: string`
from line 572
- `type: "object"` - - `"object"` - - `properties: optional map[unknown] or null` - `required: optional array of string or null`
from line 580
- `type: "custom"` - - `"custom"` - - `type: "agent"` - - `"agent"` - - `version: number` - - `BetaManagedAgentsAdvisor object { model, type }` + format: int32 + - `BetaManagedAgentsAdvisor object` + Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `model: string`
from line 596
- `type: "advisor"` - - `"advisor"` - - `archived_at: string or null` A timestamp in RFC 3339 format + format: date-time + - `created_at: string` A timestamp in RFC 3339 format + format: date-time + - `parent_thread_id: string or null` Parent thread that spawned this thread. Null for the primary thread.
from line 624
Cumulative time in seconds the thread spent actively running. Excludes idle time. + format: double + - `duration_seconds: optional number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. + format: double + - `startup_seconds: optional number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. + format: double + - `status: BetaManagedAgentsSessionThreadStatus` SessionThreadStatus enum
from line 652
- `type: "session_thread"` - - `"session_thread"` - - `updated_at: string` A timestamp in RFC 3339 format + format: date-time + - `usage: BetaManagedAgentsSessionThreadUsage or null` Cumulative token usage for a session thread across all turns.
from line 666
Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on. + format: double + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime.
from line 676
Tokens used to create 1-hour ephemeral cache entries. + format: int32 + - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. + format: int32 + - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. + format: int32 + - `input_tokens: optional number` Total input tokens consumed across all turns. + format: int32 + - `list_cost: optional BetaMonetaryAmount or null` A monetary amount in a specific currency.
from line 708
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. - - `"USD"` - - `output_tokens: optional number` Total output tokens generated across all turns. + format: int32 + - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative count of server-executed tool invocations, broken down by tool.
from line 722
Number of server-executed web fetch requests. + format: int32 + - `web_search_requests: optional number` Number of server-executed web search requests. + format: int32 + - `next_page: optional string or null` Opaque cursor for the next page. Null when no more results. -### Example +## Example -```http +```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 743
-H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +### Response (200) ```json {