## Session statuses ## Updating the agent configuration ## Updating the session budget ## Retrieving a session ## Listing sessions ## Archiving a session ## Deleting a session
The whole hunk
631 lines, first recorded
/
lines
The first capture of this source. The page was already there, and this is what it said.
---
title: Session operations
url: https://platform.claude.com/docs/en/managed-agents/session-operations
description: Retrieve, list, update, archive, and delete Claude Managed Agents sessions.
---
Once a session exists, use these operations to read, update, archive, or delete it. See [Start a session](https://platform.claude.com/docs/en/managed-agents/sessions) for creating a session and sending it work.
<Note>
Managed Agents API requests require the `managed-agents-2026-04-01` beta header, except memory store endpoints, which use `agent-memory-2026-07-22` instead. The SDK sets the correct beta header automatically. See [Beta headers](https://platform.claude.com/docs/en/api/beta-headers#endpoint-specific-headers).
</Note>
## Session statuses
Sessions progress through these statuses. See [Start a session](https://platform.claude.com/docs/en/managed-agents/sessions) for the session lifecycle.
| Status | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idle` | Agent is waiting for input, including user messages or tool confirmations. Sessions created without `initial_events` start in `idle`. |
| `running` | Agent is actively executing. |
| `rescheduling` | Transient error occurred, retrying automatically. |
| `terminated` | Session has ended, either because of an unrecoverable error or because it was archived. A session that finishes its work goes `idle`, not `terminated`. |
## Updating the agent configuration
You can update a session's `agent.tools` and `agent.mcp_servers`, including permission policies, mid-session without creating a new agent version. Updates are session-local and do not propagate back to the underlying agent.
Only the agent's `tools` and `mcp_servers` can change after a session is created. To run a session with `model`, `system`, or `skills` values other than the agent's, use [agent configuration overrides](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session) when you create the session. The agent's model configuration, including its [`inference_geo`](https://platform.claude.com/docs/en/manage-claude/data-residency) pin, also can't change mid-session: set the pin when you save the agent, or set or clear it for a single session with a `model` override when you create it. The agent's configured `system` field is fixed for the session's lifetime. On models that support it, you can still append system-level guidance mid-session by sending a [`system.message` event](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#sending-system-messages).
The semantics of a `tools` or `mcp_servers` update are full replacement: the provided array is the new value. To preserve existing entries, `GET` the session, modify the array, and `POST` it back.
The session must be `idle` to update the agent. [Interrupt](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#integrating-events) the session if you need to update the agent while it's running.
<CodeGroup defaultLanguage="CLI">
```bash cURL
curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": {
"tools": [
{"type": "agent_toolset_20260401"},
{"type": "mcp_toolset", "mcp_server_name": "linear"}
],
"mcp_servers": [
{"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}
]
}
}
EOF
```
```bash CLI
ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
agent:
tools:
- type: agent_toolset_20260401
- type: mcp_toolset
mcp_server_name: linear
mcp_servers:
- type: url
name: linear
url: https://mcp.linear.app/sse
YAML
```
```python Python
client.beta.sessions.update(
session.id,
agent={
"tools": [
{"type": "agent_toolset_20260401"},
{"type": "mcp_toolset", "mcp_server_name": "linear"},
],
"mcp_servers": [
{"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}
],
},
)
```
```typescript TypeScript
await client.beta.sessions.update(session.id, {
agent: {
tools: [
{ type: "agent_toolset_20260401" },
{ type: "mcp_toolset", mcp_server_name: "linear" }
],
mcp_servers: [{ type: "url", name: "linear", url: "https://mcp.linear.app/sse" }]
}
});
```
```csharp C#
await client.Beta.Sessions.Update(session.ID, new()
{
Agent = new()
{
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
},
new BetaManagedAgentsMcpToolsetParams
{
Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset,
McpServerName = "linear",
},
],
McpServers =
[
new()
{
Type = BetaManagedAgentsUrlMcpServerParamsType.Url,
Name = "linear",
Url = "https://mcp.linear.app/sse",
},
],
},
});
```
```go Go
_, err = client.Beta.Sessions.Update(ctx, session.ID, anthropic.BetaSessionUpdateParams{
Agent: anthropic.BetaManagedAgentsSessionAgentUpdateParam{
Tools: []anthropic.BetaManagedAgentsSessionAgentUpdateToolUnionParam{
{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
},
{
OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
MCPServerName: "linear",
},
},
},
MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{
{
Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
Name: "linear",
URL: "https://mcp.linear.app/sse",
},
},
},
})
if err != nil {
panic(err)
}
```
```java Java
client.beta().sessions().update(
session.id(),
SessionUpdateParams.builder()
.agent(BetaManagedAgentsSessionAgentUpdate.builder()
.addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build())
.addTool(BetaManagedAgentsMcpToolsetParams.builder()
.type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
.mcpServerName("linear")
.build())
.addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder()
.type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
.name("linear")
.url("https://mcp.linear.app/sse")
.build())
.build())
.build()
);
```
```php PHP
$client->beta->sessions->update(
$session->id,
agent: BetaManagedAgentsSessionAgentUpdate::with(
tools: [
BetaManagedAgentsAgentToolset20260401Params::with(type: 'agent_toolset_20260401'),
BetaManagedAgentsMCPToolsetParams::with(mcpServerName: 'linear', type: 'mcp_toolset'),
],
mcpServers: [
BetaManagedAgentsURLMCPServerParams::with(
name: 'linear',
type: 'url',
url: 'https://mcp.linear.app/sse',
),
],
),
);
```
```ruby Ruby
client.beta.sessions.update(
session.id,
agent: {
tools: [
{type: :agent_toolset_20260401},
{type: :mcp_toolset, mcp_server_name: "linear"}
],
mcp_servers: [
{type: :url, name: "linear", url: "https://mcp.linear.app/sse"}
]
}
)
```
</CodeGroup>
## Updating the session budget
A session [created with a budget](https://platform.claude.com/docs/en/managed-agents/sessions#set-a-session-budget) accepts two kinds of budget update: replacing the cap with a new `max_list_cost`, and removing it by setting `budget` to `null`. Both automatically resume work that paused when the session reached its cap. A replacement cap can be higher or lower than the current one, but it must be strictly greater than the session's consumed list cost, and removal is one-way: a non-null `budget` is accepted only on a session that currently has one, so you can't re-add a removed budget or add one to a session created without it. See [Session budgets](https://platform.claude.com/docs/en/managed-agents/budgets#resume-a-session-at-its-budget) for request examples, the error behaviors, and what counts toward list cost.
## Retrieving a session
<CodeGroup defaultLanguage="CLI">
```bash cURL
retrieved=$(curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01")
echo "Status: $(jq -r '.status' <<< "$retrieved")"
```
```bash CLI
ant beta:sessions retrieve --session-id "$SESSION_ID"
```
```python Python
retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")
```
```typescript TypeScript
const retrieved = await client.beta.sessions.retrieve(session.id);
console.log(`Status: ${retrieved.status}`);
```
```csharp C#
var retrieved = await client.Beta.Sessions.Retrieve(session.ID);
Console.WriteLine($"Status: {retrieved.Status.Raw()}");
```
```go Go
retrieved, err := client.Beta.Sessions.Get(ctx, session.ID, anthropic.BetaSessionGetParams{})
if err != nil {
panic(err)
}
fmt.Printf("Status: %s\n", retrieved.Status)
```
```java Java
var retrieved = client.beta().sessions().retrieve(session.id());
IO.println("Status: " + retrieved.status());
```
```php PHP
$retrieved = $client->beta->sessions->retrieve($session->id);
echo "Status: {$retrieved->status}\n";
```
```ruby Ruby
retrieved = client.beta.sessions.retrieve(session.id)
puts "Status: #{retrieved.status}"
```
</CodeGroup>
## Listing sessions
Results from `GET /v1/sessions` are paginated. Use the `limit` query parameter to control the page size. Each response includes a `next_page` cursor; pass it as the `page` parameter on the next request to fetch the following page. `next_page` is `null` when there are no more results.
To go back a page, pass `prev_page` as the `page` parameter. `prev_page` is `null` when you're on the first page.
A `page` cursor is opaque and encodes the `order` of the request that produced it. The `order` query parameter sets the sort direction of the results, `asc` or `desc` by creation time; the default is `desc` (newest first). Reusing a cursor with a different `order` returns a 400 error, as does changing a `created_at` filter so that it excludes the cursor's position. Other query parameters, including the remaining filters and `limit`, can change between paginated requests. For the pagination fields shared across list endpoints, see [Pagination](https://platform.claude.com/docs/en/api/overview#pagination).
<CodeGroup defaultLanguage="CLI">
```bash cURL
first_page=$(curl -sS --fail-with-body \
"https://api.anthropic.com/v1/sessions?agent_id=$AGENT_ID&limit=1" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01")
jq '{prev_page, next_page}' <<< "$first_page" # prev_page is null on the first page
next_cursor=$(jq -r '.next_page' <<< "$first_page")
second_page=$(curl -sS --fail-with-body \
"https://api.anthropic.com/v1/sessions?agent_id=$AGENT_ID&limit=1&page=$next_cursor" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01")
prev_cursor=$(jq -r '.prev_page' <<< "$second_page")
curl -sS --fail-with-body \
"https://api.anthropic.com/v1/sessions?agent_id=$AGENT_ID&limit=1&page=$prev_cursor" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
Cut at 300 lines. The page has the rest.