One change
Get Session
api/beta/sessions/retrieve
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/retrieve Changed · +122 / -159 lines
# Get Session ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Session ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
---- -title: Get Session -url: https://platform.claude.com/docs/en/api/beta/sessions/retrieve ---- +# Get Session -## Get Session +**GET** `/v1/sessions/{session_id}` -**get** `/v1/sessions/{session_id}` - Get Session -### Path Parameters +## Path parameters - `session_id: string` -### Header Parameters +## Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 86
- `"mid-conversation-tool-changes-2026-07-01"` -### Returns +## Returns -- `BetaManagedAgentsSession object { id, agent, archived_at, 14 more }` +- `BetaManagedAgentsSession object` A Managed Agents `session`.
from line 108
- `type: "url"` - - `"url"` - - `url: string` - `model: BetaManagedAgentsModelConfig`
from line 184
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 234
Full `agent` definitions the coordinator may spawn as session threads. - - `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 258
- `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }` + - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill.
from line 266
- `type: "anthropic"` - - `"anthropic"` - - `version: string` - - `BetaManagedAgentsCustomSkill object { skill_id, type, version }` + - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill.
from line 276
- `type: "custom"` - - `"custom"` - - `version: string` - `system: string or null`
from line 282
- `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 294
- `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 320
- `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 342
- `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 364
- `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 386
- `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 408
- `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 430
- `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 450
- `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 460
- `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 486
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 500
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 518
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 540
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 558
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 570
- `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 582
- `type: "object"` - - `"object"` - - `properties: optional map[unknown] or null` - `required: optional array of string or null`
from line 590
- `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 606
- `type: "advisor"` - - `"advisor"` - - `type: "coordinator"` - - `"coordinator"` - - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }` + - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - - `BetaManagedAgentsCustomSkill object { skill_id, type, version }` + - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill.
from line 624
- `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }` + - `BetaManagedAgentsAgentToolset20260401 object` - - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }` + - `BetaManagedAgentsMCPToolset object` - - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }` + - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "agent"` - - `"agent"` - - `version: number` + format: int32 + - `archived_at: string or null` A timestamp in RFC 3339 format + format: date-time + - `budget: BetaManagedAgentsBudgetLimit or null` A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 660
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"` - - `type: "limit"` - - `"limit"` - - `created_at: string` A timestamp in RFC 3339 format + format: date-time + - `environment_id: string` - `metadata: map[string]`
from line 680
A timestamp in RFC 3339 format + format: date-time + - `description: string` What the agent should produce.
from line 694
0-indexed revision cycle the outcome is currently on. + format: int32 + - `outcome_id: string` Server-generated outc_ ID for this outcome.
from line 706
- `type: "outcome_evaluation"` - - `"outcome_evaluation"` - - `resources: array of BetaManagedAgentsSessionResource` - - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }` + - `BetaManagedAgentsGitHubRepositoryResource object` - `id: string`
from line 716
A timestamp in RFC 3339 format + format: date-time + - `mount_path: string` - `type: "github_repository"` - - `"github_repository"` - - `updated_at: string` A timestamp in RFC 3339 format + format: date-time + - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - - `BetaManagedAgentsBranchCheckout object { name, type }` + - `BetaManagedAgentsBranchCheckout object` - `name: string` Branch name to check out. + minLength: 1, maxLength: 255 + - `type: "branch"` - - `"branch"` + - `BetaManagedAgentsCommitCheckout object` - - `BetaManagedAgentsCommitCheckout object { sha, type }` - - `sha: string` Full commit SHA to check out. + minLength: 7, maxLength: 64 + - `type: "commit"` - - `"commit"` + - `BetaManagedAgentsFileResource object` - - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }` - - `id: string` - `created_at: string`
from line 760
A timestamp in RFC 3339 format + format: date-time + - `file_id: string` - `mount_path: string`
from line 768
- `type: "file"` - - `"file"` - - `updated_at: string` A timestamp in RFC 3339 format - - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }` + format: date-time + - `BetaManagedAgentsMemoryStoreResource object` + A memory store attached to an agent session. - `memory_store_id: string`
from line 784
- `type: "memory_store"` - - `"memory_store"` - - `access: optional "read_write" or "read_only" or null` Access mode for an attached memory store.
from line 800
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. + maxLength: 4096 + - `mount_path: optional string or null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
from line 818
Cumulative time in seconds the session spent in running status. Excludes idle time. + format: double + - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + format: double + - `status: "rescheduling" or "running" or "idle" or "terminated"` SessionStatus enum
from line 842
- `type: "session"` - - `"session"` - - `updated_at: string` A timestamp in RFC 3339 format + format: date-time + - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for a session across all turns.
from line 856
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. + format: double + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime.
from line 866
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 894
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 904
Number of server-executed web fetch requests. + format: int32 + - `web_search_requests: optional number` Number of server-executed web search requests. + format: int32 + - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied.
from line 920
Deployment ID when the session was created from a deployment reference. Null otherwise. -### Example +## Example -```http +```bash curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 929
-H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +### Response (200) ```json {