One read of Claude Developer Platformapi-20260825T033708Z
377 pages moved out of 612 read.
Pages moved
377
significant first
Pages read
612
in this capture
Captured
03:37 UTC
Corpus hash
7d98cae5bb87
corpus-hash
What this read moved
226-250 of 377, page 10 of 16This capture is too large to show at once. Changes 226-250 of 377 are below, significant first; the rest are on the following screens.
api/beta/sessions/resources/retrieve Changed · +30 / -31 lines
# Get Session Resource ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Session Resource ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Session Resource
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/retrieve
4---
1# Get Session Resource
52
6## Get Session Resource
3**GET** `/v1/sessions/{session_id}/resources/{resource_id}`
74
8**get** `/v1/sessions/{session_id}/resources/{resource_id}`
9
105Get Session Resource
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
1611- `resource_id: string`
1712
18### Header Parameters
13## Headers
1914
2015- `"anthropic-beta": optional array of AnthropicBeta`
2116
from line 88
9388
9489 - `"mid-conversation-tool-changes-2026-07-01"`
9590
96### Returns
91## Returns
9792
98- `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
93- `BetaManagedAgentsGitHubRepositoryResource object`
9994
10095 - `id: string`
10196
from line 98
10398
10499 A timestamp in RFC 3339 format
105100
101 format: date-time
102
106103 - `mount_path: string`
107104
108105 - `type: "github_repository"`
109106
110 - `"github_repository"`
111
112107 - `updated_at: string`
113108
114109 A timestamp in RFC 3339 format
115110
111 format: date-time
112
116113 - `url: string`
117114
118115 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
119116
120 - `BetaManagedAgentsBranchCheckout object { name, type }`
117 - `BetaManagedAgentsBranchCheckout object`
121118
122119 - `name: string`
123120
124121 Branch name to check out.
125122
123 minLength: 1, maxLength: 255
124
126125 - `type: "branch"`
127126
128 - `"branch"`
127 - `BetaManagedAgentsCommitCheckout object`
129128
130 - `BetaManagedAgentsCommitCheckout object { sha, type }`
131
132129 - `sha: string`
133130
134131 Full commit SHA to check out.
135132
133 minLength: 7, maxLength: 64
134
136135 - `type: "commit"`
137136
138 - `"commit"`
137- `BetaManagedAgentsFileResource object`
139138
140- `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
141
142139 - `id: string`
143140
144141 - `created_at: string`
from line 142
145142
146143 A timestamp in RFC 3339 format
147144
145 format: date-time
146
148147 - `file_id: string`
149148
150149 - `mount_path: string`
from line 150
151150
152151 - `type: "file"`
153152
154 - `"file"`
155
156153 - `updated_at: string`
157154
158155 A timestamp in RFC 3339 format
159156
160- `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
157 format: date-time
161158
159- `BetaManagedAgentsMemoryStoreResource object`
160
162161 A memory store attached to an agent session.
163162
164163 - `memory_store_id: string`
from line 166
167166
168167 - `type: "memory_store"`
169168
170 - `"memory_store"`
171
172169 - `access: optional "read_write" or "read_only" or null`
173170
174171 Access mode for an attached memory store.
from line 182
185182
186183 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
187184
185 maxLength: 4096
186
188187 - `mount_path: optional string or null`
189188
190189 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 192
193192
194193 Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
195194
196### Example
195## Example
197196
198```http
197```bash
199198curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
200199 -H 'anthropic-version: 2023-06-01' \
201200 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 201
202201 -H "X-Api-Key: $ANTHROPIC_API_KEY"
203202```
204203
205#### Response
204### Response (200)
206205
207206```json
208207{
api/beta/sessions/resources/update Changed · +33 / -32 lines
# Update Session Resource ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Update Session Resource ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Update Session Resource
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/update
4---
1# Update Session Resource
52
6## Update Session Resource
3**POST** `/v1/sessions/{session_id}/resources/{resource_id}`
74
8**post** `/v1/sessions/{session_id}/resources/{resource_id}`
9
105Update Session Resource
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
1611- `resource_id: string`
1712
18### Header Parameters
13## Headers
1914
2015- `"anthropic-beta": optional array of AnthropicBeta`
2116
from line 88
9388
9489 - `"mid-conversation-tool-changes-2026-07-01"`
9590
96### Body Parameters
91## Body parameters
9792
9893- `authorization_token: string`
9994
10095 New authorization token for the resource. Currently only `github_repository` resources support token rotation.
10196
102### Returns
97 minLength: 1, maxLength: 4096
10398
104- `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
99## Returns
105100
101- `BetaManagedAgentsGitHubRepositoryResource object`
102
106103 - `id: string`
107104
108105 - `created_at: string`
from line 106
109106
110107 A timestamp in RFC 3339 format
111108
109 format: date-time
110
112111 - `mount_path: string`
113112
114113 - `type: "github_repository"`
115114
116 - `"github_repository"`
117
118115 - `updated_at: string`
119116
120117 A timestamp in RFC 3339 format
121118
119 format: date-time
120
122121 - `url: string`
123122
124123 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
125124
126 - `BetaManagedAgentsBranchCheckout object { name, type }`
125 - `BetaManagedAgentsBranchCheckout object`
127126
128127 - `name: string`
129128
130129 Branch name to check out.
131130
131 minLength: 1, maxLength: 255
132
132133 - `type: "branch"`
133134
134 - `"branch"`
135 - `BetaManagedAgentsCommitCheckout object`
135136
136 - `BetaManagedAgentsCommitCheckout object { sha, type }`
137
138137 - `sha: string`
139138
140139 Full commit SHA to check out.
141140
141 minLength: 7, maxLength: 64
142
142143 - `type: "commit"`
143144
144 - `"commit"`
145- `BetaManagedAgentsFileResource object`
145146
146- `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
147
148147 - `id: string`
149148
150149 - `created_at: string`
from line 150
151150
152151 A timestamp in RFC 3339 format
153152
153 format: date-time
154
154155 - `file_id: string`
155156
156157 - `mount_path: string`
from line 158
157158
158159 - `type: "file"`
159160
160 - `"file"`
161
162161 - `updated_at: string`
163162
164163 A timestamp in RFC 3339 format
165164
166- `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
165 format: date-time
167166
167- `BetaManagedAgentsMemoryStoreResource object`
168
168169 A memory store attached to an agent session.
169170
170171 - `memory_store_id: string`
from line 174
173174
174175 - `type: "memory_store"`
175176
176 - `"memory_store"`
177
178177 - `access: optional "read_write" or "read_only" or null`
179178
180179 Access mode for an attached memory store.
from line 190
191190
192191 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
193192
193 maxLength: 4096
194
194195 - `mount_path: optional string or null`
195196
196197 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 200
199200
200201 Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
201202
202### Example
203## Example
203204
204```http
205```bash
205206curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
206207 -H 'Content-Type: application/json' \
207208 -H 'anthropic-version: 2023-06-01' \
from line 213
212213 }'
213214```
214215
215#### Response
216### Response (200)
216217
217218```json
218219{
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
1---
2title: Get Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/retrieve
4---
1# Get Session
52
6## Get Session
3**GET** `/v1/sessions/{session_id}`
74
8**get** `/v1/sessions/{session_id}`
9
105Get Session
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaManagedAgentsSession object { id, agent, archived_at, 14 more }`
91- `BetaManagedAgentsSession object`
9792
9893 A Managed Agents `session`.
9994
from line 108
113108
114109 - `type: "url"`
115110
116 - `"url"`
117
118111 - `url: string`
119112
120113 - `model: BetaManagedAgentsModelConfig`
from line 184
191184
192185 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
193186
194 - `BetaManagedAgentsEffortLow object { type }`
187 - `BetaManagedAgentsEffortLow object`
195188
196189 Low effort. Favors latency over reasoning depth.
197190
198191 - `type: "low"`
199192
200 - `"low"`
193 - `BetaManagedAgentsEffortMedium object`
201194
202 - `BetaManagedAgentsEffortMedium object { type }`
203
204195 Medium effort. Balances latency and reasoning depth.
205196
206197 - `type: "medium"`
207198
208 - `"medium"`
199 - `BetaManagedAgentsEffortHigh object`
209200
210 - `BetaManagedAgentsEffortHigh object { type }`
211
212201 High effort. Favors reasoning depth.
213202
214203 - `type: "high"`
215204
216 - `"high"`
205 - `BetaManagedAgentsEffortXhigh object`
217206
218 - `BetaManagedAgentsEffortXhigh object { type }`
219
220207 Extra-high effort. Not all models accept this level.
221208
222209 - `type: "xhigh"`
223210
224 - `"xhigh"`
211 - `BetaManagedAgentsEffortMax object`
225212
226 - `BetaManagedAgentsEffortMax object { type }`
227
228213 Maximum effort. Favors reasoning depth over latency.
229214
230215 - `type: "max"`
231216
232 - `"max"`
233
234217 - `inference_geo: optional string`
235218
236219 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 234
251234
252235 Full `agent` definitions the coordinator may spawn as session threads.
253236
254 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
237 - `BetaManagedAgentsSessionThreadAgent object`
255238
256239 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`.
257240
from line 258
275258
276259 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
277260
278 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
261 - `BetaManagedAgentsAnthropicSkill object`
279262
280263 A resolved Anthropic-managed skill.
281264
from line 266
283266
284267 - `type: "anthropic"`
285268
286 - `"anthropic"`
287
288269 - `version: string`
289270
290 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
271 - `BetaManagedAgentsCustomSkill object`
291272
292273 A resolved user-created custom skill.
293274
from line 276
295276
296277 - `type: "custom"`
297278
298 - `"custom"`
299
300279 - `version: string`
301280
302281 - `system: string or null`
from line 282
303282
304283 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
305284
306 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
285 - `BetaManagedAgentsAgentToolset20260401 object`
307286
308287 - `configs: array of BetaManagedAgentsAgentToolConfig`
309288
310 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
289 - `BetaManagedAgentsBashToolConfig object`
311290
312291 Configuration for the bash tool.
313292
from line 294
315294
316295 - `name: "bash"`
317296
318 - `"bash"`
319
320297 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
321298
322299 Permission policy for tool execution.
323300
324 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
301 - `BetaManagedAgentsAlwaysAllowPolicy object`
325302
326303 Tool calls are automatically approved without user confirmation.
327304
328305 - `type: "always_allow"`
329306
330 - `"always_allow"`
307 - `BetaManagedAgentsAlwaysAskPolicy object`
331308
332 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
333
334309 Tool calls require user confirmation before execution.
335310
336311 - `type: "always_ask"`
337312
338 - `"always_ask"`
339
340313 - `type: "bash"`
341314
342 - `"bash"`
315 - `BetaManagedAgentsEditToolConfig object`
343316
344 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
345
346317 Configuration for the edit tool.
347318
348319 - `enabled: boolean`
from line 320
349320
350321 - `name: "edit"`
351322
352 - `"edit"`
353
354323 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
355324
356325 Permission policy for tool execution.
357326
358 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
327 - `BetaManagedAgentsAlwaysAllowPolicy object`
359328
360329 Tool calls are automatically approved without user confirmation.
361330
362 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
331 - `BetaManagedAgentsAlwaysAskPolicy object`
363332
364333 Tool calls require user confirmation before execution.
365334
366335 - `type: "edit"`
367336
368 - `"edit"`
337 - `BetaManagedAgentsReadToolConfig object`
369338
370 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
371
372339 Configuration for the read tool.
373340
374341 - `enabled: boolean`
from line 342
375342
376343 - `name: "read"`
377344
378 - `"read"`
379
380345 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
381346
382347 Permission policy for tool execution.
383348
384 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
349 - `BetaManagedAgentsAlwaysAllowPolicy object`
385350
386351 Tool calls are automatically approved without user confirmation.
387352
388 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
353 - `BetaManagedAgentsAlwaysAskPolicy object`
389354
390355 Tool calls require user confirmation before execution.
391356
392357 - `type: "read"`
393358
394 - `"read"`
359 - `BetaManagedAgentsWriteToolConfig object`
395360
396 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
397
398361 Configuration for the write tool.
399362
400363 - `enabled: boolean`
from line 364
401364
402365 - `name: "write"`
403366
404 - `"write"`
405
406367 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
407368
408369 Permission policy for tool execution.
409370
410 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
371 - `BetaManagedAgentsAlwaysAllowPolicy object`
411372
412373 Tool calls are automatically approved without user confirmation.
413374
414 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
375 - `BetaManagedAgentsAlwaysAskPolicy object`
415376
416377 Tool calls require user confirmation before execution.
417378
418379 - `type: "write"`
419380
420 - `"write"`
381 - `BetaManagedAgentsGlobToolConfig object`
421382
422 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
423
424383 Configuration for the glob tool.
425384
426385 - `enabled: boolean`
from line 386
427386
428387 - `name: "glob"`
429388
430 - `"glob"`
431
432389 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
433390
434391 Permission policy for tool execution.
435392
436 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
393 - `BetaManagedAgentsAlwaysAllowPolicy object`
437394
438395 Tool calls are automatically approved without user confirmation.
439396
440 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
397 - `BetaManagedAgentsAlwaysAskPolicy object`
441398
442399 Tool calls require user confirmation before execution.
443400
444401 - `type: "glob"`
445402
446 - `"glob"`
403 - `BetaManagedAgentsGrepToolConfig object`
447404
448 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
449
450405 Configuration for the grep tool.
451406
452407 - `enabled: boolean`
from line 408
453408
454409 - `name: "grep"`
455410
456 - `"grep"`
457
458411 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
459412
460413 Permission policy for tool execution.
461414
462 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
415 - `BetaManagedAgentsAlwaysAllowPolicy object`
463416
464417 Tool calls are automatically approved without user confirmation.
465418
466 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
419 - `BetaManagedAgentsAlwaysAskPolicy object`
467420
468421 Tool calls require user confirmation before execution.
469422
470423 - `type: "grep"`
471424
472 - `"grep"`
425 - `BetaManagedAgentsWebFetchToolConfig object`
473426
474 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
475
476427 Configuration for the web_fetch tool.
477428
478429 - `enabled: boolean`
from line 430
479430
480431 - `name: "web_fetch"`
481432
482 - `"web_fetch"`
483
484433 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
485434
486435 Permission policy for tool execution.
487436
488 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
437 - `BetaManagedAgentsAlwaysAllowPolicy object`
489438
490439 Tool calls are automatically approved without user confirmation.
491440
492 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
441 - `BetaManagedAgentsAlwaysAskPolicy object`
493442
494443 Tool calls require user confirmation before execution.
495444
496445 - `type: "web_fetch"`
497446
498 - `"web_fetch"`
499
500447 - `allowed_domains: optional array of string`
501448
502449 - `blocked_domains: optional array of string`
from line 450
503450
504451 - `max_content_tokens: optional number or null`
505452
506 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
453 format: int32
507454
455 - `BetaManagedAgentsWebSearchToolConfig object`
456
508457 Configuration for the web_search tool.
509458
510459 - `enabled: boolean`
from line 460
511460
512461 - `name: "web_search"`
513462
514 - `"web_search"`
515
516463 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
517464
518465 Permission policy for tool execution.
519466
520 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
467 - `BetaManagedAgentsAlwaysAllowPolicy object`
521468
522469 Tool calls are automatically approved without user confirmation.
523470
524 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
471 - `BetaManagedAgentsAlwaysAskPolicy object`
525472
526473 Tool calls require user confirmation before execution.
527474
528475 - `type: "web_search"`
529476
530 - `"web_search"`
531
532477 - `allowed_domains: optional array of string`
533478
534479 - `blocked_domains: optional array of string`
from line 486
541486
542487 Location precision. Only "approximate" is supported.
543488
544 - `"approximate"`
545
546489 - `city: optional string or null`
547490
548491 City name.
549492
493 minLength: 1, maxLength: 255
494
550495 - `country: optional string or null`
551496
552497 Two-letter ISO 3166-1 country code, uppercase.
from line 500
555500
556501 Region or state name.
557502
503 minLength: 1, maxLength: 255
504
558505 - `timezone: optional string or null`
559506
560507 IANA timezone identifier, e.g. "America/Los_Angeles".
561508
509 minLength: 1, maxLength: 255
510
562511 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
563512
564513 Resolved default configuration for agent tools.
from line 518
569518
570519 Permission policy for tool execution.
571520
572 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
521 - `BetaManagedAgentsAlwaysAllowPolicy object`
573522
574523 Tool calls are automatically approved without user confirmation.
575524
576 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
525 - `BetaManagedAgentsAlwaysAskPolicy object`
577526
578527 Tool calls require user confirmation before execution.
579528
580529 - `type: "agent_toolset_20260401"`
581530
582 - `"agent_toolset_20260401"`
531 - `BetaManagedAgentsMCPToolset object`
583532
584 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
585
586533 - `configs: array of BetaManagedAgentsMCPToolConfig`
587534
588535 - `enabled: boolean`
from line 540
593540
594541 Permission policy for tool execution.
595542
596 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
543 - `BetaManagedAgentsAlwaysAllowPolicy object`
597544
598545 Tool calls are automatically approved without user confirmation.
599546
600 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
547 - `BetaManagedAgentsAlwaysAskPolicy object`
601548
602549 Tool calls require user confirmation before execution.
603550
from line 558
611558
612559 Permission policy for tool execution.
613560
614 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
561 - `BetaManagedAgentsAlwaysAllowPolicy object`
615562
616563 Tool calls are automatically approved without user confirmation.
617564
618 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
565 - `BetaManagedAgentsAlwaysAskPolicy object`
619566
620567 Tool calls require user confirmation before execution.
621568
from line 570
623570
624571 - `type: "mcp_toolset"`
625572
626 - `"mcp_toolset"`
573 - `BetaManagedAgentsCustomTool object`
627574
628 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
629
630575 A custom tool as returned in API responses.
631576
632577 - `description: string`
from line 582
637582
638583 - `type: "object"`
639584
640 - `"object"`
641
642585 - `properties: optional map[unknown] or null`
643586
644587 - `required: optional array of string or null`
from line 590
647590
648591 - `type: "custom"`
649592
650 - `"custom"`
651
652593 - `type: "agent"`
653594
654 - `"agent"`
655
656595 - `version: number`
657596
658 - `BetaManagedAgentsAdvisor object { model, type }`
597 format: int32
659598
599 - `BetaManagedAgentsAdvisor object`
600
660601 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
661602
662603 - `model: string`
from line 606
665606
666607 - `type: "advisor"`
667608
668 - `"advisor"`
669
670609 - `type: "coordinator"`
671610
672 - `"coordinator"`
673
674611 - `name: string`
675612
676613 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
677614
678 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
615 - `BetaManagedAgentsAnthropicSkill object`
679616
680617 A resolved Anthropic-managed skill.
681618
682 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
619 - `BetaManagedAgentsCustomSkill object`
683620
684621 A resolved user-created custom skill.
685622
from line 624
687624
688625 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
689626
690 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
627 - `BetaManagedAgentsAgentToolset20260401 object`
691628
692 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
629 - `BetaManagedAgentsMCPToolset object`
693630
694 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
631 - `BetaManagedAgentsCustomTool object`
695632
696633 A custom tool as returned in API responses.
697634
698635 - `type: "agent"`
699636
700 - `"agent"`
701
702637 - `version: number`
703638
639 format: int32
640
704641 - `archived_at: string or null`
705642
706643 A timestamp in RFC 3339 format
707644
645 format: date-time
646
708647 - `budget: BetaManagedAgentsBudgetLimit or null`
709648
710649 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 660
721660
722661 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.
723662
724 - `"USD"`
725
726663 - `type: "limit"`
727664
728 - `"limit"`
729
730665 - `created_at: string`
731666
732667 A timestamp in RFC 3339 format
733668
669 format: date-time
670
734671 - `environment_id: string`
735672
736673 - `metadata: map[string]`
from line 680
743680
744681 A timestamp in RFC 3339 format
745682
683 format: date-time
684
746685 - `description: string`
747686
748687 What the agent should produce.
from line 694
755694
756695 0-indexed revision cycle the outcome is currently on.
757696
697 format: int32
698
758699 - `outcome_id: string`
759700
760701 Server-generated outc_ ID for this outcome.
from line 706
765706
766707 - `type: "outcome_evaluation"`
767708
768 - `"outcome_evaluation"`
769
770709 - `resources: array of BetaManagedAgentsSessionResource`
771710
772 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
711 - `BetaManagedAgentsGitHubRepositoryResource object`
773712
774713 - `id: string`
775714
from line 716
777716
778717 A timestamp in RFC 3339 format
779718
719 format: date-time
720
780721 - `mount_path: string`
781722
782723 - `type: "github_repository"`
783724
784 - `"github_repository"`
785
786725 - `updated_at: string`
787726
788727 A timestamp in RFC 3339 format
789728
729 format: date-time
730
790731 - `url: string`
791732
792733 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
793734
794 - `BetaManagedAgentsBranchCheckout object { name, type }`
735 - `BetaManagedAgentsBranchCheckout object`
795736
796737 - `name: string`
797738
798739 Branch name to check out.
799740
741 minLength: 1, maxLength: 255
742
800743 - `type: "branch"`
801744
802 - `"branch"`
745 - `BetaManagedAgentsCommitCheckout object`
803746
804 - `BetaManagedAgentsCommitCheckout object { sha, type }`
805
806747 - `sha: string`
807748
808749 Full commit SHA to check out.
809750
751 minLength: 7, maxLength: 64
752
810753 - `type: "commit"`
811754
812 - `"commit"`
755 - `BetaManagedAgentsFileResource object`
813756
814 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
815
816757 - `id: string`
817758
818759 - `created_at: string`
from line 760
819760
820761 A timestamp in RFC 3339 format
821762
763 format: date-time
764
822765 - `file_id: string`
823766
824767 - `mount_path: string`
from line 768
825768
826769 - `type: "file"`
827770
828 - `"file"`
829
830771 - `updated_at: string`
831772
832773 A timestamp in RFC 3339 format
833774
834 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
775 format: date-time
835776
777 - `BetaManagedAgentsMemoryStoreResource object`
778
836779 A memory store attached to an agent session.
837780
838781 - `memory_store_id: string`
from line 784
841784
842785 - `type: "memory_store"`
843786
844 - `"memory_store"`
845
846787 - `access: optional "read_write" or "read_only" or null`
847788
848789 Access mode for an attached memory store.
from line 800
859800
860801 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
861802
803 maxLength: 4096
804
862805 - `mount_path: optional string or null`
863806
864807 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
875818
876819 Cumulative time in seconds the session spent in running status. Excludes idle time.
877820
821 format: double
822
878823 - `duration_seconds: optional number`
879824
880825 Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
881826
827 format: double
828
882829 - `status: "rescheduling" or "running" or "idle" or "terminated"`
883830
884831 SessionStatus enum
from line 842
895842
896843 - `type: "session"`
897844
898 - `"session"`
899
900845 - `updated_at: string`
901846
902847 A timestamp in RFC 3339 format
903848
849 format: date-time
850
904851 - `usage: BetaManagedAgentsSessionUsage`
905852
906853 Cumulative token usage for a session across all turns.
from line 856
909856
910857 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.
911858
859 format: double
860
912861 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
913862
914863 Prompt-cache creation token usage broken down by cache lifetime.
from line 866
917866
918867 Tokens used to create 1-hour ephemeral cache entries.
919868
869 format: int32
870
920871 - `ephemeral_5m_input_tokens: optional number`
921872
922873 Tokens used to create 5-minute ephemeral cache entries.
923874
875 format: int32
876
924877 - `cache_read_input_tokens: optional number`
925878
926879 Total tokens read from prompt cache.
927880
881 format: int32
882
928883 - `input_tokens: optional number`
929884
930885 Total input tokens consumed across all turns.
931886
887 format: int32
888
932889 - `list_cost: optional BetaMonetaryAmount or null`
933890
934891 A monetary amount in a specific currency.
from line 894
937894
938895 Total output tokens generated across all turns.
939896
897 format: int32
898
940899 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null`
941900
942901 Cumulative count of server-executed tool invocations, broken down by tool.
from line 904
945904
946905 Number of server-executed web fetch requests.
947906
907 format: int32
908
948909 - `web_search_requests: optional number`
949910
950911 Number of server-executed web search requests.
951912
913 format: int32
914
952915 - `vault_ids: array of string`
953916
954917 Vault IDs attached to the session at creation. Empty when no vaults were supplied.
from line 920
957920
958921 Deployment ID when the session was created from a deployment reference. Null otherwise.
959922
960### Example
923## Example
961924
962```http
925```bash
963926curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
964927 -H 'anthropic-version: 2023-06-01' \
965928 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 929
966929 -H "X-Api-Key: $ANTHROPIC_API_KEY"
967930```
968931
969#### Response
932### Response (200)
970933
971934```json
972935{
api/beta/sessions/threads Changed · +1329 / -1642 lines
### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ## Threads › Events ### List Session Thread Events #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Stream Session Thread Events #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types # Events ## List Session Thread Events ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Stream Session Thread Events ### Path Parameters ### Query Parameters ### Header Parameters #### Response
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
api/beta/sessions/threads/archive Changed · +92 / -129 lines
# Archive Session Thread ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Archive Session Thread ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Archive Session Thread
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/archive
4---
1# Archive Session Thread
52
6## Archive Session Thread
3**POST** `/v1/sessions/{session_id}/threads/{thread_id}/archive`
74
8**post** `/v1/sessions/{session_id}/threads/{thread_id}/archive`
9
105Archive Session Thread
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
1611- `thread_id: string`
1712
18### Header Parameters
13## Headers
1914
2015- `"anthropic-beta": optional array of AnthropicBeta`
2116
from line 88
9388
9489 - `"mid-conversation-tool-changes-2026-07-01"`
9590
96### Returns
91## Returns
9792
98- `BetaManagedAgentsSessionThread object { id, agent, archived_at, 8 more }`
93- `BetaManagedAgentsSessionThread object`
9994
10095 An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator.
10196
from line 102
107102
108103 A session-resolved multiagent roster entry.
109104
110 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
105 - `BetaManagedAgentsSessionThreadAgent object`
111106
112107 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`.
113108
from line 116
121116
122117 - `type: "url"`
123118
124 - `"url"`
125
126119 - `url: string`
127120
128121 - `model: BetaManagedAgentsModelConfig`
from line 192
199192
200193 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
201194
202 - `BetaManagedAgentsEffortLow object { type }`
195 - `BetaManagedAgentsEffortLow object`
203196
204197 Low effort. Favors latency over reasoning depth.
205198
206199 - `type: "low"`
207200
208 - `"low"`
201 - `BetaManagedAgentsEffortMedium object`
209202
210 - `BetaManagedAgentsEffortMedium object { type }`
211
212203 Medium effort. Balances latency and reasoning depth.
213204
214205 - `type: "medium"`
215206
216 - `"medium"`
207 - `BetaManagedAgentsEffortHigh object`
217208
218 - `BetaManagedAgentsEffortHigh object { type }`
219
220209 High effort. Favors reasoning depth.
221210
222211 - `type: "high"`
223212
224 - `"high"`
213 - `BetaManagedAgentsEffortXhigh object`
225214
226 - `BetaManagedAgentsEffortXhigh object { type }`
227
228215 Extra-high effort. Not all models accept this level.
229216
230217 - `type: "xhigh"`
231218
232 - `"xhigh"`
219 - `BetaManagedAgentsEffortMax object`
233220
234 - `BetaManagedAgentsEffortMax object { type }`
235
236221 Maximum effort. Favors reasoning depth over latency.
237222
238223 - `type: "max"`
239224
240 - `"max"`
241
242225 - `inference_geo: optional string`
243226
244227 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 238
255238
256239 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
257240
258 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
241 - `BetaManagedAgentsAnthropicSkill object`
259242
260243 A resolved Anthropic-managed skill.
261244
from line 246
263246
264247 - `type: "anthropic"`
265248
266 - `"anthropic"`
267
268249 - `version: string`
269250
270 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
251 - `BetaManagedAgentsCustomSkill object`
271252
272253 A resolved user-created custom skill.
273254
from line 256
275256
276257 - `type: "custom"`
277258
278 - `"custom"`
279
280259 - `version: string`
281260
282261 - `system: string or null`
from line 262
283262
284263 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
285264
286 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
265 - `BetaManagedAgentsAgentToolset20260401 object`
287266
288267 - `configs: array of BetaManagedAgentsAgentToolConfig`
289268
290 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
269 - `BetaManagedAgentsBashToolConfig object`
291270
292271 Configuration for the bash tool.
293272
from line 274
295274
296275 - `name: "bash"`
297276
298 - `"bash"`
299
300277 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
301278
302279 Permission policy for tool execution.
303280
304 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
281 - `BetaManagedAgentsAlwaysAllowPolicy object`
305282
306283 Tool calls are automatically approved without user confirmation.
307284
308285 - `type: "always_allow"`
309286
310 - `"always_allow"`
287 - `BetaManagedAgentsAlwaysAskPolicy object`
311288
312 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
313
314289 Tool calls require user confirmation before execution.
315290
316291 - `type: "always_ask"`
317292
318 - `"always_ask"`
319
320293 - `type: "bash"`
321294
322 - `"bash"`
295 - `BetaManagedAgentsEditToolConfig object`
323296
324 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
325
326297 Configuration for the edit tool.
327298
328299 - `enabled: boolean`
from line 300
329300
330301 - `name: "edit"`
331302
332 - `"edit"`
333
334303 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
335304
336305 Permission policy for tool execution.
337306
338 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
307 - `BetaManagedAgentsAlwaysAllowPolicy object`
339308
340309 Tool calls are automatically approved without user confirmation.
341310
342 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
311 - `BetaManagedAgentsAlwaysAskPolicy object`
343312
344313 Tool calls require user confirmation before execution.
345314
346315 - `type: "edit"`
347316
348 - `"edit"`
317 - `BetaManagedAgentsReadToolConfig object`
349318
350 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
351
352319 Configuration for the read tool.
353320
354321 - `enabled: boolean`
from line 322
355322
356323 - `name: "read"`
357324
358 - `"read"`
359
360325 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
361326
362327 Permission policy for tool execution.
363328
364 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
329 - `BetaManagedAgentsAlwaysAllowPolicy object`
365330
366331 Tool calls are automatically approved without user confirmation.
367332
368 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
333 - `BetaManagedAgentsAlwaysAskPolicy object`
369334
370335 Tool calls require user confirmation before execution.
371336
372337 - `type: "read"`
373338
374 - `"read"`
339 - `BetaManagedAgentsWriteToolConfig object`
375340
376 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
377
378341 Configuration for the write tool.
379342
380343 - `enabled: boolean`
from line 344
381344
382345 - `name: "write"`
383346
384 - `"write"`
385
386347 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
387348
388349 Permission policy for tool execution.
389350
390 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
351 - `BetaManagedAgentsAlwaysAllowPolicy object`
391352
392353 Tool calls are automatically approved without user confirmation.
393354
394 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
355 - `BetaManagedAgentsAlwaysAskPolicy object`
395356
396357 Tool calls require user confirmation before execution.
397358
398359 - `type: "write"`
399360
400 - `"write"`
361 - `BetaManagedAgentsGlobToolConfig object`
401362
402 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
403
404363 Configuration for the glob tool.
405364
406365 - `enabled: boolean`
from line 366
407366
408367 - `name: "glob"`
409368
410 - `"glob"`
411
412369 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
413370
414371 Permission policy for tool execution.
415372
416 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
373 - `BetaManagedAgentsAlwaysAllowPolicy object`
417374
418375 Tool calls are automatically approved without user confirmation.
419376
420 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
377 - `BetaManagedAgentsAlwaysAskPolicy object`
421378
422379 Tool calls require user confirmation before execution.
423380
424381 - `type: "glob"`
425382
426 - `"glob"`
383 - `BetaManagedAgentsGrepToolConfig object`
427384
428 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
429
430385 Configuration for the grep tool.
431386
432387 - `enabled: boolean`
from line 388
433388
434389 - `name: "grep"`
435390
436 - `"grep"`
437
438391 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
439392
440393 Permission policy for tool execution.
441394
442 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
395 - `BetaManagedAgentsAlwaysAllowPolicy object`
443396
444397 Tool calls are automatically approved without user confirmation.
445398
446 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
399 - `BetaManagedAgentsAlwaysAskPolicy object`
447400
448401 Tool calls require user confirmation before execution.
449402
450403 - `type: "grep"`
451404
452 - `"grep"`
405 - `BetaManagedAgentsWebFetchToolConfig object`
453406
454 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
455
456407 Configuration for the web_fetch tool.
457408
458409 - `enabled: boolean`
from line 410
459410
460411 - `name: "web_fetch"`
461412
462 - `"web_fetch"`
463
464413 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
465414
466415 Permission policy for tool execution.
467416
468 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
417 - `BetaManagedAgentsAlwaysAllowPolicy object`
469418
470419 Tool calls are automatically approved without user confirmation.
471420
472 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
421 - `BetaManagedAgentsAlwaysAskPolicy object`
473422
474423 Tool calls require user confirmation before execution.
475424
476425 - `type: "web_fetch"`
477426
478 - `"web_fetch"`
479
480427 - `allowed_domains: optional array of string`
481428
482429 - `blocked_domains: optional array of string`
from line 430
483430
484431 - `max_content_tokens: optional number or null`
485432
486 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
433 format: int32
487434
435 - `BetaManagedAgentsWebSearchToolConfig object`
436
488437 Configuration for the web_search tool.
489438
490439 - `enabled: boolean`
from line 440
491440
492441 - `name: "web_search"`
493442
494 - `"web_search"`
495
496443 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
497444
498445 Permission policy for tool execution.
499446
500 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
447 - `BetaManagedAgentsAlwaysAllowPolicy object`
501448
502449 Tool calls are automatically approved without user confirmation.
503450
504 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
451 - `BetaManagedAgentsAlwaysAskPolicy object`
505452
506453 Tool calls require user confirmation before execution.
507454
508455 - `type: "web_search"`
509456
510 - `"web_search"`
511
512457 - `allowed_domains: optional array of string`
513458
514459 - `blocked_domains: optional array of string`
from line 466
521466
522467 Location precision. Only "approximate" is supported.
523468
524 - `"approximate"`
525
526469 - `city: optional string or null`
527470
528471 City name.
529472
473 minLength: 1, maxLength: 255
474
530475 - `country: optional string or null`
531476
532477 Two-letter ISO 3166-1 country code, uppercase.
from line 480
535480
536481 Region or state name.
537482
483 minLength: 1, maxLength: 255
484
538485 - `timezone: optional string or null`
539486
540487 IANA timezone identifier, e.g. "America/Los_Angeles".
541488
489 minLength: 1, maxLength: 255
490
542491 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
543492
544493 Resolved default configuration for agent tools.
from line 498
549498
550499 Permission policy for tool execution.
551500
552 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
501 - `BetaManagedAgentsAlwaysAllowPolicy object`
553502
554503 Tool calls are automatically approved without user confirmation.
555504
556 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
505 - `BetaManagedAgentsAlwaysAskPolicy object`
557506
558507 Tool calls require user confirmation before execution.
559508
560509 - `type: "agent_toolset_20260401"`
561510
562 - `"agent_toolset_20260401"`
511 - `BetaManagedAgentsMCPToolset object`
563512
564 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
565
566513 - `configs: array of BetaManagedAgentsMCPToolConfig`
567514
568515 - `enabled: boolean`
from line 520
573520
574521 Permission policy for tool execution.
575522
576 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
523 - `BetaManagedAgentsAlwaysAllowPolicy object`
577524
578525 Tool calls are automatically approved without user confirmation.
579526
580 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
527 - `BetaManagedAgentsAlwaysAskPolicy object`
581528
582529 Tool calls require user confirmation before execution.
583530
from line 538
591538
592539 Permission policy for tool execution.
593540
594 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
541 - `BetaManagedAgentsAlwaysAllowPolicy object`
595542
596543 Tool calls are automatically approved without user confirmation.
597544
598 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
545 - `BetaManagedAgentsAlwaysAskPolicy object`
599546
600547 Tool calls require user confirmation before execution.
601548
from line 550
603550
604551 - `type: "mcp_toolset"`
605552
606 - `"mcp_toolset"`
553 - `BetaManagedAgentsCustomTool object`
607554
608 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
609
610555 A custom tool as returned in API responses.
611556
612557 - `description: string`
from line 562
617562
618563 - `type: "object"`
619564
620 - `"object"`
621
622565 - `properties: optional map[unknown] or null`
623566
624567 - `required: optional array of string or null`
from line 570
627570
628571 - `type: "custom"`
629572
630 - `"custom"`
631
632573 - `type: "agent"`
633574
634 - `"agent"`
635
636575 - `version: number`
637576
638 - `BetaManagedAgentsAdvisor object { model, type }`
577 format: int32
639578
579 - `BetaManagedAgentsAdvisor object`
580
640581 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
641582
642583 - `model: string`
from line 586
645586
646587 - `type: "advisor"`
647588
648 - `"advisor"`
649
650589 - `archived_at: string or null`
651590
652591 A timestamp in RFC 3339 format
653592
593 format: date-time
594
654595 - `created_at: string`
655596
656597 A timestamp in RFC 3339 format
657598
599 format: date-time
600
658601 - `parent_thread_id: string or null`
659602
660603 Parent thread that spawned this thread. Null for the primary thread.
from line 614
671614
672615 Cumulative time in seconds the thread spent actively running. Excludes idle time.
673616
617 format: double
618
674619 - `duration_seconds: optional number`
675620
676621 Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.
677622
623 format: double
624
678625 - `startup_seconds: optional number`
679626
680627 Time in seconds for the thread to begin running. Zero for child threads, which start immediately.
681628
629 format: double
630
682631 - `status: BetaManagedAgentsSessionThreadStatus`
683632
684633 SessionThreadStatus enum
from line 642
693642
694643 - `type: "session_thread"`
695644
696 - `"session_thread"`
697
698645 - `updated_at: string`
699646
700647 A timestamp in RFC 3339 format
701648
649 format: date-time
650
702651 - `usage: BetaManagedAgentsSessionThreadUsage or null`
703652
704653 Cumulative token usage for a session thread across all turns.
from line 656
707656
708657 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.
709658
659 format: double
660
710661 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
711662
712663 Prompt-cache creation token usage broken down by cache lifetime.
from line 666
715666
716667 Tokens used to create 1-hour ephemeral cache entries.
717668
669 format: int32
670
718671 - `ephemeral_5m_input_tokens: optional number`
719672
720673 Tokens used to create 5-minute ephemeral cache entries.
721674
675 format: int32
676
722677 - `cache_read_input_tokens: optional number`
723678
724679 Total tokens read from prompt cache.
725680
681 format: int32
682
726683 - `input_tokens: optional number`
727684
728685 Total input tokens consumed across all turns.
729686
687 format: int32
688
730689 - `list_cost: optional BetaMonetaryAmount or null`
731690
732691 A monetary amount in a specific currency.
from line 698
739698
740699 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.
741700
742 - `"USD"`
743
744701 - `output_tokens: optional number`
745702
746703 Total output tokens generated across all turns.
747704
705 format: int32
706
748707 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null`
749708
750709 Cumulative count of server-executed tool invocations, broken down by tool.
from line 712
753712
754713 Number of server-executed web fetch requests.
755714
715 format: int32
716
756717 - `web_search_requests: optional number`
757718
758719 Number of server-executed web search requests.
759720
760### Example
721 format: int32
761722
762```http
723## Example
724
725```bash
763726curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/archive \
764727 -X POST \
765728 -H 'anthropic-version: 2023-06-01' \
from line 730
767730 -H "X-Api-Key: $ANTHROPIC_API_KEY"
768731```
769732
770#### Response
733### Response (200)
771734
772735```json
773736{
api/beta/sessions/threads/events Changed · +638 / -773 lines
### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/events
4---
5
61# Events
72
83## List Session Thread Events
94
10**get** `/v1/sessions/{session_id}/threads/{thread_id}/events`
5**GET** `/v1/sessions/{session_id}/threads/{thread_id}/events`
116
127List Session Thread Events
138
14### Path Parameters
9### Path parameters
1510
1611- `session_id: string`
1712
1813- `thread_id: string`
1914
20### Query Parameters
15### Query parameters
2116
2217- `limit: optional number`
2318
2419 Query parameter for limit
2520
21 format: int32
22
2623- `page: optional string`
2724
2825 Query parameter for page
2926
30### Header Parameters
27### Headers
3128
3229- `"anthropic-beta": optional array of AnthropicBeta`
3330
from line 108
111108
112109 Events for the thread, ordered by `processed_at`.
113110
114 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
111 - `BetaManagedAgentsUserMessageEvent object`
115112
116113 A user message event in the session conversation.
117114
from line 120
123120
124121 Array of content blocks comprising the user message.
125122
126 - `BetaManagedAgentsTextBlock object { text, type }`
123 - `BetaManagedAgentsTextBlock object`
127124
128125 Regular text content.
129126
from line 128
131128
132129 The text content.
133130
131 minLength: 1
132
134133 - `type: "text"`
135134
136 - `"text"`
137
138 - `BetaManagedAgentsImageBlock object { source, type }`
135 - `BetaManagedAgentsImageBlock object`
139136
140137 Image content specified directly as base64 data or as a reference via a URL.
141138
from line 140
143140
144141 Union type for image source variants.
145142
146 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
143 - `BetaManagedAgentsBase64ImageSource object`
147144
148145 Base64-encoded image data.
149146
from line 148
151148
152149 Base64-encoded image data.
153150
151 minLength: 1
152
154153 - `media_type: string`
155154
156155 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
157156
157 minLength: 1
158
158159 - `type: "base64"`
159160
160 - `"base64"`
161
162 - `BetaManagedAgentsURLImageSource object { type, url }`
161 - `BetaManagedAgentsURLImageSource object`
163162
164163 Image referenced by URL.
165164
166165 - `type: "url"`
167166
168 - `"url"`
169
170167 - `url: string`
171168
172169 URL of the image to fetch.
173170
174 - `BetaManagedAgentsFileImageSource object { file_id, type }`
171 minLength: 1
172
173 - `BetaManagedAgentsFileImageSource object`
175174
176175 Image referenced by file ID.
177176
from line 178
179178
180179 ID of a previously uploaded file.
181180
181 minLength: 1
182
182183 - `type: "file"`
183184
184 - `"file"`
185
186185 - `type: "image"`
187186
188 - `"image"`
189
190 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
187 - `BetaManagedAgentsDocumentBlock object`
191188
192189 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
193190
from line 192
195192
196193 Union type for document source variants.
197194
198 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
195 - `BetaManagedAgentsBase64DocumentSource object`
199196
200197 Base64-encoded document data.
201198
from line 200
203200
204201 Base64-encoded document data.
205202
203 minLength: 1
204
206205 - `media_type: string`
207206
208207 MIME type of the document (e.g., "application/pdf").
209208
209 minLength: 1
210
210211 - `type: "base64"`
211212
212 - `"base64"`
213
214 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
213 - `BetaManagedAgentsPlainTextDocumentSource object`
215214
216215 Plain text document content.
217216
from line 218
219218
220219 The plain text content.
221220
221 minLength: 1
222
222223 - `media_type: "text/plain"`
223224
224225 MIME type of the text content. Must be "text/plain".
225226
226 - `"text/plain"`
227
228227 - `type: "text"`
229228
230 - `"text"`
231
232 - `BetaManagedAgentsURLDocumentSource object { type, url }`
229 - `BetaManagedAgentsURLDocumentSource object`
233230
234231 Document referenced by URL.
235232
236233 - `type: "url"`
237234
238 - `"url"`
239
240235 - `url: string`
241236
242237 URL of the document to fetch.
243238
244 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
239 minLength: 1
240
241 - `BetaManagedAgentsFileDocumentSource object`
245242
246243 Document referenced by file ID.
247244
from line 246
249246
250247 ID of a previously uploaded file.
251248
249 minLength: 1
250
252251 - `type: "file"`
253252
254 - `"file"`
255
256253 - `type: "document"`
257254
258 - `"document"`
259
260255 - `context: optional string or null`
261256
262257 Additional context about the document for the model.
from line 260
265260
266261 The title of the document.
267262
268 - `BetaManagedAgentsRedactedBlock object { type }`
263 - `BetaManagedAgentsRedactedBlock object`
269264
270265 Placeholder for content withheld by Anthropic model policy.
271266
272267 - `type: "redacted"`
273268
274 - `"redacted"`
275
276269 - `type: "user.message"`
277270
278 - `"user.message"`
279
280271 - `processed_at: optional string or null`
281272
282273 A timestamp in RFC 3339 format
283274
284 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
275 format: date-time
276
277 - `BetaManagedAgentsUserInterruptEvent object`
285278
286279 An interrupt event that pauses agent execution and returns control to the user.
287280
from line 284
291284
292285 - `type: "user.interrupt"`
293286
294 - `"user.interrupt"`
295
296287 - `processed_at: optional string or null`
297288
298289 A timestamp in RFC 3339 format
299290
291 format: date-time
292
300293 - `session_thread_id: optional string or null`
301294
302295 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
303296
304 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
297 - `BetaManagedAgentsUserToolConfirmationEvent object`
305298
306299 A tool confirmation event that approves or denies a pending tool execution.
307300
from line 316
323316
324317 - `type: "user.tool_confirmation"`
325318
326 - `"user.tool_confirmation"`
327
328319 - `deny_message: optional string or null`
329320
330321 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
331322
323 maxLength: 10000
324
332325 - `processed_at: optional string or null`
333326
334327 A timestamp in RFC 3339 format
335328
329 format: date-time
330
336331 - `session_thread_id: optional string or null`
337332
338333 When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.
339334
340 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
335 - `BetaManagedAgentsUserCustomToolResultEvent object`
341336
342337 Event sent by the client providing the result of a custom tool execution.
343338
from line 346
351346
352347 - `type: "user.custom_tool_result"`
353348
354 - `"user.custom_tool_result"`
355
356349 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
357350
358351 The result content returned by the tool.
359352
360 - `BetaManagedAgentsTextBlock object { text, type }`
353 - `BetaManagedAgentsTextBlock object`
361354
362355 Regular text content.
363356
364 - `BetaManagedAgentsImageBlock object { source, type }`
357 - `BetaManagedAgentsImageBlock object`
365358
366359 Image content specified directly as base64 data or as a reference via a URL.
367360
368 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
361 - `BetaManagedAgentsDocumentBlock object`
369362
370363 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
371364
372 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
365 - `BetaManagedAgentsSearchResultBlock object`
373366
374367 A block containing a web search result.
375368
from line 382
389382
390383 The text content.
391384
385 minLength: 1
386
392387 - `type: "text"`
393388
394 - `"text"`
395
396389 - `source: string`
397390
398391 The URL source of the search result.
399392
393 minLength: 1
394
400395 - `title: string`
401396
402397 The title of the search result.
403398
399 minLength: 1
400
404401 - `type: "search_result"`
405402
406 - `"search_result"`
407
408403 - `is_error: optional boolean or null`
409404
410405 Whether the tool execution resulted in an error.
from line 408
413408
414409 A timestamp in RFC 3339 format
415410
411 format: date-time
412
416413 - `session_thread_id: optional string or null`
417414
418415 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
419416
420 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
417 - `BetaManagedAgentsAgentCustomToolUseEvent object`
421418
422419 Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.
423420
from line 434
437434
438435 A timestamp in RFC 3339 format
439436
437 format: date-time
438
440439 - `type: "agent.custom_tool_use"`
441440
442 - `"agent.custom_tool_use"`
443
444441 - `session_thread_id: optional string or null`
445442
446443 When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.
447444
448 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
445 - `BetaManagedAgentsAgentMessageEvent object`
449446
450447 An agent response event in the session conversation.
451448
from line 454
457454
458455 Array of text blocks comprising the agent response.
459456
460 - `BetaManagedAgentsTextBlock object { text, type }`
457 - `BetaManagedAgentsTextBlock object`
461458
462459 Regular text content.
463460
464 - `BetaManagedAgentsRedactedBlock object { type }`
461 - `BetaManagedAgentsRedactedBlock object`
465462
466463 Placeholder for content withheld by Anthropic model policy.
467464
from line 466
469466
470467 A timestamp in RFC 3339 format
471468
469 format: date-time
470
472471 - `type: "agent.message"`
473472
474 - `"agent.message"`
475
476 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
473 - `BetaManagedAgentsAgentThinkingEvent object`
477474
478475 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
479476
from line 482
485482
486483 A timestamp in RFC 3339 format
487484
485 format: date-time
486
488487 - `type: "agent.thinking"`
489488
490 - `"agent.thinking"`
491
492 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
489 - `BetaManagedAgentsAgentMCPToolUseEvent object`
493490
494491 Event emitted when the agent invokes a tool provided by an MCP server.
495492
from line 510
513510
514511 A timestamp in RFC 3339 format
515512
513 format: date-time
514
516515 - `type: "agent.mcp_tool_use"`
517516
518 - `"agent.mcp_tool_use"`
519
520517 - `evaluated_permission: optional "allow" or "ask" or "deny"`
521518
522519 AgentEvaluatedPermission enum
from line 528
531528
532529 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
533530
534 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
531 - `BetaManagedAgentsAgentMCPToolResultEvent object`
535532
536533 Event representing the result of an MCP tool execution.
537534
from line 544
547544
548545 A timestamp in RFC 3339 format
549546
547 format: date-time
548
550549 - `type: "agent.mcp_tool_result"`
551550
552 - `"agent.mcp_tool_result"`
553
554551 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
555552
556553 The result content returned by the tool.
557554
558 - `BetaManagedAgentsTextBlock object { text, type }`
555 - `BetaManagedAgentsTextBlock object`
559556
560557 Regular text content.
561558
562 - `BetaManagedAgentsImageBlock object { source, type }`
559 - `BetaManagedAgentsImageBlock object`
563560
564561 Image content specified directly as base64 data or as a reference via a URL.
565562
566 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
563 - `BetaManagedAgentsDocumentBlock object`
567564
568565 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
569566
570 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
567 - `BetaManagedAgentsSearchResultBlock object`
571568
572569 A block containing a web search result.
573570
from line 572
575572
576573 Whether the tool execution resulted in an error.
577574
578 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
575 - `BetaManagedAgentsAgentToolUseEvent object`
579576
580577 Event emitted when the agent invokes a built-in agent tool.
581578
from line 592
595592
596593 A timestamp in RFC 3339 format
597594
595 format: date-time
596
598597 - `type: "agent.tool_use"`
599598
600 - `"agent.tool_use"`
601
602599 - `evaluated_permission: optional "allow" or "ask" or "deny"`
603600
604601 AgentEvaluatedPermission enum
from line 610
613610
614611 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
615612
616 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
613 - `BetaManagedAgentsAgentToolResultEvent object`
617614
618615 Event representing the result of an agent tool execution.
619616
from line 622
625622
626623 A timestamp in RFC 3339 format
627624
625 format: date-time
626
628627 - `tool_use_id: string`
629628
630629 The id of the `agent.tool_use` event this result corresponds to.
631630
632631 - `type: "agent.tool_result"`
633632
634 - `"agent.tool_result"`
635
636633 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
637634
638635 The result content returned by the tool.
639636
640 - `BetaManagedAgentsTextBlock object { text, type }`
637 - `BetaManagedAgentsTextBlock object`
641638
642639 Regular text content.
643640
644 - `BetaManagedAgentsImageBlock object { source, type }`
641 - `BetaManagedAgentsImageBlock object`
645642
646643 Image content specified directly as base64 data or as a reference via a URL.
647644
648 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
645 - `BetaManagedAgentsDocumentBlock object`
649646
650647 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
651648
652 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
649 - `BetaManagedAgentsSearchResultBlock object`
653650
654651 A block containing a web search result.
655652
from line 654
657654
658655 Whether the tool execution resulted in an error.
659656
660 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
657 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
661658
662659 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
663660
from line 666
669666
670667 Message content blocks.
671668
672 - `BetaManagedAgentsTextBlock object { text, type }`
669 - `BetaManagedAgentsTextBlock object`
673670
674671 Regular text content.
675672
676 - `BetaManagedAgentsImageBlock object { source, type }`
673 - `BetaManagedAgentsImageBlock object`
677674
678675 Image content specified directly as base64 data or as a reference via a URL.
679676
680 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
677 - `BetaManagedAgentsDocumentBlock object`
681678
682679 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
683680
684 - `BetaManagedAgentsRedactedBlock object { type }`
681 - `BetaManagedAgentsRedactedBlock object`
685682
686683 Placeholder for content withheld by Anthropic model policy.
687684
from line 690
693690
694691 A timestamp in RFC 3339 format
695692
693 format: date-time
694
696695 - `type: "agent.thread_message_received"`
697696
698 - `"agent.thread_message_received"`
699
700697 - `from_agent_name: optional string or null`
701698
702699 Name of the callable agent this message came from. Absent when received from the primary agent.
703700
704 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
701 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
705702
706703 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
707704
from line 710
713710
714711 Message content blocks.
715712
716 - `BetaManagedAgentsTextBlock object { text, type }`
713 - `BetaManagedAgentsTextBlock object`
717714
718715 Regular text content.
719716
720 - `BetaManagedAgentsImageBlock object { source, type }`
717 - `BetaManagedAgentsImageBlock object`
721718
722719 Image content specified directly as base64 data or as a reference via a URL.
723720
724 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
721 - `BetaManagedAgentsDocumentBlock object`
725722
726723 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
727724
728 - `BetaManagedAgentsRedactedBlock object { type }`
725 - `BetaManagedAgentsRedactedBlock object`
729726
730727 Placeholder for content withheld by Anthropic model policy.
731728
from line 730
733730
734731 A timestamp in RFC 3339 format
735732
733 format: date-time
734
736735 - `to_session_thread_id: string`
737736
738737 Public `sthr_` ID of the thread the message was sent to.
739738
740739 - `type: "agent.thread_message_sent"`
741740
742 - `"agent.thread_message_sent"`
743
744741 - `to_agent_name: optional string or null`
745742
746743 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
747744
748 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
745 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
749746
750747 Indicates that context compaction (summarization) occurred during the session.
751748
from line 754
757754
758755 A timestamp in RFC 3339 format
759756
757 format: date-time
758
760759 - `type: "agent.thread_context_compacted"`
761760
762 - `"agent.thread_context_compacted"`
763
764 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
761 - `BetaManagedAgentsSessionErrorEvent object`
765762
766763 An error event indicating a problem occurred during session execution.
767764
from line 770
773770
774771 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
775772
776 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
773 - `BetaManagedAgentsUnknownError object`
777774
778775 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
779776
from line 782
785782
786783 What the client should do next in response to this error.
787784
788 - `BetaManagedAgentsRetryStatusRetrying object { type }`
785 - `BetaManagedAgentsRetryStatusRetrying object`
789786
790787 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
791788
792789 - `type: "retrying"`
793790
794 - `"retrying"`
795
796 - `BetaManagedAgentsRetryStatusExhausted object { type }`
791 - `BetaManagedAgentsRetryStatusExhausted object`
797792
798793 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
799794
800795 - `type: "exhausted"`
801796
802 - `"exhausted"`
803
804 - `BetaManagedAgentsRetryStatusTerminal object { type }`
797 - `BetaManagedAgentsRetryStatusTerminal object`
805798
806799 The session encountered a terminal error and will transition to `terminated` state.
807800
808801 - `type: "terminal"`
809802
810 - `"terminal"`
811
812803 - `type: "unknown_error"`
813804
814 - `"unknown_error"`
815
816 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
805 - `BetaManagedAgentsModelOverloadedError object`
817806
818807 The model is currently overloaded. Emitted after automatic retries are exhausted.
819808
from line 814
825814
826815 What the client should do next in response to this error.
827816
828 - `BetaManagedAgentsRetryStatusRetrying object { type }`
817 - `BetaManagedAgentsRetryStatusRetrying object`
829818
830819 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
831820
832 - `BetaManagedAgentsRetryStatusExhausted object { type }`
821 - `BetaManagedAgentsRetryStatusExhausted object`
833822
834823 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
835824
836 - `BetaManagedAgentsRetryStatusTerminal object { type }`
825 - `BetaManagedAgentsRetryStatusTerminal object`
837826
838827 The session encountered a terminal error and will transition to `terminated` state.
839828
840829 - `type: "model_overloaded_error"`
841830
842 - `"model_overloaded_error"`
843
844 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
831 - `BetaManagedAgentsModelRateLimitedError object`
845832
846833 The model request was rate-limited.
847834
from line 840
853840
854841 What the client should do next in response to this error.
855842
856 - `BetaManagedAgentsRetryStatusRetrying object { type }`
843 - `BetaManagedAgentsRetryStatusRetrying object`
857844
858845 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
859846
860 - `BetaManagedAgentsRetryStatusExhausted object { type }`
847 - `BetaManagedAgentsRetryStatusExhausted object`
861848
862849 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
863850
864 - `BetaManagedAgentsRetryStatusTerminal object { type }`
851 - `BetaManagedAgentsRetryStatusTerminal object`
865852
866853 The session encountered a terminal error and will transition to `terminated` state.
867854
868855 - `type: "model_rate_limited_error"`
869856
870 - `"model_rate_limited_error"`
871
872 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
857 - `BetaManagedAgentsModelRequestFailedError object`
873858
874859 A model request failed for a reason other than overload or rate-limiting.
875860
from line 866
881866
882867 What the client should do next in response to this error.
883868
884 - `BetaManagedAgentsRetryStatusRetrying object { type }`
869 - `BetaManagedAgentsRetryStatusRetrying object`
885870
886871 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
887872
888 - `BetaManagedAgentsRetryStatusExhausted object { type }`
873 - `BetaManagedAgentsRetryStatusExhausted object`
889874
890875 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
891876
892 - `BetaManagedAgentsRetryStatusTerminal object { type }`
877 - `BetaManagedAgentsRetryStatusTerminal object`
893878
894879 The session encountered a terminal error and will transition to `terminated` state.
895880
896881 - `type: "model_request_failed_error"`
897882
898 - `"model_request_failed_error"`
899
900 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
883 - `BetaManagedAgentsMCPConnectionFailedError object`
901884
902885 Failed to connect to an MCP server.
903886
from line 896
913896
914897 What the client should do next in response to this error.
915898
916 - `BetaManagedAgentsRetryStatusRetrying object { type }`
899 - `BetaManagedAgentsRetryStatusRetrying object`
917900
918901 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
919902
920 - `BetaManagedAgentsRetryStatusExhausted object { type }`
903 - `BetaManagedAgentsRetryStatusExhausted object`
921904
922905 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
923906
924 - `BetaManagedAgentsRetryStatusTerminal object { type }`
907 - `BetaManagedAgentsRetryStatusTerminal object`
925908
926909 The session encountered a terminal error and will transition to `terminated` state.
927910
928911 - `type: "mcp_connection_failed_error"`
929912
930 - `"mcp_connection_failed_error"`
931
932 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
913 - `BetaManagedAgentsMCPAuthenticationFailedError object`
933914
934915 Authentication to an MCP server failed.
935916
from line 926
945926
946927 What the client should do next in response to this error.
947928
948 - `BetaManagedAgentsRetryStatusRetrying object { type }`
929 - `BetaManagedAgentsRetryStatusRetrying object`
949930
950931 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
951932
952 - `BetaManagedAgentsRetryStatusExhausted object { type }`
933 - `BetaManagedAgentsRetryStatusExhausted object`
953934
954935 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
955936
956 - `BetaManagedAgentsRetryStatusTerminal object { type }`
937 - `BetaManagedAgentsRetryStatusTerminal object`
957938
958939 The session encountered a terminal error and will transition to `terminated` state.
959940
960941 - `type: "mcp_authentication_failed_error"`
961942
962 - `"mcp_authentication_failed_error"`
963
964 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
943 - `BetaManagedAgentsBillingError object`
965944
966945 The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
967946
from line 952
973952
974953 What the client should do next in response to this error.
975954
976 - `BetaManagedAgentsRetryStatusRetrying object { type }`
955 - `BetaManagedAgentsRetryStatusRetrying object`
977956
978957 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
979958
980 - `BetaManagedAgentsRetryStatusExhausted object { type }`
959 - `BetaManagedAgentsRetryStatusExhausted object`
981960
982961 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
983962
984 - `BetaManagedAgentsRetryStatusTerminal object { type }`
963 - `BetaManagedAgentsRetryStatusTerminal object`
985964
986965 The session encountered a terminal error and will transition to `terminated` state.
987966
988967 - `type: "billing_error"`
989968
990 - `"billing_error"`
991
992 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
969 - `BetaManagedAgentsCredentialHostUnreachableError object`
993970
994971 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
995972
from line 982
1005982
1006983 What the client should do next in response to this error.
1007984
1008 - `BetaManagedAgentsRetryStatusRetrying object { type }`
985 - `BetaManagedAgentsRetryStatusRetrying object`
1009986
1010987 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
1011988
1012 - `BetaManagedAgentsRetryStatusExhausted object { type }`
989 - `BetaManagedAgentsRetryStatusExhausted object`
1013990
1014991 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1015992
1016 - `BetaManagedAgentsRetryStatusTerminal object { type }`
993 - `BetaManagedAgentsRetryStatusTerminal object`
1017994
1018995 The session encountered a terminal error and will transition to `terminated` state.
1019996
1020997 - `type: "credential_host_unreachable_error"`
1021998
1022 - `"credential_host_unreachable_error"`
1023
1024999 - `vault_id: string`
10251000
10261001 ID of the vault containing the affected credential.
from line 1004
10291004
10301005 A timestamp in RFC 3339 format
10311006
1007 format: date-time
1008
10321009 - `type: "session.error"`
10331010
1034 - `"session.error"`
1035
1036 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
1011 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
10371012
10381013 Indicates the session is recovering from an error state and is rescheduled for execution.
10391014
from line 1020
10451020
10461021 A timestamp in RFC 3339 format
10471022
1023 format: date-time
1024
10481025 - `type: "session.status_rescheduled"`
10491026
1050 - `"session.status_rescheduled"`
1051
1052 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
1027 - `BetaManagedAgentsSessionStatusRunningEvent object`
10531028
10541029 Indicates the session is actively running and the agent is working.
10551030
from line 1036
10611036
10621037 A timestamp in RFC 3339 format
10631038
1039 format: date-time
1040
10641041 - `type: "session.status_running"`
10651042
1066 - `"session.status_running"`
1067
1068 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
1043 - `BetaManagedAgentsSessionStatusIdleEvent object`
10691044
10701045 Indicates the agent has paused and is awaiting user input.
10711046
from line 1052
10771052
10781053 A timestamp in RFC 3339 format
10791054
1055 format: date-time
1056
10801057 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
10811058
10821059 The agent completed its turn naturally and is ready for the next user message.
10831060
1084 - `BetaManagedAgentsSessionEndTurn object { type }`
1061 - `BetaManagedAgentsSessionEndTurn object`
10851062
10861063 The agent completed its turn naturally and is ready for the next user message.
10871064
10881065 - `type: "end_turn"`
10891066
1090 - `"end_turn"`
1091
1092 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1067 - `BetaManagedAgentsSessionRequiresAction object`
10931068
10941069 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
10951070
from line 1074
10991074
11001075 - `type: "requires_action"`
11011076
1102 - `"requires_action"`
1103
1104 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1077 - `BetaManagedAgentsSessionRetriesExhausted object`
11051078
11061079 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
11071080
11081081 - `type: "retries_exhausted"`
11091082
1110 - `"retries_exhausted"`
1111
1112 - `BetaManagedAgentsSessionBudgetReached object { type }`
1083 - `BetaManagedAgentsSessionBudgetReached object`
11131084
11141085 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
11151086
11161087 - `type: "budget_reached"`
11171088
1118 - `"budget_reached"`
1119
11201089 - `type: "session.status_idle"`
11211090
1122 - `"session.status_idle"`
1123
1124 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
1091 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
11251092
11261093 Indicates the session has terminated, either due to an error or completion.
11271094
from line 1100
11331100
11341101 A timestamp in RFC 3339 format
11351102
1103 format: date-time
1104
11361105 - `type: "session.status_terminated"`
11371106
1138 - `"session.status_terminated"`
1139
1140 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
1107 - `BetaManagedAgentsSessionThreadCreatedEvent object`
11411108
11421109 Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
11431110
from line 1120
11531120
11541121 A timestamp in RFC 3339 format
11551122
1123 format: date-time
1124
11561125 - `session_thread_id: string`
11571126
11581127 Public `sthr_` ID of the newly created thread.
11591128
11601129 - `type: "session.thread_created"`
11611130
1162 - `"session.thread_created"`
1163
1164 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
1131 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
11651132
11661133 Emitted when an outcome evaluation cycle begins.
11671134
from line 1140
11731140
11741141 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
11751142
1143 format: int32
1144
11761145 - `outcome_id: string`
11771146
11781147 The `outc_` ID of the outcome being evaluated.
from line 1150
11811150
11821151 A timestamp in RFC 3339 format
11831152
1153 format: date-time
1154
11841155 - `type: "span.outcome_evaluation_start"`
11851156
1186 - `"span.outcome_evaluation_start"`
1187
1188 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
1157 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
11891158
11901159 Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.
11911160
from line 1170
12011170
12021171 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
12031172
1173 format: int32
1174
12041175 - `outcome_evaluation_start_id: string`
12051176
12061177 The id of the corresponding `span.outcome_evaluation_start` event.
from line 1184
12131184
12141185 A timestamp in RFC 3339 format
12151186
1187 format: date-time
1188
12161189 - `result: string`
12171190
12181191 Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
12191192
12201193 - `type: "span.outcome_evaluation_end"`
12211194
1222 - `"span.outcome_evaluation_end"`
1223
12241195 - `usage: BetaManagedAgentsSpanModelUsage`
12251196
12261197 Token usage for a single model request.
from line 1200
12291200
12301201 Tokens used to create prompt cache in this request.
12311202
1203 format: int32
1204
12321205 - `cache_read_input_tokens: number`
12331206
12341207 Tokens read from prompt cache in this request.
12351208
1209 format: int32
1210
12361211 - `input_tokens: number`
12371212
12381213 Input tokens consumed by this request.
12391214
1215 format: int32
1216
12401217 - `output_tokens: number`
12411218
12421219 Output tokens generated by this request.
12431220
1221 format: int32
1222
12441223 - `speed: optional "standard" or "fast" or null`
12451224
12461225 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1228
12491228
12501229 - `"fast"`
12511230
1252 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
1231 - `BetaManagedAgentsSpanModelRequestStartEvent object`
12531232
12541233 Emitted when a model request is initiated by the agent.
12551234
from line 1240
12611240
12621241 A timestamp in RFC 3339 format
12631242
1243 format: date-time
1244
12641245 - `type: "span.model_request_start"`
12651246
1266 - `"span.model_request_start"`
1267
1268 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
1247 - `BetaManagedAgentsSpanModelRequestEndEvent object`
12691248
12701249 Emitted when a model request completes.
12711250
from line 1268
12891268
12901269 A timestamp in RFC 3339 format
12911270
1271 format: date-time
1272
12921273 - `type: "span.model_request_end"`
12931274
1294 - `"span.model_request_end"`
1295
1296 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
1275 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
12971276
12981277 Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.
12991278
from line 1284
13051284
13061285 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
13071286
1287 format: int32
1288
13081289 - `outcome_id: string`
13091290
13101291 The `outc_` ID of the outcome being evaluated.
from line 1294
13131294
13141295 A timestamp in RFC 3339 format
13151296
1297 format: date-time
1298
13161299 - `type: "span.outcome_evaluation_ongoing"`
13171300
1318 - `"span.outcome_evaluation_ongoing"`
1319
1320 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
1301 - `BetaManagedAgentsUserDefineOutcomeEvent object`
13211302
13221303 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
13231304
from line 1314
13331314
13341315 Evaluate-then-revise cycles before giving up. Default 3, max 20.
13351316
1317 format: int32
1318
13361319 - `outcome_id: string`
13371320
13381321 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1324
13411324
13421325 A timestamp in RFC 3339 format
13431326
1327 format: date-time
1328
13441329 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
13451330
13461331 Rubric for grading the quality of an outcome.
13471332
1348 - `BetaManagedAgentsFileRubric object { file_id, type }`
1333 - `BetaManagedAgentsFileRubric object`
13491334
13501335 Rubric referenced by a file uploaded via the Files API.
13511336
from line 1340
13551340
13561341 - `type: "file"`
13571342
1358 - `"file"`
1359
1360 - `BetaManagedAgentsTextRubric object { content, type }`
1343 - `BetaManagedAgentsTextRubric object`
13611344
13621345 Rubric content provided inline as text.
13631346
from line 1350
13671350
13681351 - `type: "text"`
13691352
1370 - `"text"`
1371
13721353 - `type: "user.define_outcome"`
13731354
1374 - `"user.define_outcome"`
1375
1376 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
1355 - `BetaManagedAgentsSessionDeletedEvent object`
13771356
13781357 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
13791358
from line 1364
13851364
13861365 A timestamp in RFC 3339 format
13871366
1367 format: date-time
1368
13881369 - `type: "session.deleted"`
13891370
1390 - `"session.deleted"`
1391
1392 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
1371 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
13931372
13941373 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
13951374
from line 1384
14051384
14061385 A timestamp in RFC 3339 format
14071386
1387 format: date-time
1388
14081389 - `session_thread_id: string`
14091390
14101391 Public sthr_ ID of the thread that started running.
14111392
14121393 - `type: "session.thread_status_running"`
14131394
1414 - `"session.thread_status_running"`
1415
1416 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
1395 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
14171396
14181397 A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14191398
from line 1408
14291408
14301409 A timestamp in RFC 3339 format
14311410
1411 format: date-time
1412
14321413 - `session_thread_id: string`
14331414
14341415 Public sthr_ ID of the thread that went idle.
from line 1418
14371418
14381419 The agent completed its turn naturally and is ready for the next user message.
14391420
1440 - `BetaManagedAgentsSessionEndTurn object { type }`
1421 - `BetaManagedAgentsSessionEndTurn object`
14411422
14421423 The agent completed its turn naturally and is ready for the next user message.
14431424
1444 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1425 - `BetaManagedAgentsSessionRequiresAction object`
14451426
14461427 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
14471428
1448 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1429 - `BetaManagedAgentsSessionRetriesExhausted object`
14491430
14501431 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
14511432
1452 - `BetaManagedAgentsSessionBudgetReached object { type }`
1433 - `BetaManagedAgentsSessionBudgetReached object`
14531434
14541435 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
14551436
14561437 - `type: "session.thread_status_idle"`
14571438
1458 - `"session.thread_status_idle"`
1459
1460 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
1439 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
14611440
14621441 A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14631442
from line 1452
14731452
14741453 A timestamp in RFC 3339 format
14751454
1455 format: date-time
1456
14761457 - `session_thread_id: string`
14771458
14781459 Public sthr_ ID of the thread that terminated.
14791460
14801461 - `type: "session.thread_status_terminated"`
14811462
1482 - `"session.thread_status_terminated"`
1483
1484 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
1463 - `BetaManagedAgentsUserToolResultEvent object`
14851464
14861465 Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.
14871466
from line 1474
14951474
14961475 - `type: "user.tool_result"`
14971476
1498 - `"user.tool_result"`
1499
15001477 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
15011478
15021479 The result content returned by the tool.
15031480
1504 - `BetaManagedAgentsTextBlock object { text, type }`
1481 - `BetaManagedAgentsTextBlock object`
15051482
15061483 Regular text content.
15071484
1508 - `BetaManagedAgentsImageBlock object { source, type }`
1485 - `BetaManagedAgentsImageBlock object`
15091486
15101487 Image content specified directly as base64 data or as a reference via a URL.
15111488
1512 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1489 - `BetaManagedAgentsDocumentBlock object`
15131490
15141491 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
15151492
1516 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
1493 - `BetaManagedAgentsSearchResultBlock object`
15171494
15181495 A block containing a web search result.
15191496
from line 1502
15251502
15261503 A timestamp in RFC 3339 format
15271504
1505 format: date-time
1506
15281507 - `session_thread_id: optional string or null`
15291508
15301509 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
15311510
1532 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
1511 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
15331512
15341513 A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
15351514
from line 1524
15451524
15461525 A timestamp in RFC 3339 format
15471526
1527 format: date-time
1528
15481529 - `session_thread_id: string`
15491530
15501531 Public sthr_ ID of the thread that is retrying.
15511532
15521533 - `type: "session.thread_status_rescheduled"`
15531534
1554 - `"session.thread_status_rescheduled"`
1555
1556 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
1535 - `BetaManagedAgentsSessionUpdatedEvent object`
15571536
15581537 Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
15591538
from line 1544
15651544
15661545 A timestamp in RFC 3339 format
15671546
1547 format: date-time
1548
15681549 - `type: "session.updated"`
15691550
1570 - `"session.updated"`
1571
15721551 - `agent: optional BetaManagedAgentsSessionAgent or null`
15731552
15741553 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1562
15831562
15841563 - `type: "url"`
15851564
1586 - `"url"`
1587
15881565 - `url: string`
15891566
15901567 - `model: BetaManagedAgentsModelConfig`
from line 1638
16611638
16621639 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16631640
1664 - `BetaManagedAgentsEffortLow object { type }`
1641 - `BetaManagedAgentsEffortLow object`
16651642
16661643 Low effort. Favors latency over reasoning depth.
16671644
16681645 - `type: "low"`
16691646
1670 - `"low"`
1671
1672 - `BetaManagedAgentsEffortMedium object { type }`
1647 - `BetaManagedAgentsEffortMedium object`
16731648
16741649 Medium effort. Balances latency and reasoning depth.
16751650
16761651 - `type: "medium"`
16771652
1678 - `"medium"`
1679
1680 - `BetaManagedAgentsEffortHigh object { type }`
1653 - `BetaManagedAgentsEffortHigh object`
16811654
16821655 High effort. Favors reasoning depth.
16831656
16841657 - `type: "high"`
16851658
1686 - `"high"`
1687
1688 - `BetaManagedAgentsEffortXhigh object { type }`
1659 - `BetaManagedAgentsEffortXhigh object`
16891660
16901661 Extra-high effort. Not all models accept this level.
16911662
16921663 - `type: "xhigh"`
16931664
1694 - `"xhigh"`
1695
1696 - `BetaManagedAgentsEffortMax object { type }`
1665 - `BetaManagedAgentsEffortMax object`
16971666
16981667 Maximum effort. Favors reasoning depth over latency.
16991668
17001669 - `type: "max"`
17011670
1702 - `"max"`
1703
17041671 - `inference_geo: optional string`
17051672
17061673 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1688
17211688
17221689 Full `agent` definitions the coordinator may spawn as session threads.
17231690
1724 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1691 - `BetaManagedAgentsSessionThreadAgent object`
17251692
17261693 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`.
17271694
from line 1712
17451712
17461713 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17471714
1748 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1715 - `BetaManagedAgentsAnthropicSkill object`
17491716
17501717 A resolved Anthropic-managed skill.
17511718
from line 1720
17531720
17541721 - `type: "anthropic"`
17551722
1756 - `"anthropic"`
1757
17581723 - `version: string`
17591724
1760 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1725 - `BetaManagedAgentsCustomSkill object`
17611726
17621727 A resolved user-created custom skill.
17631728
from line 1730
17651730
17661731 - `type: "custom"`
17671732
1768 - `"custom"`
1769
17701733 - `version: string`
17711734
17721735 - `system: string or null`
17731736
17741737 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17751738
1776 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1739 - `BetaManagedAgentsAgentToolset20260401 object`
17771740
17781741 - `configs: array of BetaManagedAgentsAgentToolConfig`
17791742
1780 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1743 - `BetaManagedAgentsBashToolConfig object`
17811744
17821745 Configuration for the bash tool.
17831746
from line 1748
17851748
17861749 - `name: "bash"`
17871750
1788 - `"bash"`
1789
17901751 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
17911752
17921753 Permission policy for tool execution.
17931754
1794 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1755 - `BetaManagedAgentsAlwaysAllowPolicy object`
17951756
17961757 Tool calls are automatically approved without user confirmation.
17971758
17981759 - `type: "always_allow"`
17991760
1800 - `"always_allow"`
1801
1802 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1761 - `BetaManagedAgentsAlwaysAskPolicy object`
18031762
18041763 Tool calls require user confirmation before execution.
18051764
18061765 - `type: "always_ask"`
18071766
1808 - `"always_ask"`
1809
18101767 - `type: "bash"`
18111768
1812 - `"bash"`
1813
1814 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1769 - `BetaManagedAgentsEditToolConfig object`
18151770
18161771 Configuration for the edit tool.
18171772
from line 1774
18191774
18201775 - `name: "edit"`
18211776
1822 - `"edit"`
1823
18241777 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18251778
18261779 Permission policy for tool execution.
18271780
1828 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1781 - `BetaManagedAgentsAlwaysAllowPolicy object`
18291782
18301783 Tool calls are automatically approved without user confirmation.
18311784
1832 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1785 - `BetaManagedAgentsAlwaysAskPolicy object`
18331786
18341787 Tool calls require user confirmation before execution.
18351788
18361789 - `type: "edit"`
18371790
1838 - `"edit"`
1839
1840 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1791 - `BetaManagedAgentsReadToolConfig object`
18411792
18421793 Configuration for the read tool.
18431794
from line 1796
18451796
18461797 - `name: "read"`
18471798
1848 - `"read"`
1849
18501799 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18511800
18521801 Permission policy for tool execution.
18531802
1854 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1803 - `BetaManagedAgentsAlwaysAllowPolicy object`
18551804
18561805 Tool calls are automatically approved without user confirmation.
18571806
1858 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1807 - `BetaManagedAgentsAlwaysAskPolicy object`
18591808
18601809 Tool calls require user confirmation before execution.
18611810
18621811 - `type: "read"`
18631812
1864 - `"read"`
1865
1866 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1813 - `BetaManagedAgentsWriteToolConfig object`
18671814
18681815 Configuration for the write tool.
18691816
from line 1818
18711818
18721819 - `name: "write"`
18731820
1874 - `"write"`
1875
18761821 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18771822
18781823 Permission policy for tool execution.
18791824
1880 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1825 - `BetaManagedAgentsAlwaysAllowPolicy object`
18811826
18821827 Tool calls are automatically approved without user confirmation.
18831828
1884 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1829 - `BetaManagedAgentsAlwaysAskPolicy object`
18851830
18861831 Tool calls require user confirmation before execution.
18871832
18881833 - `type: "write"`
18891834
1890 - `"write"`
1891
1892 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1835 - `BetaManagedAgentsGlobToolConfig object`
18931836
18941837 Configuration for the glob tool.
18951838
from line 1840
18971840
18981841 - `name: "glob"`
18991842
1900 - `"glob"`
1901
19021843 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19031844
19041845 Permission policy for tool execution.
19051846
1906 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1847 - `BetaManagedAgentsAlwaysAllowPolicy object`
19071848
19081849 Tool calls are automatically approved without user confirmation.
19091850
1910 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1851 - `BetaManagedAgentsAlwaysAskPolicy object`
19111852
19121853 Tool calls require user confirmation before execution.
19131854
19141855 - `type: "glob"`
19151856
1916 - `"glob"`
1917
1918 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1857 - `BetaManagedAgentsGrepToolConfig object`
19191858
19201859 Configuration for the grep tool.
19211860
from line 1862
19231862
19241863 - `name: "grep"`
19251864
1926 - `"grep"`
1927
19281865 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19291866
19301867 Permission policy for tool execution.
19311868
1932 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1869 - `BetaManagedAgentsAlwaysAllowPolicy object`
19331870
19341871 Tool calls are automatically approved without user confirmation.
19351872
1936 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1873 - `BetaManagedAgentsAlwaysAskPolicy object`
19371874
19381875 Tool calls require user confirmation before execution.
19391876
19401877 - `type: "grep"`
19411878
1942 - `"grep"`
1943
1944 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1879 - `BetaManagedAgentsWebFetchToolConfig object`
19451880
19461881 Configuration for the web_fetch tool.
19471882
from line 1884
19491884
19501885 - `name: "web_fetch"`
19511886
1952 - `"web_fetch"`
1953
19541887 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19551888
19561889 Permission policy for tool execution.
19571890
1958 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1891 - `BetaManagedAgentsAlwaysAllowPolicy object`
19591892
19601893 Tool calls are automatically approved without user confirmation.
19611894
1962 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1895 - `BetaManagedAgentsAlwaysAskPolicy object`
19631896
19641897 Tool calls require user confirmation before execution.
19651898
19661899 - `type: "web_fetch"`
19671900
1968 - `"web_fetch"`
1969
19701901 - `allowed_domains: optional array of string`
19711902
19721903 - `blocked_domains: optional array of string`
19731904
19741905 - `max_content_tokens: optional number or null`
19751906
1976 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1907 format: int32
1908
1909 - `BetaManagedAgentsWebSearchToolConfig object`
19771910
19781911 Configuration for the web_search tool.
19791912
from line 1914
19811914
19821915 - `name: "web_search"`
19831916
1984 - `"web_search"`
1985
19861917 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19871918
19881919 Permission policy for tool execution.
19891920
1990 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1921 - `BetaManagedAgentsAlwaysAllowPolicy object`
19911922
19921923 Tool calls are automatically approved without user confirmation.
19931924
1994 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1925 - `BetaManagedAgentsAlwaysAskPolicy object`
19951926
19961927 Tool calls require user confirmation before execution.
19971928
19981929 - `type: "web_search"`
19991930
2000 - `"web_search"`
2001
20021931 - `allowed_domains: optional array of string`
20031932
20041933 - `blocked_domains: optional array of string`
from line 1940
20111940
20121941 Location precision. Only "approximate" is supported.
20131942
2014 - `"approximate"`
2015
20161943 - `city: optional string or null`
20171944
20181945 City name.
20191946
1947 minLength: 1, maxLength: 255
1948
20201949 - `country: optional string or null`
20211950
20221951 Two-letter ISO 3166-1 country code, uppercase.
from line 1954
20251954
20261955 Region or state name.
20271956
1957 minLength: 1, maxLength: 255
1958
20281959 - `timezone: optional string or null`
20291960
20301961 IANA timezone identifier, e.g. "America/Los_Angeles".
20311962
1963 minLength: 1, maxLength: 255
1964
20321965 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20331966
20341967 Resolved default configuration for agent tools.
from line 1972
20391972
20401973 Permission policy for tool execution.
20411974
2042 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1975 - `BetaManagedAgentsAlwaysAllowPolicy object`
20431976
20441977 Tool calls are automatically approved without user confirmation.
20451978
2046 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1979 - `BetaManagedAgentsAlwaysAskPolicy object`
20471980
20481981 Tool calls require user confirmation before execution.
20491982
20501983 - `type: "agent_toolset_20260401"`
20511984
2052 - `"agent_toolset_20260401"`
2053
2054 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1985 - `BetaManagedAgentsMCPToolset object`
20551986
20561987 - `configs: array of BetaManagedAgentsMCPToolConfig`
20571988
from line 1994
20631994
20641995 Permission policy for tool execution.
20651996
2066 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1997 - `BetaManagedAgentsAlwaysAllowPolicy object`
20671998
20681999 Tool calls are automatically approved without user confirmation.
20692000
2070 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2001 - `BetaManagedAgentsAlwaysAskPolicy object`
20712002
20722003 Tool calls require user confirmation before execution.
20732004
from line 2012
20812012
20822013 Permission policy for tool execution.
20832014
2084 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2015 - `BetaManagedAgentsAlwaysAllowPolicy object`
20852016
20862017 Tool calls are automatically approved without user confirmation.
20872018
2088 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2019 - `BetaManagedAgentsAlwaysAskPolicy object`
20892020
20902021 Tool calls require user confirmation before execution.
20912022
from line 2024
20932024
20942025 - `type: "mcp_toolset"`
20952026
2096 - `"mcp_toolset"`
2097
2098 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2027 - `BetaManagedAgentsCustomTool object`
20992028
21002029 A custom tool as returned in API responses.
21012030
from line 2036
21072036
21082037 - `type: "object"`
21092038
2110 - `"object"`
2111
21122039 - `properties: optional map[unknown] or null`
21132040
21142041 - `required: optional array of string or null`
from line 2044
21172044
21182045 - `type: "custom"`
21192046
2120 - `"custom"`
2121
21222047 - `type: "agent"`
21232048
2124 - `"agent"`
2125
21262049 - `version: number`
21272050
2128 - `BetaManagedAgentsAdvisor object { model, type }`
2051 format: int32
2052
2053 - `BetaManagedAgentsAdvisor object`
21292054
21302055 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
21312056
from line 2060
21352060
21362061 - `type: "advisor"`
21372062
2138 - `"advisor"`
2139
21402063 - `type: "coordinator"`
21412064
2142 - `"coordinator"`
2143
21442065 - `name: string`
21452066
21462067 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
21472068
2148 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2069 - `BetaManagedAgentsAnthropicSkill object`
21492070
21502071 A resolved Anthropic-managed skill.
21512072
2152 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2073 - `BetaManagedAgentsCustomSkill object`
21532074
21542075 A resolved user-created custom skill.
21552076
from line 2078
21572078
21582079 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
21592080
2160 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2161
2162 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2163
2164 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2081 - `BetaManagedAgentsAgentToolset20260401 object`
2082
2083 - `BetaManagedAgentsMCPToolset object`
2084
2085 - `BetaManagedAgentsCustomTool object`
21652086
21662087 A custom tool as returned in API responses.
21672088
21682089 - `type: "agent"`
21692090
2170 - `"agent"`
2171
21722091 - `version: number`
21732092
2093 format: int32
2094
21742095 - `budget: optional BetaManagedAgentsBudgetLimit or null`
21752096
21762097 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2108
21872108
21882109 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.
21892110
2190 - `"USD"`
2191
21922111 - `type: "limit"`
21932112
2194 - `"limit"`
2195
21962113 - `metadata: optional map[string]`
21972114
21982115 The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
from line 2118
22012118
22022119 The session's new title. Present only when the update changed it.
22032120
2204 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
2121 - `BetaManagedAgentsSystemMessageEvent object`
22052122
22062123 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
22072124
from line 2134
22172134
22182135 The text content.
22192136
2137 minLength: 1
2138
22202139 - `type: "text"`
22212140
2222 - `"text"`
2223
22242141 - `type: "system.message"`
22252142
2226 - `"system.message"`
2227
22282143 - `processed_at: optional string or null`
22292144
22302145 A timestamp in RFC 3339 format
22312146
2232 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
2147 format: date-time
2148
2149 - `BetaManagedAgentsSessionUsageEvent object`
22332150
22342151 Periodic snapshot of the session's cumulative usage and tracked list cost.
22352152
from line 2158
22412158
22422159 A timestamp in RFC 3339 format
22432160
2161 format: date-time
2162
22442163 - `type: "session.usage"`
22452164
2246 - `"session.usage"`
2247
22482165 - `usage: BetaManagedAgentsSessionUsageSnapshot`
22492166
22502167 Point-in-time snapshot of a session's cumulative usage.
from line 2170
22532170
22542171 Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
22552172
2173 format: double
2174
22562175 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
22572176
22582177 Prompt-cache creation token usage broken down by cache lifetime.
from line 2180
22612180
22622181 Tokens used to create 1-hour ephemeral cache entries.
22632182
2183 format: int32
2184
22642185 - `ephemeral_5m_input_tokens: optional number`
22652186
22662187 Tokens used to create 5-minute ephemeral cache entries.
22672188
2189 format: int32
2190
22682191 - `cache_read_input_tokens: optional number`
22692192
22702193 Total tokens read from prompt cache.
22712194
2195 format: int32
2196
22722197 - `input_tokens: optional number`
22732198
22742199 Total input tokens consumed across all turns.
22752200
2201 format: int32
2202
22762203 - `list_cost: optional BetaMonetaryAmount`
22772204
22782205 A monetary amount in a specific currency.
from line 2208
22812208
22822209 Total output tokens generated across all turns.
22832210
2211 format: int32
2212
22842213 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
22852214
22862215 Cumulative count of server-executed tool invocations, broken down by tool.
from line 2218
22892218
22902219 Number of server-executed web fetch requests.
22912220
2221 format: int32
2222
22922223 - `web_search_requests: optional number`
22932224
22942225 Number of server-executed web search requests.
22952226
2227 format: int32
2228
22962229 - `budget: optional BetaManagedAgentsBudgetLimit or null`
22972230
22982231 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2236
23032236
23042237### Example
23052238
2306```http
2239```bash
23072240curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events \
23082241 -H 'anthropic-version: 2023-06-01' \
23092242 -H 'anthropic-beta: managed-agents-2026-04-01' \
23102243 -H "X-Api-Key: $ANTHROPIC_API_KEY"
23112244```
23122245
2313#### Response
2246#### Response (200)
23142247
23152248```json
23162249{
from line 2266
23332266
23342267## Stream Session Thread Events
23352268
2336**get** `/v1/sessions/{session_id}/threads/{thread_id}/stream`
2269**GET** `/v1/sessions/{session_id}/threads/{thread_id}/stream`
23372270
23382271Stream Session Thread Events
23392272
2340### Path Parameters
2273### Path parameters
23412274
23422275- `session_id: string`
23432276
23442277- `thread_id: string`
23452278
2346### Query Parameters
2279### Query parameters
23472280
23482281- `event_deltas: optional array of BetaManagedAgentsDeltaType`
23492282
from line 2286
23532286
23542287 - `"agent.thinking"`
23552288
2356### Header Parameters
2289### Headers
23572290
23582291- `"anthropic-beta": optional array of AnthropicBeta`
23592292
from line 2370
24372370
24382371 Server-sent event in a single thread's stream.
24392372
2440 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
2373 - `BetaManagedAgentsUserMessageEvent object`
24412374
24422375 A user message event in the session conversation.
24432376
from line 2382
24492382
24502383 Array of content blocks comprising the user message.
24512384
2452 - `BetaManagedAgentsTextBlock object { text, type }`
2385 - `BetaManagedAgentsTextBlock object`
24532386
24542387 Regular text content.
24552388
from line 2390
24572390
24582391 The text content.
24592392
2393 minLength: 1
2394
24602395 - `type: "text"`
24612396
2462 - `"text"`
2463
2464 - `BetaManagedAgentsImageBlock object { source, type }`
2397 - `BetaManagedAgentsImageBlock object`
24652398
24662399 Image content specified directly as base64 data or as a reference via a URL.
24672400
from line 2402
24692402
24702403 Union type for image source variants.
24712404
2472 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
2405 - `BetaManagedAgentsBase64ImageSource object`
24732406
24742407 Base64-encoded image data.
24752408
from line 2410
24772410
24782411 Base64-encoded image data.
24792412
2413 minLength: 1
2414
24802415 - `media_type: string`
24812416
24822417 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
24832418
2419 minLength: 1
2420
24842421 - `type: "base64"`
24852422
2486 - `"base64"`
2487
2488 - `BetaManagedAgentsURLImageSource object { type, url }`
2423 - `BetaManagedAgentsURLImageSource object`
24892424
24902425 Image referenced by URL.
24912426
24922427 - `type: "url"`
24932428
2494 - `"url"`
2495
24962429 - `url: string`
24972430
24982431 URL of the image to fetch.
24992432
2500 - `BetaManagedAgentsFileImageSource object { file_id, type }`
2433 minLength: 1
2434
2435 - `BetaManagedAgentsFileImageSource object`
25012436
25022437 Image referenced by file ID.
25032438
from line 2440
25052440
25062441 ID of a previously uploaded file.
25072442
2443 minLength: 1
2444
25082445 - `type: "file"`
25092446
2510 - `"file"`
2511
25122447 - `type: "image"`
25132448
2514 - `"image"`
2515
2516 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2449 - `BetaManagedAgentsDocumentBlock object`
25172450
25182451 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
25192452
from line 2454
25212454
25222455 Union type for document source variants.
25232456
2524 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
2457 - `BetaManagedAgentsBase64DocumentSource object`
25252458
25262459 Base64-encoded document data.
25272460
from line 2462
25292462
25302463 Base64-encoded document data.
25312464
2465 minLength: 1
2466
25322467 - `media_type: string`
25332468
25342469 MIME type of the document (e.g., "application/pdf").
25352470
2471 minLength: 1
2472
25362473 - `type: "base64"`
25372474
2538 - `"base64"`
2539
2540 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
2475 - `BetaManagedAgentsPlainTextDocumentSource object`
25412476
25422477 Plain text document content.
25432478
from line 2480
25452480
25462481 The plain text content.
25472482
2483 minLength: 1
2484
25482485 - `media_type: "text/plain"`
25492486
25502487 MIME type of the text content. Must be "text/plain".
25512488
2552 - `"text/plain"`
2553
25542489 - `type: "text"`
25552490
2556 - `"text"`
2557
2558 - `BetaManagedAgentsURLDocumentSource object { type, url }`
2491 - `BetaManagedAgentsURLDocumentSource object`
25592492
25602493 Document referenced by URL.
25612494
25622495 - `type: "url"`
25632496
2564 - `"url"`
2565
25662497 - `url: string`
25672498
25682499 URL of the document to fetch.
25692500
2570 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
2501 minLength: 1
2502
2503 - `BetaManagedAgentsFileDocumentSource object`
25712504
25722505 Document referenced by file ID.
25732506
from line 2508
25752508
25762509 ID of a previously uploaded file.
25772510
2511 minLength: 1
2512
25782513 - `type: "file"`
25792514
2580 - `"file"`
2581
25822515 - `type: "document"`
25832516
2584 - `"document"`
2585
25862517 - `context: optional string or null`
25872518
25882519 Additional context about the document for the model.
from line 2522
25912522
25922523 The title of the document.
25932524
2594 - `BetaManagedAgentsRedactedBlock object { type }`
2525 - `BetaManagedAgentsRedactedBlock object`
25952526
25962527 Placeholder for content withheld by Anthropic model policy.
25972528
25982529 - `type: "redacted"`
25992530
2600 - `"redacted"`
2601
26022531 - `type: "user.message"`
26032532
2604 - `"user.message"`
2605
26062533 - `processed_at: optional string or null`
26072534
26082535 A timestamp in RFC 3339 format
26092536
2610 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
2537 format: date-time
2538
2539 - `BetaManagedAgentsUserInterruptEvent object`
26112540
26122541 An interrupt event that pauses agent execution and returns control to the user.
26132542
from line 2546
26172546
26182547 - `type: "user.interrupt"`
26192548
2620 - `"user.interrupt"`
2621
26222549 - `processed_at: optional string or null`
26232550
26242551 A timestamp in RFC 3339 format
26252552
2553 format: date-time
2554
26262555 - `session_thread_id: optional string or null`
26272556
26282557 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
26292558
2630 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
2559 - `BetaManagedAgentsUserToolConfirmationEvent object`
26312560
26322561 A tool confirmation event that approves or denies a pending tool execution.
26332562
from line 2578
26492578
26502579 - `type: "user.tool_confirmation"`
26512580
2652 - `"user.tool_confirmation"`
2653
26542581 - `deny_message: optional string or null`
26552582
26562583 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
26572584
2585 maxLength: 10000
2586
26582587 - `processed_at: optional string or null`
26592588
26602589 A timestamp in RFC 3339 format
26612590
2591 format: date-time
2592
26622593 - `session_thread_id: optional string or null`
26632594
26642595 When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.
26652596
2666 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
2597 - `BetaManagedAgentsUserCustomToolResultEvent object`
26672598
26682599 Event sent by the client providing the result of a custom tool execution.
26692600
from line 2608
26772608
26782609 - `type: "user.custom_tool_result"`
26792610
2680 - `"user.custom_tool_result"`
2681
26822611 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
26832612
26842613 The result content returned by the tool.
26852614
2686 - `BetaManagedAgentsTextBlock object { text, type }`
2615 - `BetaManagedAgentsTextBlock object`
26872616
26882617 Regular text content.
26892618
2690 - `BetaManagedAgentsImageBlock object { source, type }`
2619 - `BetaManagedAgentsImageBlock object`
26912620
26922621 Image content specified directly as base64 data or as a reference via a URL.
26932622
2694 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2623 - `BetaManagedAgentsDocumentBlock object`
26952624
26962625 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
26972626
2698 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
2627 - `BetaManagedAgentsSearchResultBlock object`
26992628
27002629 A block containing a web search result.
27012630
from line 2644
27152644
27162645 The text content.
27172646
2647 minLength: 1
2648
27182649 - `type: "text"`
27192650
2720 - `"text"`
2721
27222651 - `source: string`
27232652
27242653 The URL source of the search result.
27252654
2655 minLength: 1
2656
27262657 - `title: string`
27272658
27282659 The title of the search result.
27292660
2661 minLength: 1
2662
27302663 - `type: "search_result"`
27312664
2732 - `"search_result"`
2733
27342665 - `is_error: optional boolean or null`
27352666
27362667 Whether the tool execution resulted in an error.
from line 2670
27392670
27402671 A timestamp in RFC 3339 format
27412672
2673 format: date-time
2674
27422675 - `session_thread_id: optional string or null`
27432676
27442677 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
27452678
2746 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
2679 - `BetaManagedAgentsAgentCustomToolUseEvent object`
27472680
27482681 Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.
27492682
from line 2696
27632696
27642697 A timestamp in RFC 3339 format
27652698
2699 format: date-time
2700
27662701 - `type: "agent.custom_tool_use"`
27672702
2768 - `"agent.custom_tool_use"`
2769
27702703 - `session_thread_id: optional string or null`
27712704
27722705 When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.
27732706
2774 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
2707 - `BetaManagedAgentsAgentMessageEvent object`
27752708
27762709 An agent response event in the session conversation.
27772710
from line 2716
27832716
27842717 Array of text blocks comprising the agent response.
27852718
2786 - `BetaManagedAgentsTextBlock object { text, type }`
2719 - `BetaManagedAgentsTextBlock object`
27872720
27882721 Regular text content.
27892722
2790 - `BetaManagedAgentsRedactedBlock object { type }`
2723 - `BetaManagedAgentsRedactedBlock object`
27912724
27922725 Placeholder for content withheld by Anthropic model policy.
27932726
from line 2728
27952728
27962729 A timestamp in RFC 3339 format
27972730
2731 format: date-time
2732
27982733 - `type: "agent.message"`
27992734
2800 - `"agent.message"`
2801
2802 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
2735 - `BetaManagedAgentsAgentThinkingEvent object`
28032736
28042737 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
28052738
from line 2744
28112744
28122745 A timestamp in RFC 3339 format
28132746
2747 format: date-time
2748
28142749 - `type: "agent.thinking"`
28152750
2816 - `"agent.thinking"`
2817
2818 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
2751 - `BetaManagedAgentsAgentMCPToolUseEvent object`
28192752
28202753 Event emitted when the agent invokes a tool provided by an MCP server.
28212754
from line 2772
28392772
28402773 A timestamp in RFC 3339 format
28412774
2775 format: date-time
2776
28422777 - `type: "agent.mcp_tool_use"`
28432778
2844 - `"agent.mcp_tool_use"`
2845
28462779 - `evaluated_permission: optional "allow" or "ask" or "deny"`
28472780
28482781 AgentEvaluatedPermission enum
from line 2790
28572790
28582791 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
28592792
2860 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
2793 - `BetaManagedAgentsAgentMCPToolResultEvent object`
28612794
28622795 Event representing the result of an MCP tool execution.
28632796
from line 2806
28732806
28742807 A timestamp in RFC 3339 format
28752808
2809 format: date-time
2810
28762811 - `type: "agent.mcp_tool_result"`
28772812
2878 - `"agent.mcp_tool_result"`
2879
28802813 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
28812814
28822815 The result content returned by the tool.
28832816
2884 - `BetaManagedAgentsTextBlock object { text, type }`
2817 - `BetaManagedAgentsTextBlock object`
28852818
28862819 Regular text content.
28872820
2888 - `BetaManagedAgentsImageBlock object { source, type }`
2821 - `BetaManagedAgentsImageBlock object`
28892822
28902823 Image content specified directly as base64 data or as a reference via a URL.
28912824
2892 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2825 - `BetaManagedAgentsDocumentBlock object`
28932826
28942827 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
28952828
2896 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
2829 - `BetaManagedAgentsSearchResultBlock object`
28972830
28982831 A block containing a web search result.
28992832
from line 2834
29012834
29022835 Whether the tool execution resulted in an error.
29032836
2904 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
2837 - `BetaManagedAgentsAgentToolUseEvent object`
29052838
29062839 Event emitted when the agent invokes a built-in agent tool.
29072840
from line 2854
29212854
29222855 A timestamp in RFC 3339 format
29232856
2857 format: date-time
2858
29242859 - `type: "agent.tool_use"`
29252860
2926 - `"agent.tool_use"`
2927
29282861 - `evaluated_permission: optional "allow" or "ask" or "deny"`
29292862
29302863 AgentEvaluatedPermission enum
from line 2872
29392872
29402873 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
29412874
2942 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
2875 - `BetaManagedAgentsAgentToolResultEvent object`
29432876
29442877 Event representing the result of an agent tool execution.
29452878
from line 2884
29512884
29522885 A timestamp in RFC 3339 format
29532886
2887 format: date-time
2888
29542889 - `tool_use_id: string`
29552890
29562891 The id of the `agent.tool_use` event this result corresponds to.
29572892
29582893 - `type: "agent.tool_result"`
29592894
2960 - `"agent.tool_result"`
2961
29622895 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
29632896
29642897 The result content returned by the tool.
29652898
2966 - `BetaManagedAgentsTextBlock object { text, type }`
2899 - `BetaManagedAgentsTextBlock object`
29672900
29682901 Regular text content.
29692902
2970 - `BetaManagedAgentsImageBlock object { source, type }`
2903 - `BetaManagedAgentsImageBlock object`
29712904
29722905 Image content specified directly as base64 data or as a reference via a URL.
29732906
2974 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2907 - `BetaManagedAgentsDocumentBlock object`
29752908
29762909 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
29772910
2978 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
2911 - `BetaManagedAgentsSearchResultBlock object`
29792912
29802913 A block containing a web search result.
29812914
from line 2916
29832916
29842917 Whether the tool execution resulted in an error.
29852918
2986 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
2919 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
29872920
29882921 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
29892922
from line 2928
29952928
29962929 Message content blocks.
29972930
2998 - `BetaManagedAgentsTextBlock object { text, type }`
2931 - `BetaManagedAgentsTextBlock object`
29992932
30002933 Regular text content.
30012934
3002 - `BetaManagedAgentsImageBlock object { source, type }`
2935 - `BetaManagedAgentsImageBlock object`
30032936
30042937 Image content specified directly as base64 data or as a reference via a URL.
30052938
3006 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2939 - `BetaManagedAgentsDocumentBlock object`
30072940
30082941 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
30092942
3010 - `BetaManagedAgentsRedactedBlock object { type }`
2943 - `BetaManagedAgentsRedactedBlock object`
30112944
30122945 Placeholder for content withheld by Anthropic model policy.
30132946
from line 2952
30192952
30202953 A timestamp in RFC 3339 format
30212954
2955 format: date-time
2956
30222957 - `type: "agent.thread_message_received"`
30232958
3024 - `"agent.thread_message_received"`
3025
30262959 - `from_agent_name: optional string or null`
30272960
30282961 Name of the callable agent this message came from. Absent when received from the primary agent.
30292962
3030 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
2963 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
30312964
30322965 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
30332966
from line 2972
30392972
30402973 Message content blocks.
30412974
3042 - `BetaManagedAgentsTextBlock object { text, type }`
2975 - `BetaManagedAgentsTextBlock object`
30432976
30442977 Regular text content.
30452978
3046 - `BetaManagedAgentsImageBlock object { source, type }`
2979 - `BetaManagedAgentsImageBlock object`
30472980
30482981 Image content specified directly as base64 data or as a reference via a URL.
30492982
3050 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2983 - `BetaManagedAgentsDocumentBlock object`
30512984
30522985 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
30532986
3054 - `BetaManagedAgentsRedactedBlock object { type }`
2987 - `BetaManagedAgentsRedactedBlock object`
30552988
30562989 Placeholder for content withheld by Anthropic model policy.
30572990
from line 2992
30592992
30602993 A timestamp in RFC 3339 format
30612994
2995 format: date-time
2996
30622997 - `to_session_thread_id: string`
30632998
30642999 Public `sthr_` ID of the thread the message was sent to.
30653000
30663001 - `type: "agent.thread_message_sent"`
30673002
3068 - `"agent.thread_message_sent"`
3069
30703003 - `to_agent_name: optional string or null`
30713004
30723005 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
30733006
3074 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
3007 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
30753008
30763009 Indicates that context compaction (summarization) occurred during the session.
30773010
from line 3016
30833016
30843017 A timestamp in RFC 3339 format
30853018
3019 format: date-time
3020
30863021 - `type: "agent.thread_context_compacted"`
30873022
3088 - `"agent.thread_context_compacted"`
3089
3090 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
3023 - `BetaManagedAgentsSessionErrorEvent object`
30913024
30923025 An error event indicating a problem occurred during session execution.
30933026
from line 3032
30993032
31003033 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
31013034
3102 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
3035 - `BetaManagedAgentsUnknownError object`
31033036
31043037 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
31053038
from line 3044
31113044
31123045 What the client should do next in response to this error.
31133046
3114 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3047 - `BetaManagedAgentsRetryStatusRetrying object`
31153048
31163049 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
31173050
31183051 - `type: "retrying"`
31193052
3120 - `"retrying"`
3121
3122 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3053 - `BetaManagedAgentsRetryStatusExhausted object`
31233054
31243055 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
31253056
31263057 - `type: "exhausted"`
31273058
3128 - `"exhausted"`
3129
3130 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3059 - `BetaManagedAgentsRetryStatusTerminal object`
31313060
31323061 The session encountered a terminal error and will transition to `terminated` state.
31333062
31343063 - `type: "terminal"`
31353064
3136 - `"terminal"`
3137
31383065 - `type: "unknown_error"`
31393066
3140 - `"unknown_error"`
3141
3142 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
3067 - `BetaManagedAgentsModelOverloadedError object`
31433068
31443069 The model is currently overloaded. Emitted after automatic retries are exhausted.
31453070
from line 3076
31513076
31523077 What the client should do next in response to this error.
31533078
3154 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3079 - `BetaManagedAgentsRetryStatusRetrying object`
31553080
31563081 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
31573082
3158 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3083 - `BetaManagedAgentsRetryStatusExhausted object`
31593084
31603085 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
31613086
3162 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3087 - `BetaManagedAgentsRetryStatusTerminal object`
31633088
31643089 The session encountered a terminal error and will transition to `terminated` state.
31653090
31663091 - `type: "model_overloaded_error"`
31673092
3168 - `"model_overloaded_error"`
3169
3170 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
3093 - `BetaManagedAgentsModelRateLimitedError object`
31713094
31723095 The model request was rate-limited.
31733096
from line 3102
31793102
31803103 What the client should do next in response to this error.
31813104
3182 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3105 - `BetaManagedAgentsRetryStatusRetrying object`
31833106
31843107 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
31853108
3186 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3109 - `BetaManagedAgentsRetryStatusExhausted object`
31873110
31883111 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
31893112
3190 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3113 - `BetaManagedAgentsRetryStatusTerminal object`
31913114
31923115 The session encountered a terminal error and will transition to `terminated` state.
31933116
31943117 - `type: "model_rate_limited_error"`
31953118
3196 - `"model_rate_limited_error"`
3197
3198 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
3119 - `BetaManagedAgentsModelRequestFailedError object`
31993120
32003121 A model request failed for a reason other than overload or rate-limiting.
32013122
from line 3128
32073128
32083129 What the client should do next in response to this error.
32093130
3210 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3131 - `BetaManagedAgentsRetryStatusRetrying object`
32113132
32123133 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
32133134
3214 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3135 - `BetaManagedAgentsRetryStatusExhausted object`
32153136
32163137 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
32173138
3218 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3139 - `BetaManagedAgentsRetryStatusTerminal object`
32193140
32203141 The session encountered a terminal error and will transition to `terminated` state.
32213142
32223143 - `type: "model_request_failed_error"`
32233144
3224 - `"model_request_failed_error"`
3225
3226 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
3145 - `BetaManagedAgentsMCPConnectionFailedError object`
32273146
32283147 Failed to connect to an MCP server.
32293148
from line 3158
32393158
32403159 What the client should do next in response to this error.
32413160
3242 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3161 - `BetaManagedAgentsRetryStatusRetrying object`
32433162
32443163 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
32453164
3246 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3165 - `BetaManagedAgentsRetryStatusExhausted object`
32473166
32483167 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
32493168
3250 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3169 - `BetaManagedAgentsRetryStatusTerminal object`
32513170
32523171 The session encountered a terminal error and will transition to `terminated` state.
32533172
32543173 - `type: "mcp_connection_failed_error"`
32553174
3256 - `"mcp_connection_failed_error"`
3257
3258 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
3175 - `BetaManagedAgentsMCPAuthenticationFailedError object`
32593176
32603177 Authentication to an MCP server failed.
32613178
from line 3188
32713188
32723189 What the client should do next in response to this error.
32733190
3274 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3191 - `BetaManagedAgentsRetryStatusRetrying object`
32753192
32763193 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
32773194
3278 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3195 - `BetaManagedAgentsRetryStatusExhausted object`
32793196
32803197 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
32813198
3282 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3199 - `BetaManagedAgentsRetryStatusTerminal object`
32833200
32843201 The session encountered a terminal error and will transition to `terminated` state.
32853202
32863203 - `type: "mcp_authentication_failed_error"`
32873204
3288 - `"mcp_authentication_failed_error"`
3289
3290 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
3205 - `BetaManagedAgentsBillingError object`
32913206
32923207 The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
32933208
from line 3214
32993214
33003215 What the client should do next in response to this error.
33013216
3302 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3217 - `BetaManagedAgentsRetryStatusRetrying object`
33033218
33043219 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
33053220
3306 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3221 - `BetaManagedAgentsRetryStatusExhausted object`
33073222
33083223 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
33093224
3310 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3225 - `BetaManagedAgentsRetryStatusTerminal object`
33113226
33123227 The session encountered a terminal error and will transition to `terminated` state.
33133228
33143229 - `type: "billing_error"`
33153230
3316 - `"billing_error"`
3317
3318 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
3231 - `BetaManagedAgentsCredentialHostUnreachableError object`
33193232
33203233 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
33213234
from line 3244
33313244
33323245 What the client should do next in response to this error.
33333246
3334 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3247 - `BetaManagedAgentsRetryStatusRetrying object`
33353248
33363249 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
33373250
3338 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3251 - `BetaManagedAgentsRetryStatusExhausted object`
33393252
33403253 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
33413254
3342 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3255 - `BetaManagedAgentsRetryStatusTerminal object`
33433256
33443257 The session encountered a terminal error and will transition to `terminated` state.
33453258
33463259 - `type: "credential_host_unreachable_error"`
33473260
3348 - `"credential_host_unreachable_error"`
3349
33503261 - `vault_id: string`
33513262
33523263 ID of the vault containing the affected credential.
from line 3266
33553266
33563267 A timestamp in RFC 3339 format
33573268
3269 format: date-time
3270
33583271 - `type: "session.error"`
33593272
3360 - `"session.error"`
3361
3362 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
3273 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
33633274
33643275 Indicates the session is recovering from an error state and is rescheduled for execution.
33653276
from line 3282
33713282
33723283 A timestamp in RFC 3339 format
33733284
3285 format: date-time
3286
33743287 - `type: "session.status_rescheduled"`
33753288
3376 - `"session.status_rescheduled"`
3377
3378 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
3289 - `BetaManagedAgentsSessionStatusRunningEvent object`
33793290
33803291 Indicates the session is actively running and the agent is working.
33813292
from line 3298
33873298
33883299 A timestamp in RFC 3339 format
33893300
3301 format: date-time
3302
33903303 - `type: "session.status_running"`
33913304
3392 - `"session.status_running"`
3393
3394 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
3305 - `BetaManagedAgentsSessionStatusIdleEvent object`
33953306
33963307 Indicates the agent has paused and is awaiting user input.
33973308
from line 3314
34033314
34043315 A timestamp in RFC 3339 format
34053316
3317 format: date-time
3318
34063319 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
34073320
34083321 The agent completed its turn naturally and is ready for the next user message.
34093322
3410 - `BetaManagedAgentsSessionEndTurn object { type }`
3323 - `BetaManagedAgentsSessionEndTurn object`
34113324
34123325 The agent completed its turn naturally and is ready for the next user message.
34133326
34143327 - `type: "end_turn"`
34153328
3416 - `"end_turn"`
3417
3418 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
3329 - `BetaManagedAgentsSessionRequiresAction object`
34193330
34203331 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
34213332
from line 3336
34253336
34263337 - `type: "requires_action"`
34273338
3428 - `"requires_action"`
3429
3430 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
3339 - `BetaManagedAgentsSessionRetriesExhausted object`
34313340
34323341 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
34333342
34343343 - `type: "retries_exhausted"`
34353344
3436 - `"retries_exhausted"`
3437
3438 - `BetaManagedAgentsSessionBudgetReached object { type }`
3345 - `BetaManagedAgentsSessionBudgetReached object`
34393346
34403347 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
34413348
34423349 - `type: "budget_reached"`
34433350
3444 - `"budget_reached"`
3445
34463351 - `type: "session.status_idle"`
34473352
3448 - `"session.status_idle"`
3449
3450 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
3353 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
34513354
34523355 Indicates the session has terminated, either due to an error or completion.
34533356
from line 3362
34593362
34603363 A timestamp in RFC 3339 format
34613364
3365 format: date-time
3366
34623367 - `type: "session.status_terminated"`
34633368
3464 - `"session.status_terminated"`
3465
3466 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
3369 - `BetaManagedAgentsSessionThreadCreatedEvent object`
34673370
34683371 Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
34693372
from line 3382
34793382
34803383 A timestamp in RFC 3339 format
34813384
3385 format: date-time
3386
34823387 - `session_thread_id: string`
34833388
34843389 Public `sthr_` ID of the newly created thread.
34853390
34863391 - `type: "session.thread_created"`
34873392
3488 - `"session.thread_created"`
3489
3490 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
3393 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
34913394
34923395 Emitted when an outcome evaluation cycle begins.
34933396
from line 3402
34993402
35003403 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
35013404
3405 format: int32
3406
35023407 - `outcome_id: string`
35033408
35043409 The `outc_` ID of the outcome being evaluated.
from line 3412
35073412
35083413 A timestamp in RFC 3339 format
35093414
3415 format: date-time
3416
35103417 - `type: "span.outcome_evaluation_start"`
35113418
3512 - `"span.outcome_evaluation_start"`
3513
3514 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
3419 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
35153420
35163421 Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.
35173422
from line 3432
35273432
35283433 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
35293434
3435 format: int32
3436
35303437 - `outcome_evaluation_start_id: string`
35313438
35323439 The id of the corresponding `span.outcome_evaluation_start` event.
from line 3446
35393446
35403447 A timestamp in RFC 3339 format
35413448
3449 format: date-time
3450
35423451 - `result: string`
35433452
35443453 Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
35453454
35463455 - `type: "span.outcome_evaluation_end"`
35473456
3548 - `"span.outcome_evaluation_end"`
3549
35503457 - `usage: BetaManagedAgentsSpanModelUsage`
35513458
35523459 Token usage for a single model request.
from line 3462
35553462
35563463 Tokens used to create prompt cache in this request.
35573464
3465 format: int32
3466
35583467 - `cache_read_input_tokens: number`
35593468
35603469 Tokens read from prompt cache in this request.
35613470
3471 format: int32
3472
35623473 - `input_tokens: number`
35633474
35643475 Input tokens consumed by this request.
35653476
3477 format: int32
3478
35663479 - `output_tokens: number`
35673480
35683481 Output tokens generated by this request.
35693482
3483 format: int32
3484
35703485 - `speed: optional "standard" or "fast" or null`
35713486
35723487 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 3490
35753490
35763491 - `"fast"`
35773492
3578 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
3493 - `BetaManagedAgentsSpanModelRequestStartEvent object`
35793494
35803495 Emitted when a model request is initiated by the agent.
35813496
from line 3502
35873502
35883503 A timestamp in RFC 3339 format
35893504
3505 format: date-time
3506
35903507 - `type: "span.model_request_start"`
35913508
3592 - `"span.model_request_start"`
3593
3594 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
3509 - `BetaManagedAgentsSpanModelRequestEndEvent object`
35953510
35963511 Emitted when a model request completes.
35973512
from line 3530
36153530
36163531 A timestamp in RFC 3339 format
36173532
3533 format: date-time
3534
36183535 - `type: "span.model_request_end"`
36193536
3620 - `"span.model_request_end"`
3621
3622 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
3537 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
36233538
36243539 Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.
36253540
from line 3546
36313546
36323547 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
36333548
3549 format: int32
3550
36343551 - `outcome_id: string`
36353552
36363553 The `outc_` ID of the outcome being evaluated.
from line 3556
36393556
36403557 A timestamp in RFC 3339 format
36413558
3559 format: date-time
3560
36423561 - `type: "span.outcome_evaluation_ongoing"`
36433562
3644 - `"span.outcome_evaluation_ongoing"`
3645
3646 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
3563 - `BetaManagedAgentsUserDefineOutcomeEvent object`
36473564
36483565 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
36493566
from line 3576
36593576
36603577 Evaluate-then-revise cycles before giving up. Default 3, max 20.
36613578
3579 format: int32
3580
36623581 - `outcome_id: string`
36633582
36643583 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 3586
36673586
36683587 A timestamp in RFC 3339 format
36693588
3589 format: date-time
3590
36703591 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
36713592
36723593 Rubric for grading the quality of an outcome.
36733594
3674 - `BetaManagedAgentsFileRubric object { file_id, type }`
3595 - `BetaManagedAgentsFileRubric object`
36753596
36763597 Rubric referenced by a file uploaded via the Files API.
36773598
from line 3602
36813602
36823603 - `type: "file"`
36833604
3684 - `"file"`
3685
3686 - `BetaManagedAgentsTextRubric object { content, type }`
3605 - `BetaManagedAgentsTextRubric object`
36873606
36883607 Rubric content provided inline as text.
36893608
from line 3612
36933612
36943613 - `type: "text"`
36953614
3696 - `"text"`
3697
36983615 - `type: "user.define_outcome"`
36993616
3700 - `"user.define_outcome"`
3701
3702 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
3617 - `BetaManagedAgentsSessionDeletedEvent object`
37033618
37043619 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
37053620
from line 3626
37113626
37123627 A timestamp in RFC 3339 format
37133628
3629 format: date-time
3630
37143631 - `type: "session.deleted"`
37153632
3716 - `"session.deleted"`
3717
3718 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
3633 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
37193634
37203635 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
37213636
from line 3646
37313646
37323647 A timestamp in RFC 3339 format
37333648
3649 format: date-time
3650
37343651 - `session_thread_id: string`
37353652
37363653 Public sthr_ ID of the thread that started running.
37373654
37383655 - `type: "session.thread_status_running"`
37393656
3740 - `"session.thread_status_running"`
3741
3742 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
3657 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
37433658
37443659 A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
37453660
from line 3670
37553670
37563671 A timestamp in RFC 3339 format
37573672
3673 format: date-time
3674
37583675 - `session_thread_id: string`
37593676
37603677 Public sthr_ ID of the thread that went idle.
from line 3680
37633680
37643681 The agent completed its turn naturally and is ready for the next user message.
37653682
3766 - `BetaManagedAgentsSessionEndTurn object { type }`
3683 - `BetaManagedAgentsSessionEndTurn object`
37673684
37683685 The agent completed its turn naturally and is ready for the next user message.
37693686
3770 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
3687 - `BetaManagedAgentsSessionRequiresAction object`
37713688
37723689 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
37733690
3774 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
3691 - `BetaManagedAgentsSessionRetriesExhausted object`
37753692
37763693 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
37773694
3778 - `BetaManagedAgentsSessionBudgetReached object { type }`
3695 - `BetaManagedAgentsSessionBudgetReached object`
37793696
37803697 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
37813698
37823699 - `type: "session.thread_status_idle"`
37833700
3784 - `"session.thread_status_idle"`
3785
3786 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
3701 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
37873702
37883703 A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
37893704
from line 3714
37993714
38003715 A timestamp in RFC 3339 format
38013716
3717 format: date-time
3718
38023719 - `session_thread_id: string`
38033720
38043721 Public sthr_ ID of the thread that terminated.
38053722
38063723 - `type: "session.thread_status_terminated"`
38073724
3808 - `"session.thread_status_terminated"`
3809
3810 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
3725 - `BetaManagedAgentsUserToolResultEvent object`
38113726
38123727 Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.
38133728
from line 3736
38213736
38223737 - `type: "user.tool_result"`
38233738
3824 - `"user.tool_result"`
3825
38263739 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
38273740
38283741 The result content returned by the tool.
38293742
3830 - `BetaManagedAgentsTextBlock object { text, type }`
3743 - `BetaManagedAgentsTextBlock object`
38313744
38323745 Regular text content.
38333746
3834 - `BetaManagedAgentsImageBlock object { source, type }`
3747 - `BetaManagedAgentsImageBlock object`
38353748
38363749 Image content specified directly as base64 data or as a reference via a URL.
38373750
3838 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
3751 - `BetaManagedAgentsDocumentBlock object`
38393752
38403753 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
38413754
3842 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
3755 - `BetaManagedAgentsSearchResultBlock object`
38433756
38443757 A block containing a web search result.
38453758
from line 3764
38513764
38523765 A timestamp in RFC 3339 format
38533766
3767 format: date-time
3768
38543769 - `session_thread_id: optional string or null`
38553770
38563771 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
38573772
3858 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
3773 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
38593774
38603775 A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
38613776
from line 3786
38713786
38723787 A timestamp in RFC 3339 format
38733788
3789 format: date-time
3790
38743791 - `session_thread_id: string`
38753792
38763793 Public sthr_ ID of the thread that is retrying.
38773794
38783795 - `type: "session.thread_status_rescheduled"`
38793796
3880 - `"session.thread_status_rescheduled"`
3881
3882 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
3797 - `BetaManagedAgentsSessionUpdatedEvent object`
38833798
38843799 Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
38853800
from line 3806
38913806
38923807 A timestamp in RFC 3339 format
38933808
3809 format: date-time
3810
38943811 - `type: "session.updated"`
38953812
3896 - `"session.updated"`
3897
38983813 - `agent: optional BetaManagedAgentsSessionAgent or null`
38993814
39003815 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 3824
39093824
39103825 - `type: "url"`
39113826
3912 - `"url"`
3913
39143827 - `url: string`
39153828
39163829 - `model: BetaManagedAgentsModelConfig`
from line 3900
39873900
39883901 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
39893902
3990 - `BetaManagedAgentsEffortLow object { type }`
3903 - `BetaManagedAgentsEffortLow object`
39913904
39923905 Low effort. Favors latency over reasoning depth.
39933906
39943907 - `type: "low"`
39953908
3996 - `"low"`
3997
3998 - `BetaManagedAgentsEffortMedium object { type }`
3909 - `BetaManagedAgentsEffortMedium object`
39993910
40003911 Medium effort. Balances latency and reasoning depth.
40013912
40023913 - `type: "medium"`
40033914
4004 - `"medium"`
4005
4006 - `BetaManagedAgentsEffortHigh object { type }`
3915 - `BetaManagedAgentsEffortHigh object`
40073916
40083917 High effort. Favors reasoning depth.
40093918
40103919 - `type: "high"`
40113920
4012 - `"high"`
4013
4014 - `BetaManagedAgentsEffortXhigh object { type }`
3921 - `BetaManagedAgentsEffortXhigh object`
40153922
40163923 Extra-high effort. Not all models accept this level.
40173924
40183925 - `type: "xhigh"`
40193926
4020 - `"xhigh"`
4021
4022 - `BetaManagedAgentsEffortMax object { type }`
3927 - `BetaManagedAgentsEffortMax object`
40233928
40243929 Maximum effort. Favors reasoning depth over latency.
40253930
40263931 - `type: "max"`
40273932
4028 - `"max"`
4029
40303933 - `inference_geo: optional string`
40313934
40323935 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 3950
40473950
40483951 Full `agent` definitions the coordinator may spawn as session threads.
40493952
4050 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
3953 - `BetaManagedAgentsSessionThreadAgent object`
40513954
40523955 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`.
40533956
from line 3974
40713974
40723975 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
40733976
4074 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
3977 - `BetaManagedAgentsAnthropicSkill object`
40753978
40763979 A resolved Anthropic-managed skill.
40773980
from line 3982
40793982
40803983 - `type: "anthropic"`
40813984
4082 - `"anthropic"`
4083
40843985 - `version: string`
40853986
4086 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
3987 - `BetaManagedAgentsCustomSkill object`
40873988
40883989 A resolved user-created custom skill.
40893990
from line 3992
40913992
40923993 - `type: "custom"`
40933994
4094 - `"custom"`
4095
40963995 - `version: string`
40973996
40983997 - `system: string or null`
40993998
41003999 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
41014000
4102 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
4001 - `BetaManagedAgentsAgentToolset20260401 object`
41034002
41044003 - `configs: array of BetaManagedAgentsAgentToolConfig`
41054004
4106 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
4005 - `BetaManagedAgentsBashToolConfig object`
41074006
41084007 Configuration for the bash tool.
41094008
from line 4010
41114010
41124011 - `name: "bash"`
41134012
4114 - `"bash"`
4115
41164013 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41174014
41184015 Permission policy for tool execution.
41194016
4120 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4017 - `BetaManagedAgentsAlwaysAllowPolicy object`
41214018
41224019 Tool calls are automatically approved without user confirmation.
41234020
41244021 - `type: "always_allow"`
41254022
4126 - `"always_allow"`
4127
4128 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4023 - `BetaManagedAgentsAlwaysAskPolicy object`
41294024
41304025 Tool calls require user confirmation before execution.
41314026
41324027 - `type: "always_ask"`
41334028
4134 - `"always_ask"`
4135
41364029 - `type: "bash"`
41374030
4138 - `"bash"`
4139
4140 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
4031 - `BetaManagedAgentsEditToolConfig object`
41414032
41424033 Configuration for the edit tool.
41434034
from line 4036
41454036
41464037 - `name: "edit"`
41474038
4148 - `"edit"`
4149
41504039 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41514040
41524041 Permission policy for tool execution.
41534042
4154 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4043 - `BetaManagedAgentsAlwaysAllowPolicy object`
41554044
41564045 Tool calls are automatically approved without user confirmation.
41574046
4158 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4047 - `BetaManagedAgentsAlwaysAskPolicy object`
41594048
41604049 Tool calls require user confirmation before execution.
41614050
41624051 - `type: "edit"`
41634052
4164 - `"edit"`
4165
4166 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
4053 - `BetaManagedAgentsReadToolConfig object`
41674054
41684055 Configuration for the read tool.
41694056
from line 4058
41714058
41724059 - `name: "read"`
41734060
4174 - `"read"`
4175
41764061 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41774062
41784063 Permission policy for tool execution.
41794064
4180 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4065 - `BetaManagedAgentsAlwaysAllowPolicy object`
41814066
41824067 Tool calls are automatically approved without user confirmation.
41834068
4184 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4069 - `BetaManagedAgentsAlwaysAskPolicy object`
41854070
41864071 Tool calls require user confirmation before execution.
41874072
41884073 - `type: "read"`
41894074
4190 - `"read"`
4191
4192 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
4075 - `BetaManagedAgentsWriteToolConfig object`
41934076
41944077 Configuration for the write tool.
41954078
from line 4080
41974080
41984081 - `name: "write"`
41994082
4200 - `"write"`
4201
42024083 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
42034084
42044085 Permission policy for tool execution.
42054086
4206 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4087 - `BetaManagedAgentsAlwaysAllowPolicy object`
42074088
42084089 Tool calls are automatically approved without user confirmation.
42094090
4210 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4091 - `BetaManagedAgentsAlwaysAskPolicy object`
42114092
42124093 Tool calls require user confirmation before execution.
42134094
42144095 - `type: "write"`
42154096
4216 - `"write"`
4217
4218 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
4097 - `BetaManagedAgentsGlobToolConfig object`
42194098
42204099 Configuration for the glob tool.
42214100
from line 4102
42234102
42244103 - `name: "glob"`
42254104
4226 - `"glob"`
4227
42284105 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
42294106
42304107 Permission policy for tool execution.
42314108
4232 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4109 - `BetaManagedAgentsAlwaysAllowPolicy object`
42334110
42344111 Tool calls are automatically approved without user confirmation.
42354112
4236 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4113 - `BetaManagedAgentsAlwaysAskPolicy object`
42374114
42384115 Tool calls require user confirmation before execution.
42394116
42404117 - `type: "glob"`
42414118
4242 - `"glob"`
4243
4244 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
4119 - `BetaManagedAgentsGrepToolConfig object`
42454120
42464121 Configuration for the grep tool.
42474122
from line 4124
42494124
42504125 - `name: "grep"`
42514126
4252 - `"grep"`
4253
42544127 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
42554128
42564129 Permission policy for tool execution.
42574130
4258 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4131 - `BetaManagedAgentsAlwaysAllowPolicy object`
42594132
42604133 Tool calls are automatically approved without user confirmation.
42614134
4262 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4135 - `BetaManagedAgentsAlwaysAskPolicy object`
42634136
42644137 Tool calls require user confirmation before execution.
42654138
42664139 - `type: "grep"`
42674140
4268 - `"grep"`
4269
4270 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
4141 - `BetaManagedAgentsWebFetchToolConfig object`
42714142
42724143 Configuration for the web_fetch tool.
42734144
from line 4146
42754146
42764147 - `name: "web_fetch"`
42774148
4278 - `"web_fetch"`
4279
42804149 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
42814150
42824151 Permission policy for tool execution.
42834152
4284 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4153 - `BetaManagedAgentsAlwaysAllowPolicy object`
42854154
42864155 Tool calls are automatically approved without user confirmation.
42874156
4288 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4157 - `BetaManagedAgentsAlwaysAskPolicy object`
42894158
42904159 Tool calls require user confirmation before execution.
42914160
42924161 - `type: "web_fetch"`
42934162
4294 - `"web_fetch"`
4295
42964163 - `allowed_domains: optional array of string`
42974164
42984165 - `blocked_domains: optional array of string`
42994166
43004167 - `max_content_tokens: optional number or null`
43014168
4302 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
4169 format: int32
4170
4171 - `BetaManagedAgentsWebSearchToolConfig object`
43034172
43044173 Configuration for the web_search tool.
43054174
from line 4176
43074176
43084177 - `name: "web_search"`
43094178
4310 - `"web_search"`
4311
43124179 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
43134180
43144181 Permission policy for tool execution.
43154182
4316 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4183 - `BetaManagedAgentsAlwaysAllowPolicy object`
43174184
43184185 Tool calls are automatically approved without user confirmation.
43194186
4320 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4187 - `BetaManagedAgentsAlwaysAskPolicy object`
43214188
43224189 Tool calls require user confirmation before execution.
43234190
43244191 - `type: "web_search"`
43254192
4326 - `"web_search"`
4327
43284193 - `allowed_domains: optional array of string`
43294194
43304195 - `blocked_domains: optional array of string`
from line 4202
43374202
43384203 Location precision. Only "approximate" is supported.
43394204
4340 - `"approximate"`
4341
43424205 - `city: optional string or null`
43434206
43444207 City name.
43454208
4209 minLength: 1, maxLength: 255
4210
43464211 - `country: optional string or null`
43474212
43484213 Two-letter ISO 3166-1 country code, uppercase.
from line 4216
43514216
43524217 Region or state name.
43534218
4219 minLength: 1, maxLength: 255
4220
43544221 - `timezone: optional string or null`
43554222
43564223 IANA timezone identifier, e.g. "America/Los_Angeles".
43574224
4225 minLength: 1, maxLength: 255
4226
43584227 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
43594228
43604229 Resolved default configuration for agent tools.
from line 4234
43654234
43664235 Permission policy for tool execution.
43674236
4368 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4237 - `BetaManagedAgentsAlwaysAllowPolicy object`
43694238
43704239 Tool calls are automatically approved without user confirmation.
43714240
4372 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4241 - `BetaManagedAgentsAlwaysAskPolicy object`
43734242
43744243 Tool calls require user confirmation before execution.
43754244
43764245 - `type: "agent_toolset_20260401"`
43774246
4378 - `"agent_toolset_20260401"`
4379
4380 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
4247 - `BetaManagedAgentsMCPToolset object`
43814248
43824249 - `configs: array of BetaManagedAgentsMCPToolConfig`
43834250
from line 4256
43894256
43904257 Permission policy for tool execution.
43914258
4392 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4259 - `BetaManagedAgentsAlwaysAllowPolicy object`
43934260
43944261 Tool calls are automatically approved without user confirmation.
43954262
4396 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4263 - `BetaManagedAgentsAlwaysAskPolicy object`
43974264
43984265 Tool calls require user confirmation before execution.
43994266
from line 4274
44074274
44084275 Permission policy for tool execution.
44094276
4410 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4277 - `BetaManagedAgentsAlwaysAllowPolicy object`
44114278
44124279 Tool calls are automatically approved without user confirmation.
44134280
4414 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4281 - `BetaManagedAgentsAlwaysAskPolicy object`
44154282
44164283 Tool calls require user confirmation before execution.
44174284
from line 4286
44194286
44204287 - `type: "mcp_toolset"`
44214288
4422 - `"mcp_toolset"`
4423
4424 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
4289 - `BetaManagedAgentsCustomTool object`
44254290
44264291 A custom tool as returned in API responses.
44274292
from line 4298
44334298
44344299 - `type: "object"`
44354300
4436 - `"object"`
4437
44384301 - `properties: optional map[unknown] or null`
44394302
44404303 - `required: optional array of string or null`
from line 4306
44434306
44444307 - `type: "custom"`
44454308
4446 - `"custom"`
4447
44484309 - `type: "agent"`
44494310
4450 - `"agent"`
4451
44524311 - `version: number`
44534312
4454 - `BetaManagedAgentsAdvisor object { model, type }`
4313 format: int32
4314
4315 - `BetaManagedAgentsAdvisor object`
44554316
44564317 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
44574318
from line 4322
44614322
44624323 - `type: "advisor"`
44634324
4464 - `"advisor"`
4465
44664325 - `type: "coordinator"`
44674326
4468 - `"coordinator"`
4469
44704327 - `name: string`
44714328
44724329 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
44734330
4474 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
4331 - `BetaManagedAgentsAnthropicSkill object`
44754332
44764333 A resolved Anthropic-managed skill.
44774334
4478 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
4335 - `BetaManagedAgentsCustomSkill object`
44794336
44804337 A resolved user-created custom skill.
44814338
from line 4340
44834340
44844341 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
44854342
4486 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
4487
4488 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
4489
4490 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
4343 - `BetaManagedAgentsAgentToolset20260401 object`
4344
4345 - `BetaManagedAgentsMCPToolset object`
4346
4347 - `BetaManagedAgentsCustomTool object`
44914348
44924349 A custom tool as returned in API responses.
44934350
44944351 - `type: "agent"`
44954352
4496 - `"agent"`
4497
44984353 - `version: number`
44994354
4355 format: int32
4356
45004357 - `budget: optional BetaManagedAgentsBudgetLimit or null`
45014358
45024359 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 4370
45134370
45144371 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.
45154372
4516 - `"USD"`
4517
45184373 - `type: "limit"`
45194374
4520 - `"limit"`
4521
45224375 - `metadata: optional map[string]`
45234376
45244377 The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
from line 4380
45274380
45284381 The session's new title. Present only when the update changed it.
45294382
4530 - `BetaManagedAgentsStartEvent object { event, type }`
4383 - `BetaManagedAgentsStartEvent object`
45314384
45324385 Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
45334386
from line 4388
45354388
45364389 The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.
45374390
4538 - `BetaManagedAgentsAgentMessagePreview object { id, type }`
4391 - `BetaManagedAgentsAgentMessagePreview object`
45394392
45404393 - `id: string`
45414394
from line 4396
45434396
45444397 - `type: "agent.message"`
45454398
4546 - `"agent.message"`
4547
4548 - `BetaManagedAgentsAgentThinkingPreview object { id, type }`
4399 - `BetaManagedAgentsAgentThinkingPreview object`
45494400
45504401 - `id: string`
45514402
from line 4404
45534404
45544405 - `type: "agent.thinking"`
45554406
4556 - `"agent.thinking"`
4557
45584407 - `type: "event_start"`
45594408
4560 - `"event_start"`
4561
4562 - `BetaManagedAgentsDeltaEvent object { delta, event_id, type }`
4409 - `BetaManagedAgentsDeltaEvent object`
45634410
45644411 An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
45654412
from line 4420
45734420
45744421 - `type: "content_delta"`
45754422
4576 - `"content_delta"`
4577
45784423 - `index: optional number`
45794424
45804425 Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.
45814426
4427 format: uint32
4428
45824429 - `event_id: string`
45834430
45844431 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
45854432
45864433 - `type: "event_delta"`
45874434
4588 - `"event_delta"`
4589
4590 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
4435 - `BetaManagedAgentsSystemMessageEvent object`
45914436
45924437 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
45934438
from line 4448
46034448
46044449 The text content.
46054450
4451 minLength: 1
4452
46064453 - `type: "text"`
46074454
4608 - `"text"`
4609
46104455 - `type: "system.message"`
46114456
4612 - `"system.message"`
4613
46144457 - `processed_at: optional string or null`
46154458
46164459 A timestamp in RFC 3339 format
46174460
4618 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
4461 format: date-time
4462
4463 - `BetaManagedAgentsSessionUsageEvent object`
46194464
46204465 Periodic snapshot of the session's cumulative usage and tracked list cost.
46214466
from line 4472
46274472
46284473 A timestamp in RFC 3339 format
46294474
4475 format: date-time
4476
46304477 - `type: "session.usage"`
46314478
4632 - `"session.usage"`
4633
46344479 - `usage: BetaManagedAgentsSessionUsageSnapshot`
46354480
46364481 Point-in-time snapshot of a session's cumulative usage.
from line 4484
46394484
46404485 Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
46414486
4487 format: double
4488
46424489 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
46434490
46444491 Prompt-cache creation token usage broken down by cache lifetime.
from line 4494
46474494
46484495 Tokens used to create 1-hour ephemeral cache entries.
46494496
4497 format: int32
4498
46504499 - `ephemeral_5m_input_tokens: optional number`
46514500
46524501 Tokens used to create 5-minute ephemeral cache entries.
46534502
4503 format: int32
4504
46544505 - `cache_read_input_tokens: optional number`
46554506
46564507 Total tokens read from prompt cache.
46574508
4509 format: int32
4510
46584511 - `input_tokens: optional number`
46594512
46604513 Total input tokens consumed across all turns.
46614514
4515 format: int32
4516
46624517 - `list_cost: optional BetaMonetaryAmount`
46634518
46644519 A monetary amount in a specific currency.
from line 4522
46674522
46684523 Total output tokens generated across all turns.
46694524
4525 format: int32
4526
46704527 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
46714528
46724529 Cumulative count of server-executed tool invocations, broken down by tool.
from line 4532
46754532
46764533 Number of server-executed web fetch requests.
46774534
4535 format: int32
4536
46784537 - `web_search_requests: optional number`
46794538
46804539 Number of server-executed web search requests.
46814540
4541 format: int32
4542
46824543 - `budget: optional BetaManagedAgentsBudgetLimit or null`
46834544
46844545 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
46854546
4547- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
4548
4549 Server-sent event in a single thread's stream.
4550
46864551### Example
46874552
4688```http
4553```bash
46894554curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream \
46904555 -H 'anthropic-version: 2023-06-01' \
46914556 -H 'anthropic-beta: managed-agents-2026-04-01' \
46924557 -H "X-Api-Key: $ANTHROPIC_API_KEY"
46934558```
46944559
4695#### Response
4560#### Response (200)
46964561
46974562```json
46984563{
46994564
api/beta/sessions/threads/events/list Changed · +320 / -387 lines
# List Session Thread Events ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Session Thread Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: List Session Thread Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/events/list
4---
5
6## List Session Thread Events
7
8**get** `/v1/sessions/{session_id}/threads/{thread_id}/events`
1# List Session Thread Events
2
3**GET** `/v1/sessions/{session_id}/threads/{thread_id}/events`
94
105List Session Thread Events
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
1611- `thread_id: string`
1712
18### Query Parameters
13## Query parameters
1914
2015- `limit: optional number`
2116
2217 Query parameter for limit
2318
19 format: int32
20
2421- `page: optional string`
2522
2623 Query parameter for page
2724
28### Header Parameters
25## Headers
2926
3027- `"anthropic-beta": optional array of AnthropicBeta`
3128
from line 100
103100
104101 - `"mid-conversation-tool-changes-2026-07-01"`
105102
106### Returns
103## Returns
107104
108105- `data: optional array of BetaManagedAgentsSessionEvent`
109106
110107 Events for the thread, ordered by `processed_at`.
111108
112 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
109 - `BetaManagedAgentsUserMessageEvent object`
113110
114111 A user message event in the session conversation.
115112
from line 118
121118
122119 Array of content blocks comprising the user message.
123120
124 - `BetaManagedAgentsTextBlock object { text, type }`
121 - `BetaManagedAgentsTextBlock object`
125122
126123 Regular text content.
127124
from line 126
129126
130127 The text content.
131128
129 minLength: 1
130
132131 - `type: "text"`
133132
134 - `"text"`
135
136 - `BetaManagedAgentsImageBlock object { source, type }`
133 - `BetaManagedAgentsImageBlock object`
137134
138135 Image content specified directly as base64 data or as a reference via a URL.
139136
from line 138
141138
142139 Union type for image source variants.
143140
144 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
141 - `BetaManagedAgentsBase64ImageSource object`
145142
146143 Base64-encoded image data.
147144
from line 146
149146
150147 Base64-encoded image data.
151148
149 minLength: 1
150
152151 - `media_type: string`
153152
154153 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
155154
155 minLength: 1
156
156157 - `type: "base64"`
157158
158 - `"base64"`
159
160 - `BetaManagedAgentsURLImageSource object { type, url }`
159 - `BetaManagedAgentsURLImageSource object`
161160
162161 Image referenced by URL.
163162
164163 - `type: "url"`
165164
166 - `"url"`
167
168165 - `url: string`
169166
170167 URL of the image to fetch.
171168
172 - `BetaManagedAgentsFileImageSource object { file_id, type }`
169 minLength: 1
170
171 - `BetaManagedAgentsFileImageSource object`
173172
174173 Image referenced by file ID.
175174
from line 176
177176
178177 ID of a previously uploaded file.
179178
179 minLength: 1
180
180181 - `type: "file"`
181182
182 - `"file"`
183
184183 - `type: "image"`
185184
186 - `"image"`
187
188 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
185 - `BetaManagedAgentsDocumentBlock object`
189186
190187 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
191188
from line 190
193190
194191 Union type for document source variants.
195192
196 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
193 - `BetaManagedAgentsBase64DocumentSource object`
197194
198195 Base64-encoded document data.
199196
from line 198
201198
202199 Base64-encoded document data.
203200
201 minLength: 1
202
204203 - `media_type: string`
205204
206205 MIME type of the document (e.g., "application/pdf").
207206
207 minLength: 1
208
208209 - `type: "base64"`
209210
210 - `"base64"`
211
212 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
211 - `BetaManagedAgentsPlainTextDocumentSource object`
213212
214213 Plain text document content.
215214
from line 216
217216
218217 The plain text content.
219218
219 minLength: 1
220
220221 - `media_type: "text/plain"`
221222
222223 MIME type of the text content. Must be "text/plain".
223224
224 - `"text/plain"`
225
226225 - `type: "text"`
227226
228 - `"text"`
229
230 - `BetaManagedAgentsURLDocumentSource object { type, url }`
227 - `BetaManagedAgentsURLDocumentSource object`
231228
232229 Document referenced by URL.
233230
234231 - `type: "url"`
235232
236 - `"url"`
237
238233 - `url: string`
239234
240235 URL of the document to fetch.
241236
242 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
237 minLength: 1
238
239 - `BetaManagedAgentsFileDocumentSource object`
243240
244241 Document referenced by file ID.
245242
from line 244
247244
248245 ID of a previously uploaded file.
249246
247 minLength: 1
248
250249 - `type: "file"`
251250
252 - `"file"`
253
254251 - `type: "document"`
255252
256 - `"document"`
257
258253 - `context: optional string or null`
259254
260255 Additional context about the document for the model.
from line 258
263258
264259 The title of the document.
265260
266 - `BetaManagedAgentsRedactedBlock object { type }`
261 - `BetaManagedAgentsRedactedBlock object`
267262
268263 Placeholder for content withheld by Anthropic model policy.
269264
270265 - `type: "redacted"`
271266
272 - `"redacted"`
273
274267 - `type: "user.message"`
275268
276 - `"user.message"`
277
278269 - `processed_at: optional string or null`
279270
280271 A timestamp in RFC 3339 format
281272
282 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
273 format: date-time
274
275 - `BetaManagedAgentsUserInterruptEvent object`
283276
284277 An interrupt event that pauses agent execution and returns control to the user.
285278
from line 282
289282
290283 - `type: "user.interrupt"`
291284
292 - `"user.interrupt"`
293
294285 - `processed_at: optional string or null`
295286
296287 A timestamp in RFC 3339 format
297288
289 format: date-time
290
298291 - `session_thread_id: optional string or null`
299292
300293 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
301294
302 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
295 - `BetaManagedAgentsUserToolConfirmationEvent object`
303296
304297 A tool confirmation event that approves or denies a pending tool execution.
305298
from line 314
321314
322315 - `type: "user.tool_confirmation"`
323316
324 - `"user.tool_confirmation"`
325
326317 - `deny_message: optional string or null`
327318
328319 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
329320
321 maxLength: 10000
322
330323 - `processed_at: optional string or null`
331324
332325 A timestamp in RFC 3339 format
333326
327 format: date-time
328
334329 - `session_thread_id: optional string or null`
335330
336331 When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.
337332
338 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
333 - `BetaManagedAgentsUserCustomToolResultEvent object`
339334
340335 Event sent by the client providing the result of a custom tool execution.
341336
from line 344
349344
350345 - `type: "user.custom_tool_result"`
351346
352 - `"user.custom_tool_result"`
353
354347 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
355348
356349 The result content returned by the tool.
357350
358 - `BetaManagedAgentsTextBlock object { text, type }`
351 - `BetaManagedAgentsTextBlock object`
359352
360353 Regular text content.
361354
362 - `BetaManagedAgentsImageBlock object { source, type }`
355 - `BetaManagedAgentsImageBlock object`
363356
364357 Image content specified directly as base64 data or as a reference via a URL.
365358
366 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
359 - `BetaManagedAgentsDocumentBlock object`
367360
368361 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
369362
370 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
363 - `BetaManagedAgentsSearchResultBlock object`
371364
372365 A block containing a web search result.
373366
from line 380
387380
388381 The text content.
389382
383 minLength: 1
384
390385 - `type: "text"`
391386
392 - `"text"`
393
394387 - `source: string`
395388
396389 The URL source of the search result.
397390
391 minLength: 1
392
398393 - `title: string`
399394
400395 The title of the search result.
401396
397 minLength: 1
398
402399 - `type: "search_result"`
403400
404 - `"search_result"`
405
406401 - `is_error: optional boolean or null`
407402
408403 Whether the tool execution resulted in an error.
from line 406
411406
412407 A timestamp in RFC 3339 format
413408
409 format: date-time
410
414411 - `session_thread_id: optional string or null`
415412
416413 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
417414
418 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
415 - `BetaManagedAgentsAgentCustomToolUseEvent object`
419416
420417 Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.
421418
from line 432
435432
436433 A timestamp in RFC 3339 format
437434
435 format: date-time
436
438437 - `type: "agent.custom_tool_use"`
439438
440 - `"agent.custom_tool_use"`
441
442439 - `session_thread_id: optional string or null`
443440
444441 When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.
445442
446 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
443 - `BetaManagedAgentsAgentMessageEvent object`
447444
448445 An agent response event in the session conversation.
449446
from line 452
455452
456453 Array of text blocks comprising the agent response.
457454
458 - `BetaManagedAgentsTextBlock object { text, type }`
455 - `BetaManagedAgentsTextBlock object`
459456
460457 Regular text content.
461458
462 - `BetaManagedAgentsRedactedBlock object { type }`
459 - `BetaManagedAgentsRedactedBlock object`
463460
464461 Placeholder for content withheld by Anthropic model policy.
465462
from line 464
467464
468465 A timestamp in RFC 3339 format
469466
467 format: date-time
468
470469 - `type: "agent.message"`
471470
472 - `"agent.message"`
473
474 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
471 - `BetaManagedAgentsAgentThinkingEvent object`
475472
476473 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
477474
from line 480
483480
484481 A timestamp in RFC 3339 format
485482
483 format: date-time
484
486485 - `type: "agent.thinking"`
487486
488 - `"agent.thinking"`
489
490 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
487 - `BetaManagedAgentsAgentMCPToolUseEvent object`
491488
492489 Event emitted when the agent invokes a tool provided by an MCP server.
493490
from line 508
511508
512509 A timestamp in RFC 3339 format
513510
511 format: date-time
512
514513 - `type: "agent.mcp_tool_use"`
515514
516 - `"agent.mcp_tool_use"`
517
518515 - `evaluated_permission: optional "allow" or "ask" or "deny"`
519516
520517 AgentEvaluatedPermission enum
from line 526
529526
530527 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
531528
532 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
529 - `BetaManagedAgentsAgentMCPToolResultEvent object`
533530
534531 Event representing the result of an MCP tool execution.
535532
from line 542
545542
546543 A timestamp in RFC 3339 format
547544
545 format: date-time
546
548547 - `type: "agent.mcp_tool_result"`
549548
550 - `"agent.mcp_tool_result"`
551
552549 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
553550
554551 The result content returned by the tool.
555552
556 - `BetaManagedAgentsTextBlock object { text, type }`
553 - `BetaManagedAgentsTextBlock object`
557554
558555 Regular text content.
559556
560 - `BetaManagedAgentsImageBlock object { source, type }`
557 - `BetaManagedAgentsImageBlock object`
561558
562559 Image content specified directly as base64 data or as a reference via a URL.
563560
564 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
561 - `BetaManagedAgentsDocumentBlock object`
565562
566563 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
567564
568 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
565 - `BetaManagedAgentsSearchResultBlock object`
569566
570567 A block containing a web search result.
571568
from line 570
573570
574571 Whether the tool execution resulted in an error.
575572
576 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
573 - `BetaManagedAgentsAgentToolUseEvent object`
577574
578575 Event emitted when the agent invokes a built-in agent tool.
579576
from line 590
593590
594591 A timestamp in RFC 3339 format
595592
593 format: date-time
594
596595 - `type: "agent.tool_use"`
597596
598 - `"agent.tool_use"`
599
600597 - `evaluated_permission: optional "allow" or "ask" or "deny"`
601598
602599 AgentEvaluatedPermission enum
from line 608
611608
612609 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
613610
614 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
611 - `BetaManagedAgentsAgentToolResultEvent object`
615612
616613 Event representing the result of an agent tool execution.
617614
from line 620
623620
624621 A timestamp in RFC 3339 format
625622
623 format: date-time
624
626625 - `tool_use_id: string`
627626
628627 The id of the `agent.tool_use` event this result corresponds to.
629628
630629 - `type: "agent.tool_result"`
631630
632 - `"agent.tool_result"`
633
634631 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
635632
636633 The result content returned by the tool.
637634
638 - `BetaManagedAgentsTextBlock object { text, type }`
635 - `BetaManagedAgentsTextBlock object`
639636
640637 Regular text content.
641638
642 - `BetaManagedAgentsImageBlock object { source, type }`
639 - `BetaManagedAgentsImageBlock object`
643640
644641 Image content specified directly as base64 data or as a reference via a URL.
645642
646 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
643 - `BetaManagedAgentsDocumentBlock object`
647644
648645 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
649646
650 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
647 - `BetaManagedAgentsSearchResultBlock object`
651648
652649 A block containing a web search result.
653650
from line 652
655652
656653 Whether the tool execution resulted in an error.
657654
658 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
655 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
659656
660657 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
661658
from line 664
667664
668665 Message content blocks.
669666
670 - `BetaManagedAgentsTextBlock object { text, type }`
667 - `BetaManagedAgentsTextBlock object`
671668
672669 Regular text content.
673670
674 - `BetaManagedAgentsImageBlock object { source, type }`
671 - `BetaManagedAgentsImageBlock object`
675672
676673 Image content specified directly as base64 data or as a reference via a URL.
677674
678 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
675 - `BetaManagedAgentsDocumentBlock object`
679676
680677 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
681678
682 - `BetaManagedAgentsRedactedBlock object { type }`
679 - `BetaManagedAgentsRedactedBlock object`
683680
684681 Placeholder for content withheld by Anthropic model policy.
685682
from line 688
691688
692689 A timestamp in RFC 3339 format
693690
691 format: date-time
692
694693 - `type: "agent.thread_message_received"`
695694
696 - `"agent.thread_message_received"`
697
698695 - `from_agent_name: optional string or null`
699696
700697 Name of the callable agent this message came from. Absent when received from the primary agent.
701698
702 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
699 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
703700
704701 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
705702
from line 708
711708
712709 Message content blocks.
713710
714 - `BetaManagedAgentsTextBlock object { text, type }`
711 - `BetaManagedAgentsTextBlock object`
715712
716713 Regular text content.
717714
718 - `BetaManagedAgentsImageBlock object { source, type }`
715 - `BetaManagedAgentsImageBlock object`
719716
720717 Image content specified directly as base64 data or as a reference via a URL.
721718
722 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
719 - `BetaManagedAgentsDocumentBlock object`
723720
724721 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
725722
726 - `BetaManagedAgentsRedactedBlock object { type }`
723 - `BetaManagedAgentsRedactedBlock object`
727724
728725 Placeholder for content withheld by Anthropic model policy.
729726
from line 728
731728
732729 A timestamp in RFC 3339 format
733730
731 format: date-time
732
734733 - `to_session_thread_id: string`
735734
736735 Public `sthr_` ID of the thread the message was sent to.
737736
738737 - `type: "agent.thread_message_sent"`
739738
740 - `"agent.thread_message_sent"`
741
742739 - `to_agent_name: optional string or null`
743740
744741 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
745742
746 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
743 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
747744
748745 Indicates that context compaction (summarization) occurred during the session.
749746
from line 752
755752
756753 A timestamp in RFC 3339 format
757754
755 format: date-time
756
758757 - `type: "agent.thread_context_compacted"`
759758
760 - `"agent.thread_context_compacted"`
761
762 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
759 - `BetaManagedAgentsSessionErrorEvent object`
763760
764761 An error event indicating a problem occurred during session execution.
765762
from line 768
771768
772769 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
773770
774 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
771 - `BetaManagedAgentsUnknownError object`
775772
776773 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
777774
from line 780
783780
784781 What the client should do next in response to this error.
785782
786 - `BetaManagedAgentsRetryStatusRetrying object { type }`
783 - `BetaManagedAgentsRetryStatusRetrying object`
787784
788785 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
789786
790787 - `type: "retrying"`
791788
792 - `"retrying"`
793
794 - `BetaManagedAgentsRetryStatusExhausted object { type }`
789 - `BetaManagedAgentsRetryStatusExhausted object`
795790
796791 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
797792
798793 - `type: "exhausted"`
799794
800 - `"exhausted"`
801
802 - `BetaManagedAgentsRetryStatusTerminal object { type }`
795 - `BetaManagedAgentsRetryStatusTerminal object`
803796
804797 The session encountered a terminal error and will transition to `terminated` state.
805798
806799 - `type: "terminal"`
807800
808 - `"terminal"`
809
810801 - `type: "unknown_error"`
811802
812 - `"unknown_error"`
813
814 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
803 - `BetaManagedAgentsModelOverloadedError object`
815804
816805 The model is currently overloaded. Emitted after automatic retries are exhausted.
817806
from line 812
823812
824813 What the client should do next in response to this error.
825814
826 - `BetaManagedAgentsRetryStatusRetrying object { type }`
815 - `BetaManagedAgentsRetryStatusRetrying object`
827816
828817 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
829818
830 - `BetaManagedAgentsRetryStatusExhausted object { type }`
819 - `BetaManagedAgentsRetryStatusExhausted object`
831820
832821 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
833822
834 - `BetaManagedAgentsRetryStatusTerminal object { type }`
823 - `BetaManagedAgentsRetryStatusTerminal object`
835824
836825 The session encountered a terminal error and will transition to `terminated` state.
837826
838827 - `type: "model_overloaded_error"`
839828
840 - `"model_overloaded_error"`
841
842 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
829 - `BetaManagedAgentsModelRateLimitedError object`
843830
844831 The model request was rate-limited.
845832
from line 838
851838
852839 What the client should do next in response to this error.
853840
854 - `BetaManagedAgentsRetryStatusRetrying object { type }`
841 - `BetaManagedAgentsRetryStatusRetrying object`
855842
856843 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
857844
858 - `BetaManagedAgentsRetryStatusExhausted object { type }`
845 - `BetaManagedAgentsRetryStatusExhausted object`
859846
860847 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
861848
862 - `BetaManagedAgentsRetryStatusTerminal object { type }`
849 - `BetaManagedAgentsRetryStatusTerminal object`
863850
864851 The session encountered a terminal error and will transition to `terminated` state.
865852
866853 - `type: "model_rate_limited_error"`
867854
868 - `"model_rate_limited_error"`
869
870 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
855 - `BetaManagedAgentsModelRequestFailedError object`
871856
872857 A model request failed for a reason other than overload or rate-limiting.
873858
from line 864
879864
880865 What the client should do next in response to this error.
881866
882 - `BetaManagedAgentsRetryStatusRetrying object { type }`
867 - `BetaManagedAgentsRetryStatusRetrying object`
883868
884869 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
885870
886 - `BetaManagedAgentsRetryStatusExhausted object { type }`
871 - `BetaManagedAgentsRetryStatusExhausted object`
887872
888873 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
889874
890 - `BetaManagedAgentsRetryStatusTerminal object { type }`
875 - `BetaManagedAgentsRetryStatusTerminal object`
891876
892877 The session encountered a terminal error and will transition to `terminated` state.
893878
894879 - `type: "model_request_failed_error"`
895880
896 - `"model_request_failed_error"`
897
898 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
881 - `BetaManagedAgentsMCPConnectionFailedError object`
899882
900883 Failed to connect to an MCP server.
901884
from line 894
911894
912895 What the client should do next in response to this error.
913896
914 - `BetaManagedAgentsRetryStatusRetrying object { type }`
897 - `BetaManagedAgentsRetryStatusRetrying object`
915898
916899 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
917900
918 - `BetaManagedAgentsRetryStatusExhausted object { type }`
901 - `BetaManagedAgentsRetryStatusExhausted object`
919902
920903 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
921904
922 - `BetaManagedAgentsRetryStatusTerminal object { type }`
905 - `BetaManagedAgentsRetryStatusTerminal object`
923906
924907 The session encountered a terminal error and will transition to `terminated` state.
925908
926909 - `type: "mcp_connection_failed_error"`
927910
928 - `"mcp_connection_failed_error"`
929
930 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
911 - `BetaManagedAgentsMCPAuthenticationFailedError object`
931912
932913 Authentication to an MCP server failed.
933914
from line 924
943924
944925 What the client should do next in response to this error.
945926
946 - `BetaManagedAgentsRetryStatusRetrying object { type }`
927 - `BetaManagedAgentsRetryStatusRetrying object`
947928
948929 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
949930
950 - `BetaManagedAgentsRetryStatusExhausted object { type }`
931 - `BetaManagedAgentsRetryStatusExhausted object`
951932
952933 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
953934
954 - `BetaManagedAgentsRetryStatusTerminal object { type }`
935 - `BetaManagedAgentsRetryStatusTerminal object`
955936
956937 The session encountered a terminal error and will transition to `terminated` state.
957938
958939 - `type: "mcp_authentication_failed_error"`
959940
960 - `"mcp_authentication_failed_error"`
961
962 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
941 - `BetaManagedAgentsBillingError object`
963942
964943 The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
965944
from line 950
971950
972951 What the client should do next in response to this error.
973952
974 - `BetaManagedAgentsRetryStatusRetrying object { type }`
953 - `BetaManagedAgentsRetryStatusRetrying object`
975954
976955 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
977956
978 - `BetaManagedAgentsRetryStatusExhausted object { type }`
957 - `BetaManagedAgentsRetryStatusExhausted object`
979958
980959 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
981960
982 - `BetaManagedAgentsRetryStatusTerminal object { type }`
961 - `BetaManagedAgentsRetryStatusTerminal object`
983962
984963 The session encountered a terminal error and will transition to `terminated` state.
985964
986965 - `type: "billing_error"`
987966
988 - `"billing_error"`
989
990 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
967 - `BetaManagedAgentsCredentialHostUnreachableError object`
991968
992969 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
993970
from line 980
1003980
1004981 What the client should do next in response to this error.
1005982
1006 - `BetaManagedAgentsRetryStatusRetrying object { type }`
983 - `BetaManagedAgentsRetryStatusRetrying object`
1007984
1008985 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
1009986
1010 - `BetaManagedAgentsRetryStatusExhausted object { type }`
987 - `BetaManagedAgentsRetryStatusExhausted object`
1011988
1012989 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1013990
1014 - `BetaManagedAgentsRetryStatusTerminal object { type }`
991 - `BetaManagedAgentsRetryStatusTerminal object`
1015992
1016993 The session encountered a terminal error and will transition to `terminated` state.
1017994
1018995 - `type: "credential_host_unreachable_error"`
1019996
1020 - `"credential_host_unreachable_error"`
1021
1022997 - `vault_id: string`
1023998
1024999 ID of the vault containing the affected credential.
from line 1002
10271002
10281003 A timestamp in RFC 3339 format
10291004
1005 format: date-time
1006
10301007 - `type: "session.error"`
10311008
1032 - `"session.error"`
1033
1034 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
1009 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
10351010
10361011 Indicates the session is recovering from an error state and is rescheduled for execution.
10371012
from line 1018
10431018
10441019 A timestamp in RFC 3339 format
10451020
1021 format: date-time
1022
10461023 - `type: "session.status_rescheduled"`
10471024
1048 - `"session.status_rescheduled"`
1049
1050 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
1025 - `BetaManagedAgentsSessionStatusRunningEvent object`
10511026
10521027 Indicates the session is actively running and the agent is working.
10531028
from line 1034
10591034
10601035 A timestamp in RFC 3339 format
10611036
1037 format: date-time
1038
10621039 - `type: "session.status_running"`
10631040
1064 - `"session.status_running"`
1065
1066 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
1041 - `BetaManagedAgentsSessionStatusIdleEvent object`
10671042
10681043 Indicates the agent has paused and is awaiting user input.
10691044
from line 1050
10751050
10761051 A timestamp in RFC 3339 format
10771052
1053 format: date-time
1054
10781055 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
10791056
10801057 The agent completed its turn naturally and is ready for the next user message.
10811058
1082 - `BetaManagedAgentsSessionEndTurn object { type }`
1059 - `BetaManagedAgentsSessionEndTurn object`
10831060
10841061 The agent completed its turn naturally and is ready for the next user message.
10851062
10861063 - `type: "end_turn"`
10871064
1088 - `"end_turn"`
1089
1090 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1065 - `BetaManagedAgentsSessionRequiresAction object`
10911066
10921067 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
10931068
from line 1072
10971072
10981073 - `type: "requires_action"`
10991074
1100 - `"requires_action"`
1101
1102 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1075 - `BetaManagedAgentsSessionRetriesExhausted object`
11031076
11041077 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
11051078
11061079 - `type: "retries_exhausted"`
11071080
1108 - `"retries_exhausted"`
1109
1110 - `BetaManagedAgentsSessionBudgetReached object { type }`
1081 - `BetaManagedAgentsSessionBudgetReached object`
11111082
11121083 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
11131084
11141085 - `type: "budget_reached"`
11151086
1116 - `"budget_reached"`
1117
11181087 - `type: "session.status_idle"`
11191088
1120 - `"session.status_idle"`
1121
1122 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
1089 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
11231090
11241091 Indicates the session has terminated, either due to an error or completion.
11251092
from line 1098
11311098
11321099 A timestamp in RFC 3339 format
11331100
1101 format: date-time
1102
11341103 - `type: "session.status_terminated"`
11351104
1136 - `"session.status_terminated"`
1137
1138 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
1105 - `BetaManagedAgentsSessionThreadCreatedEvent object`
11391106
11401107 Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
11411108
from line 1118
11511118
11521119 A timestamp in RFC 3339 format
11531120
1121 format: date-time
1122
11541123 - `session_thread_id: string`
11551124
11561125 Public `sthr_` ID of the newly created thread.
11571126
11581127 - `type: "session.thread_created"`
11591128
1160 - `"session.thread_created"`
1161
1162 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
1129 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
11631130
11641131 Emitted when an outcome evaluation cycle begins.
11651132
from line 1138
11711138
11721139 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
11731140
1141 format: int32
1142
11741143 - `outcome_id: string`
11751144
11761145 The `outc_` ID of the outcome being evaluated.
from line 1148
11791148
11801149 A timestamp in RFC 3339 format
11811150
1151 format: date-time
1152
11821153 - `type: "span.outcome_evaluation_start"`
11831154
1184 - `"span.outcome_evaluation_start"`
1185
1186 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
1155 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
11871156
11881157 Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.
11891158
from line 1168
11991168
12001169 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
12011170
1171 format: int32
1172
12021173 - `outcome_evaluation_start_id: string`
12031174
12041175 The id of the corresponding `span.outcome_evaluation_start` event.
from line 1182
12111182
12121183 A timestamp in RFC 3339 format
12131184
1185 format: date-time
1186
12141187 - `result: string`
12151188
12161189 Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
12171190
12181191 - `type: "span.outcome_evaluation_end"`
12191192
1220 - `"span.outcome_evaluation_end"`
1221
12221193 - `usage: BetaManagedAgentsSpanModelUsage`
12231194
12241195 Token usage for a single model request.
from line 1198
12271198
12281199 Tokens used to create prompt cache in this request.
12291200
1201 format: int32
1202
12301203 - `cache_read_input_tokens: number`
12311204
12321205 Tokens read from prompt cache in this request.
12331206
1207 format: int32
1208
12341209 - `input_tokens: number`
12351210
12361211 Input tokens consumed by this request.
12371212
1213 format: int32
1214
12381215 - `output_tokens: number`
12391216
12401217 Output tokens generated by this request.
12411218
1219 format: int32
1220
12421221 - `speed: optional "standard" or "fast" or null`
12431222
12441223 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1226
12471226
12481227 - `"fast"`
12491228
1250 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
1229 - `BetaManagedAgentsSpanModelRequestStartEvent object`
12511230
12521231 Emitted when a model request is initiated by the agent.
12531232
from line 1238
12591238
12601239 A timestamp in RFC 3339 format
12611240
1241 format: date-time
1242
12621243 - `type: "span.model_request_start"`
12631244
1264 - `"span.model_request_start"`
1265
1266 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
1245 - `BetaManagedAgentsSpanModelRequestEndEvent object`
12671246
12681247 Emitted when a model request completes.
12691248
from line 1266
12871266
12881267 A timestamp in RFC 3339 format
12891268
1269 format: date-time
1270
12901271 - `type: "span.model_request_end"`
12911272
1292 - `"span.model_request_end"`
1293
1294 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
1273 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
12951274
12961275 Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.
12971276
from line 1282
13031282
13041283 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
13051284
1285 format: int32
1286
13061287 - `outcome_id: string`
13071288
13081289 The `outc_` ID of the outcome being evaluated.
from line 1292
13111292
13121293 A timestamp in RFC 3339 format
13131294
1295 format: date-time
1296
13141297 - `type: "span.outcome_evaluation_ongoing"`
13151298
1316 - `"span.outcome_evaluation_ongoing"`
1317
1318 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
1299 - `BetaManagedAgentsUserDefineOutcomeEvent object`
13191300
13201301 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
13211302
from line 1312
13311312
13321313 Evaluate-then-revise cycles before giving up. Default 3, max 20.
13331314
1315 format: int32
1316
13341317 - `outcome_id: string`
13351318
13361319 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1322
13391322
13401323 A timestamp in RFC 3339 format
13411324
1325 format: date-time
1326
13421327 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
13431328
13441329 Rubric for grading the quality of an outcome.
13451330
1346 - `BetaManagedAgentsFileRubric object { file_id, type }`
1331 - `BetaManagedAgentsFileRubric object`
13471332
13481333 Rubric referenced by a file uploaded via the Files API.
13491334
from line 1338
13531338
13541339 - `type: "file"`
13551340
1356 - `"file"`
1357
1358 - `BetaManagedAgentsTextRubric object { content, type }`
1341 - `BetaManagedAgentsTextRubric object`
13591342
13601343 Rubric content provided inline as text.
13611344
from line 1348
13651348
13661349 - `type: "text"`
13671350
1368 - `"text"`
1369
13701351 - `type: "user.define_outcome"`
13711352
1372 - `"user.define_outcome"`
1373
1374 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
1353 - `BetaManagedAgentsSessionDeletedEvent object`
13751354
13761355 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
13771356
from line 1362
13831362
13841363 A timestamp in RFC 3339 format
13851364
1365 format: date-time
1366
13861367 - `type: "session.deleted"`
13871368
1388 - `"session.deleted"`
1389
1390 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
1369 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
13911370
13921371 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
13931372
from line 1382
14031382
14041383 A timestamp in RFC 3339 format
14051384
1385 format: date-time
1386
14061387 - `session_thread_id: string`
14071388
14081389 Public sthr_ ID of the thread that started running.
14091390
14101391 - `type: "session.thread_status_running"`
14111392
1412 - `"session.thread_status_running"`
1413
1414 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
1393 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
14151394
14161395 A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14171396
from line 1406
14271406
14281407 A timestamp in RFC 3339 format
14291408
1409 format: date-time
1410
14301411 - `session_thread_id: string`
14311412
14321413 Public sthr_ ID of the thread that went idle.
from line 1416
14351416
14361417 The agent completed its turn naturally and is ready for the next user message.
14371418
1438 - `BetaManagedAgentsSessionEndTurn object { type }`
1419 - `BetaManagedAgentsSessionEndTurn object`
14391420
14401421 The agent completed its turn naturally and is ready for the next user message.
14411422
1442 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1423 - `BetaManagedAgentsSessionRequiresAction object`
14431424
14441425 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
14451426
1446 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1427 - `BetaManagedAgentsSessionRetriesExhausted object`
14471428
14481429 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
14491430
1450 - `BetaManagedAgentsSessionBudgetReached object { type }`
1431 - `BetaManagedAgentsSessionBudgetReached object`
14511432
14521433 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
14531434
14541435 - `type: "session.thread_status_idle"`
14551436
1456 - `"session.thread_status_idle"`
1457
1458 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
1437 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
14591438
14601439 A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14611440
from line 1450
14711450
14721451 A timestamp in RFC 3339 format
14731452
1453 format: date-time
1454
14741455 - `session_thread_id: string`
14751456
14761457 Public sthr_ ID of the thread that terminated.
14771458
14781459 - `type: "session.thread_status_terminated"`
14791460
1480 - `"session.thread_status_terminated"`
1481
1482 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
1461 - `BetaManagedAgentsUserToolResultEvent object`
14831462
14841463 Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.
14851464
from line 1472
14931472
14941473 - `type: "user.tool_result"`
14951474
1496 - `"user.tool_result"`
1497
14981475 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
14991476
15001477 The result content returned by the tool.
15011478
1502 - `BetaManagedAgentsTextBlock object { text, type }`
1479 - `BetaManagedAgentsTextBlock object`
15031480
15041481 Regular text content.
15051482
1506 - `BetaManagedAgentsImageBlock object { source, type }`
1483 - `BetaManagedAgentsImageBlock object`
15071484
15081485 Image content specified directly as base64 data or as a reference via a URL.
15091486
1510 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1487 - `BetaManagedAgentsDocumentBlock object`
15111488
15121489 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
15131490
1514 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
1491 - `BetaManagedAgentsSearchResultBlock object`
15151492
15161493 A block containing a web search result.
15171494
from line 1500
15231500
15241501 A timestamp in RFC 3339 format
15251502
1503 format: date-time
1504
15261505 - `session_thread_id: optional string or null`
15271506
15281507 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
15291508
1530 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
1509 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
15311510
15321511 A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
15331512
from line 1522
15431522
15441523 A timestamp in RFC 3339 format
15451524
1525 format: date-time
1526
15461527 - `session_thread_id: string`
15471528
15481529 Public sthr_ ID of the thread that is retrying.
15491530
15501531 - `type: "session.thread_status_rescheduled"`
15511532
1552 - `"session.thread_status_rescheduled"`
1553
1554 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
1533 - `BetaManagedAgentsSessionUpdatedEvent object`
15551534
15561535 Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
15571536
from line 1542
15631542
15641543 A timestamp in RFC 3339 format
15651544
1545 format: date-time
1546
15661547 - `type: "session.updated"`
15671548
1568 - `"session.updated"`
1569
15701549 - `agent: optional BetaManagedAgentsSessionAgent or null`
15711550
15721551 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1560
15811560
15821561 - `type: "url"`
15831562
1584 - `"url"`
1585
15861563 - `url: string`
15871564
15881565 - `model: BetaManagedAgentsModelConfig`
from line 1636
16591636
16601637 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16611638
1662 - `BetaManagedAgentsEffortLow object { type }`
1639 - `BetaManagedAgentsEffortLow object`
16631640
16641641 Low effort. Favors latency over reasoning depth.
16651642
16661643 - `type: "low"`
16671644
1668 - `"low"`
1669
1670 - `BetaManagedAgentsEffortMedium object { type }`
1645 - `BetaManagedAgentsEffortMedium object`
16711646
16721647 Medium effort. Balances latency and reasoning depth.
16731648
16741649 - `type: "medium"`
16751650
1676 - `"medium"`
1677
1678 - `BetaManagedAgentsEffortHigh object { type }`
1651 - `BetaManagedAgentsEffortHigh object`
16791652
16801653 High effort. Favors reasoning depth.
16811654
16821655 - `type: "high"`
16831656
1684 - `"high"`
1685
1686 - `BetaManagedAgentsEffortXhigh object { type }`
1657 - `BetaManagedAgentsEffortXhigh object`
16871658
16881659 Extra-high effort. Not all models accept this level.
16891660
16901661 - `type: "xhigh"`
16911662
1692 - `"xhigh"`
1693
1694 - `BetaManagedAgentsEffortMax object { type }`
1663 - `BetaManagedAgentsEffortMax object`
16951664
16961665 Maximum effort. Favors reasoning depth over latency.
16971666
16981667 - `type: "max"`
16991668
1700 - `"max"`
1701
17021669 - `inference_geo: optional string`
17031670
17041671 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1686
17191686
17201687 Full `agent` definitions the coordinator may spawn as session threads.
17211688
1722 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1689 - `BetaManagedAgentsSessionThreadAgent object`
17231690
17241691 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`.
17251692
from line 1710
17431710
17441711 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17451712
1746 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1713 - `BetaManagedAgentsAnthropicSkill object`
17471714
17481715 A resolved Anthropic-managed skill.
17491716
from line 1718
17511718
17521719 - `type: "anthropic"`
17531720
1754 - `"anthropic"`
1755
17561721 - `version: string`
17571722
1758 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1723 - `BetaManagedAgentsCustomSkill object`
17591724
17601725 A resolved user-created custom skill.
17611726
from line 1728
17631728
17641729 - `type: "custom"`
17651730
1766 - `"custom"`
1767
17681731 - `version: string`
17691732
17701733 - `system: string or null`
17711734
17721735 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17731736
1774 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1737 - `BetaManagedAgentsAgentToolset20260401 object`
17751738
17761739 - `configs: array of BetaManagedAgentsAgentToolConfig`
17771740
1778 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1741 - `BetaManagedAgentsBashToolConfig object`
17791742
17801743 Configuration for the bash tool.
17811744
from line 1746
17831746
17841747 - `name: "bash"`
17851748
1786 - `"bash"`
1787
17881749 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
17891750
17901751 Permission policy for tool execution.
17911752
1792 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1753 - `BetaManagedAgentsAlwaysAllowPolicy object`
17931754
17941755 Tool calls are automatically approved without user confirmation.
17951756
17961757 - `type: "always_allow"`
17971758
1798 - `"always_allow"`
1799
1800 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1759 - `BetaManagedAgentsAlwaysAskPolicy object`
18011760
18021761 Tool calls require user confirmation before execution.
18031762
18041763 - `type: "always_ask"`
18051764
1806 - `"always_ask"`
1807
18081765 - `type: "bash"`
18091766
1810 - `"bash"`
1811
1812 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1767 - `BetaManagedAgentsEditToolConfig object`
18131768
18141769 Configuration for the edit tool.
18151770
from line 1772
18171772
18181773 - `name: "edit"`
18191774
1820 - `"edit"`
1821
18221775 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18231776
18241777 Permission policy for tool execution.
18251778
1826 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1779 - `BetaManagedAgentsAlwaysAllowPolicy object`
18271780
18281781 Tool calls are automatically approved without user confirmation.
18291782
1830 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1783 - `BetaManagedAgentsAlwaysAskPolicy object`
18311784
18321785 Tool calls require user confirmation before execution.
18331786
18341787 - `type: "edit"`
18351788
1836 - `"edit"`
1837
1838 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1789 - `BetaManagedAgentsReadToolConfig object`
18391790
18401791 Configuration for the read tool.
18411792
from line 1794
18431794
18441795 - `name: "read"`
18451796
1846 - `"read"`
1847
18481797 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18491798
18501799 Permission policy for tool execution.
18511800
1852 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1801 - `BetaManagedAgentsAlwaysAllowPolicy object`
18531802
18541803 Tool calls are automatically approved without user confirmation.
18551804
1856 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1805 - `BetaManagedAgentsAlwaysAskPolicy object`
18571806
18581807 Tool calls require user confirmation before execution.
18591808
18601809 - `type: "read"`
18611810
1862 - `"read"`
1863
1864 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1811 - `BetaManagedAgentsWriteToolConfig object`
18651812
18661813 Configuration for the write tool.
18671814
from line 1816
18691816
18701817 - `name: "write"`
18711818
1872 - `"write"`
1873
18741819 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18751820
18761821 Permission policy for tool execution.
18771822
1878 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1823 - `BetaManagedAgentsAlwaysAllowPolicy object`
18791824
18801825 Tool calls are automatically approved without user confirmation.
18811826
1882 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1827 - `BetaManagedAgentsAlwaysAskPolicy object`
18831828
18841829 Tool calls require user confirmation before execution.
18851830
18861831 - `type: "write"`
18871832
1888 - `"write"`
1889
1890 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1833 - `BetaManagedAgentsGlobToolConfig object`
18911834
18921835 Configuration for the glob tool.
18931836
from line 1838
18951838
18961839 - `name: "glob"`
18971840
1898 - `"glob"`
1899
19001841 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19011842
19021843 Permission policy for tool execution.
19031844
1904 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1845 - `BetaManagedAgentsAlwaysAllowPolicy object`
19051846
19061847 Tool calls are automatically approved without user confirmation.
19071848
1908 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1849 - `BetaManagedAgentsAlwaysAskPolicy object`
19091850
19101851 Tool calls require user confirmation before execution.
19111852
19121853 - `type: "glob"`
19131854
1914 - `"glob"`
1915
1916 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1855 - `BetaManagedAgentsGrepToolConfig object`
19171856
19181857 Configuration for the grep tool.
19191858
from line 1860
19211860
19221861 - `name: "grep"`
19231862
1924 - `"grep"`
1925
19261863 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19271864
19281865 Permission policy for tool execution.
19291866
1930 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1867 - `BetaManagedAgentsAlwaysAllowPolicy object`
19311868
19321869 Tool calls are automatically approved without user confirmation.
19331870
1934 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1871 - `BetaManagedAgentsAlwaysAskPolicy object`
19351872
19361873 Tool calls require user confirmation before execution.
19371874
19381875 - `type: "grep"`
19391876
1940 - `"grep"`
1941
1942 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1877 - `BetaManagedAgentsWebFetchToolConfig object`
19431878
19441879 Configuration for the web_fetch tool.
19451880
from line 1882
19471882
19481883 - `name: "web_fetch"`
19491884
1950 - `"web_fetch"`
1951
19521885 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19531886
19541887 Permission policy for tool execution.
19551888
1956 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1889 - `BetaManagedAgentsAlwaysAllowPolicy object`
19571890
19581891 Tool calls are automatically approved without user confirmation.
19591892
1960 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1893 - `BetaManagedAgentsAlwaysAskPolicy object`
19611894
19621895 Tool calls require user confirmation before execution.
19631896
19641897 - `type: "web_fetch"`
19651898
1966 - `"web_fetch"`
1967
19681899 - `allowed_domains: optional array of string`
19691900
19701901 - `blocked_domains: optional array of string`
19711902
19721903 - `max_content_tokens: optional number or null`
19731904
1974 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1905 format: int32
1906
1907 - `BetaManagedAgentsWebSearchToolConfig object`
19751908
19761909 Configuration for the web_search tool.
19771910
from line 1912
19791912
19801913 - `name: "web_search"`
19811914
1982 - `"web_search"`
1983
19841915 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19851916
19861917 Permission policy for tool execution.
19871918
1988 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1919 - `BetaManagedAgentsAlwaysAllowPolicy object`
19891920
19901921 Tool calls are automatically approved without user confirmation.
19911922
1992 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1923 - `BetaManagedAgentsAlwaysAskPolicy object`
19931924
19941925 Tool calls require user confirmation before execution.
19951926
19961927 - `type: "web_search"`
19971928
1998 - `"web_search"`
1999
20001929 - `allowed_domains: optional array of string`
20011930
20021931 - `blocked_domains: optional array of string`
from line 1938
20091938
20101939 Location precision. Only "approximate" is supported.
20111940
2012 - `"approximate"`
2013
20141941 - `city: optional string or null`
20151942
20161943 City name.
20171944
1945 minLength: 1, maxLength: 255
1946
20181947 - `country: optional string or null`
20191948
20201949 Two-letter ISO 3166-1 country code, uppercase.
from line 1952
20231952
20241953 Region or state name.
20251954
1955 minLength: 1, maxLength: 255
1956
20261957 - `timezone: optional string or null`
20271958
20281959 IANA timezone identifier, e.g. "America/Los_Angeles".
20291960
1961 minLength: 1, maxLength: 255
1962
20301963 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20311964
20321965 Resolved default configuration for agent tools.
from line 1970
20371970
20381971 Permission policy for tool execution.
20391972
2040 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1973 - `BetaManagedAgentsAlwaysAllowPolicy object`
20411974
20421975 Tool calls are automatically approved without user confirmation.
20431976
2044 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1977 - `BetaManagedAgentsAlwaysAskPolicy object`
20451978
20461979 Tool calls require user confirmation before execution.
20471980
20481981 - `type: "agent_toolset_20260401"`
20491982
2050 - `"agent_toolset_20260401"`
2051
2052 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1983 - `BetaManagedAgentsMCPToolset object`
20531984
20541985 - `configs: array of BetaManagedAgentsMCPToolConfig`
20551986
from line 1992
20611992
20621993 Permission policy for tool execution.
20631994
2064 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1995 - `BetaManagedAgentsAlwaysAllowPolicy object`
20651996
20661997 Tool calls are automatically approved without user confirmation.
20671998
2068 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1999 - `BetaManagedAgentsAlwaysAskPolicy object`
20692000
20702001 Tool calls require user confirmation before execution.
20712002
from line 2010
20792010
20802011 Permission policy for tool execution.
20812012
2082 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2013 - `BetaManagedAgentsAlwaysAllowPolicy object`
20832014
20842015 Tool calls are automatically approved without user confirmation.
20852016
2086 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2017 - `BetaManagedAgentsAlwaysAskPolicy object`
20872018
20882019 Tool calls require user confirmation before execution.
20892020
from line 2022
20912022
20922023 - `type: "mcp_toolset"`
20932024
2094 - `"mcp_toolset"`
2095
2096 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2025 - `BetaManagedAgentsCustomTool object`
20972026
20982027 A custom tool as returned in API responses.
20992028
from line 2034
21052034
21062035 - `type: "object"`
21072036
2108 - `"object"`
2109
21102037 - `properties: optional map[unknown] or null`
21112038
21122039 - `required: optional array of string or null`
from line 2042
21152042
21162043 - `type: "custom"`
21172044
2118 - `"custom"`
2119
21202045 - `type: "agent"`
21212046
2122 - `"agent"`
2123
21242047 - `version: number`
21252048
2126 - `BetaManagedAgentsAdvisor object { model, type }`
2049 format: int32
2050
2051 - `BetaManagedAgentsAdvisor object`
21272052
21282053 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
21292054
from line 2058
21332058
21342059 - `type: "advisor"`
21352060
2136 - `"advisor"`
2137
21382061 - `type: "coordinator"`
21392062
2140 - `"coordinator"`
2141
21422063 - `name: string`
21432064
21442065 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
21452066
2146 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2067 - `BetaManagedAgentsAnthropicSkill object`
21472068
21482069 A resolved Anthropic-managed skill.
21492070
2150 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2071 - `BetaManagedAgentsCustomSkill object`
21512072
21522073 A resolved user-created custom skill.
21532074
from line 2076
21552076
21562077 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
21572078
2158 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2159
2160 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2161
2162 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2079 - `BetaManagedAgentsAgentToolset20260401 object`
2080
2081 - `BetaManagedAgentsMCPToolset object`
2082
2083 - `BetaManagedAgentsCustomTool object`
21632084
21642085 A custom tool as returned in API responses.
21652086
21662087 - `type: "agent"`
21672088
2168 - `"agent"`
2169
21702089 - `version: number`
21712090
2091 format: int32
2092
21722093 - `budget: optional BetaManagedAgentsBudgetLimit or null`
21732094
21742095 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2106
21852106
21862107 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.
21872108
2188 - `"USD"`
2189
21902109 - `type: "limit"`
21912110
2192 - `"limit"`
2193
21942111 - `metadata: optional map[string]`
21952112
21962113 The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
from line 2116
21992116
22002117 The session's new title. Present only when the update changed it.
22012118
2202 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
2119 - `BetaManagedAgentsSystemMessageEvent object`
22032120
22042121 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
22052122
from line 2132
22152132
22162133 The text content.
22172134
2135 minLength: 1
2136
22182137 - `type: "text"`
22192138
2220 - `"text"`
2221
22222139 - `type: "system.message"`
22232140
2224 - `"system.message"`
2225
22262141 - `processed_at: optional string or null`
22272142
22282143 A timestamp in RFC 3339 format
22292144
2230 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
2145 format: date-time
2146
2147 - `BetaManagedAgentsSessionUsageEvent object`
22312148
22322149 Periodic snapshot of the session's cumulative usage and tracked list cost.
22332150
from line 2156
22392156
22402157 A timestamp in RFC 3339 format
22412158
2159 format: date-time
2160
22422161 - `type: "session.usage"`
22432162
2244 - `"session.usage"`
2245
22462163 - `usage: BetaManagedAgentsSessionUsageSnapshot`
22472164
22482165 Point-in-time snapshot of a session's cumulative usage.
from line 2168
22512168
22522169 Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
22532170
2171 format: double
2172
22542173 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
22552174
22562175 Prompt-cache creation token usage broken down by cache lifetime.
from line 2178
22592178
22602179 Tokens used to create 1-hour ephemeral cache entries.
22612180
2181 format: int32
2182
22622183 - `ephemeral_5m_input_tokens: optional number`
22632184
22642185 Tokens used to create 5-minute ephemeral cache entries.
22652186
2187 format: int32
2188
22662189 - `cache_read_input_tokens: optional number`
22672190
22682191 Total tokens read from prompt cache.
22692192
2193 format: int32
2194
22702195 - `input_tokens: optional number`
22712196
22722197 Total input tokens consumed across all turns.
22732198
2199 format: int32
2200
22742201 - `list_cost: optional BetaMonetaryAmount`
22752202
22762203 A monetary amount in a specific currency.
from line 2206
22792206
22802207 Total output tokens generated across all turns.
22812208
2209 format: int32
2210
22822211 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
22832212
22842213 Cumulative count of server-executed tool invocations, broken down by tool.
from line 2216
22872216
22882217 Number of server-executed web fetch requests.
22892218
2219 format: int32
2220
22902221 - `web_search_requests: optional number`
22912222
22922223 Number of server-executed web search requests.
22932224
2225 format: int32
2226
22942227 - `budget: optional BetaManagedAgentsBudgetLimit or null`
22952228
22962229 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2232
22992232
23002233 Opaque cursor for the next page. Null when no more results.
23012234
2302### Example
2303
2304```http
2235## Example
2236
2237```bash
23052238curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events \
23062239 -H 'anthropic-version: 2023-06-01' \
23072240 -H 'anthropic-beta: managed-agents-2026-04-01' \
23082241 -H "X-Api-Key: $ANTHROPIC_API_KEY"
23092242```
23102243
2311#### Response
2244### Response (200)
23122245
23132246```json
23142247{
23152248
api/beta/sessions/threads/events/stream Changed · +328 / -401 lines
# Stream Session Thread Events ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## Stream Session Thread Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Stream Session Thread Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/events/stream
4---
5
6## Stream Session Thread Events
7
8**get** `/v1/sessions/{session_id}/threads/{thread_id}/stream`
1# Stream Session Thread Events
2
3**GET** `/v1/sessions/{session_id}/threads/{thread_id}/stream`
94
105Stream Session Thread Events
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
1611- `thread_id: string`
1712
18### Query Parameters
13## Query parameters
1914
2015- `event_deltas: optional array of BetaManagedAgentsDeltaType`
2116
from line 20
2520
2621 - `"agent.thinking"`
2722
28### Header Parameters
23## Headers
2924
3025- `"anthropic-beta": optional array of AnthropicBeta`
3126
from line 98
10398
10499 - `"mid-conversation-tool-changes-2026-07-01"`
105100
106### Returns
101## Returns
107102
108103- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
109104
110105 Server-sent event in a single thread's stream.
111106
112 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
107 - `BetaManagedAgentsUserMessageEvent object`
113108
114109 A user message event in the session conversation.
115110
from line 116
121116
122117 Array of content blocks comprising the user message.
123118
124 - `BetaManagedAgentsTextBlock object { text, type }`
119 - `BetaManagedAgentsTextBlock object`
125120
126121 Regular text content.
127122
from line 124
129124
130125 The text content.
131126
127 minLength: 1
128
132129 - `type: "text"`
133130
134 - `"text"`
135
136 - `BetaManagedAgentsImageBlock object { source, type }`
131 - `BetaManagedAgentsImageBlock object`
137132
138133 Image content specified directly as base64 data or as a reference via a URL.
139134
from line 136
141136
142137 Union type for image source variants.
143138
144 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
139 - `BetaManagedAgentsBase64ImageSource object`
145140
146141 Base64-encoded image data.
147142
from line 144
149144
150145 Base64-encoded image data.
151146
147 minLength: 1
148
152149 - `media_type: string`
153150
154151 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
155152
153 minLength: 1
154
156155 - `type: "base64"`
157156
158 - `"base64"`
159
160 - `BetaManagedAgentsURLImageSource object { type, url }`
157 - `BetaManagedAgentsURLImageSource object`
161158
162159 Image referenced by URL.
163160
164161 - `type: "url"`
165162
166 - `"url"`
167
168163 - `url: string`
169164
170165 URL of the image to fetch.
171166
172 - `BetaManagedAgentsFileImageSource object { file_id, type }`
167 minLength: 1
168
169 - `BetaManagedAgentsFileImageSource object`
173170
174171 Image referenced by file ID.
175172
from line 174
177174
178175 ID of a previously uploaded file.
179176
177 minLength: 1
178
180179 - `type: "file"`
181180
182 - `"file"`
183
184181 - `type: "image"`
185182
186 - `"image"`
187
188 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
183 - `BetaManagedAgentsDocumentBlock object`
189184
190185 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
191186
from line 188
193188
194189 Union type for document source variants.
195190
196 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
191 - `BetaManagedAgentsBase64DocumentSource object`
197192
198193 Base64-encoded document data.
199194
from line 196
201196
202197 Base64-encoded document data.
203198
199 minLength: 1
200
204201 - `media_type: string`
205202
206203 MIME type of the document (e.g., "application/pdf").
207204
205 minLength: 1
206
208207 - `type: "base64"`
209208
210 - `"base64"`
211
212 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
209 - `BetaManagedAgentsPlainTextDocumentSource object`
213210
214211 Plain text document content.
215212
from line 214
217214
218215 The plain text content.
219216
217 minLength: 1
218
220219 - `media_type: "text/plain"`
221220
222221 MIME type of the text content. Must be "text/plain".
223222
224 - `"text/plain"`
225
226223 - `type: "text"`
227224
228 - `"text"`
229
230 - `BetaManagedAgentsURLDocumentSource object { type, url }`
225 - `BetaManagedAgentsURLDocumentSource object`
231226
232227 Document referenced by URL.
233228
234229 - `type: "url"`
235230
236 - `"url"`
237
238231 - `url: string`
239232
240233 URL of the document to fetch.
241234
242 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
235 minLength: 1
236
237 - `BetaManagedAgentsFileDocumentSource object`
243238
244239 Document referenced by file ID.
245240
from line 242
247242
248243 ID of a previously uploaded file.
249244
245 minLength: 1
246
250247 - `type: "file"`
251248
252 - `"file"`
253
254249 - `type: "document"`
255250
256 - `"document"`
257
258251 - `context: optional string or null`
259252
260253 Additional context about the document for the model.
from line 256
263256
264257 The title of the document.
265258
266 - `BetaManagedAgentsRedactedBlock object { type }`
259 - `BetaManagedAgentsRedactedBlock object`
267260
268261 Placeholder for content withheld by Anthropic model policy.
269262
270263 - `type: "redacted"`
271264
272 - `"redacted"`
273
274265 - `type: "user.message"`
275266
276 - `"user.message"`
277
278267 - `processed_at: optional string or null`
279268
280269 A timestamp in RFC 3339 format
281270
282 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
271 format: date-time
272
273 - `BetaManagedAgentsUserInterruptEvent object`
283274
284275 An interrupt event that pauses agent execution and returns control to the user.
285276
from line 280
289280
290281 - `type: "user.interrupt"`
291282
292 - `"user.interrupt"`
293
294283 - `processed_at: optional string or null`
295284
296285 A timestamp in RFC 3339 format
297286
287 format: date-time
288
298289 - `session_thread_id: optional string or null`
299290
300291 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
301292
302 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
293 - `BetaManagedAgentsUserToolConfirmationEvent object`
303294
304295 A tool confirmation event that approves or denies a pending tool execution.
305296
from line 312
321312
322313 - `type: "user.tool_confirmation"`
323314
324 - `"user.tool_confirmation"`
325
326315 - `deny_message: optional string or null`
327316
328317 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
329318
319 maxLength: 10000
320
330321 - `processed_at: optional string or null`
331322
332323 A timestamp in RFC 3339 format
333324
325 format: date-time
326
334327 - `session_thread_id: optional string or null`
335328
336329 When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.
337330
338 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
331 - `BetaManagedAgentsUserCustomToolResultEvent object`
339332
340333 Event sent by the client providing the result of a custom tool execution.
341334
from line 342
349342
350343 - `type: "user.custom_tool_result"`
351344
352 - `"user.custom_tool_result"`
353
354345 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
355346
356347 The result content returned by the tool.
357348
358 - `BetaManagedAgentsTextBlock object { text, type }`
349 - `BetaManagedAgentsTextBlock object`
359350
360351 Regular text content.
361352
362 - `BetaManagedAgentsImageBlock object { source, type }`
353 - `BetaManagedAgentsImageBlock object`
363354
364355 Image content specified directly as base64 data or as a reference via a URL.
365356
366 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
357 - `BetaManagedAgentsDocumentBlock object`
367358
368359 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
369360
370 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
361 - `BetaManagedAgentsSearchResultBlock object`
371362
372363 A block containing a web search result.
373364
from line 378
387378
388379 The text content.
389380
381 minLength: 1
382
390383 - `type: "text"`
391384
392 - `"text"`
393
394385 - `source: string`
395386
396387 The URL source of the search result.
397388
389 minLength: 1
390
398391 - `title: string`
399392
400393 The title of the search result.
401394
395 minLength: 1
396
402397 - `type: "search_result"`
403398
404 - `"search_result"`
405
406399 - `is_error: optional boolean or null`
407400
408401 Whether the tool execution resulted in an error.
from line 404
411404
412405 A timestamp in RFC 3339 format
413406
407 format: date-time
408
414409 - `session_thread_id: optional string or null`
415410
416411 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
417412
418 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
413 - `BetaManagedAgentsAgentCustomToolUseEvent object`
419414
420415 Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.
421416
from line 430
435430
436431 A timestamp in RFC 3339 format
437432
433 format: date-time
434
438435 - `type: "agent.custom_tool_use"`
439436
440 - `"agent.custom_tool_use"`
441
442437 - `session_thread_id: optional string or null`
443438
444439 When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.
445440
446 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
441 - `BetaManagedAgentsAgentMessageEvent object`
447442
448443 An agent response event in the session conversation.
449444
from line 450
455450
456451 Array of text blocks comprising the agent response.
457452
458 - `BetaManagedAgentsTextBlock object { text, type }`
453 - `BetaManagedAgentsTextBlock object`
459454
460455 Regular text content.
461456
462 - `BetaManagedAgentsRedactedBlock object { type }`
457 - `BetaManagedAgentsRedactedBlock object`
463458
464459 Placeholder for content withheld by Anthropic model policy.
465460
from line 462
467462
468463 A timestamp in RFC 3339 format
469464
465 format: date-time
466
470467 - `type: "agent.message"`
471468
472 - `"agent.message"`
473
474 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
469 - `BetaManagedAgentsAgentThinkingEvent object`
475470
476471 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
477472
from line 478
483478
484479 A timestamp in RFC 3339 format
485480
481 format: date-time
482
486483 - `type: "agent.thinking"`
487484
488 - `"agent.thinking"`
489
490 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
485 - `BetaManagedAgentsAgentMCPToolUseEvent object`
491486
492487 Event emitted when the agent invokes a tool provided by an MCP server.
493488
from line 506
511506
512507 A timestamp in RFC 3339 format
513508
509 format: date-time
510
514511 - `type: "agent.mcp_tool_use"`
515512
516 - `"agent.mcp_tool_use"`
517
518513 - `evaluated_permission: optional "allow" or "ask" or "deny"`
519514
520515 AgentEvaluatedPermission enum
from line 524
529524
530525 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
531526
532 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
527 - `BetaManagedAgentsAgentMCPToolResultEvent object`
533528
534529 Event representing the result of an MCP tool execution.
535530
from line 540
545540
546541 A timestamp in RFC 3339 format
547542
543 format: date-time
544
548545 - `type: "agent.mcp_tool_result"`
549546
550 - `"agent.mcp_tool_result"`
551
552547 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
553548
554549 The result content returned by the tool.
555550
556 - `BetaManagedAgentsTextBlock object { text, type }`
551 - `BetaManagedAgentsTextBlock object`
557552
558553 Regular text content.
559554
560 - `BetaManagedAgentsImageBlock object { source, type }`
555 - `BetaManagedAgentsImageBlock object`
561556
562557 Image content specified directly as base64 data or as a reference via a URL.
563558
564 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
559 - `BetaManagedAgentsDocumentBlock object`
565560
566561 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
567562
568 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
563 - `BetaManagedAgentsSearchResultBlock object`
569564
570565 A block containing a web search result.
571566
from line 568
573568
574569 Whether the tool execution resulted in an error.
575570
576 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
571 - `BetaManagedAgentsAgentToolUseEvent object`
577572
578573 Event emitted when the agent invokes a built-in agent tool.
579574
from line 588
593588
594589 A timestamp in RFC 3339 format
595590
591 format: date-time
592
596593 - `type: "agent.tool_use"`
597594
598 - `"agent.tool_use"`
599
600595 - `evaluated_permission: optional "allow" or "ask" or "deny"`
601596
602597 AgentEvaluatedPermission enum
from line 606
611606
612607 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
613608
614 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
609 - `BetaManagedAgentsAgentToolResultEvent object`
615610
616611 Event representing the result of an agent tool execution.
617612
from line 618
623618
624619 A timestamp in RFC 3339 format
625620
621 format: date-time
622
626623 - `tool_use_id: string`
627624
628625 The id of the `agent.tool_use` event this result corresponds to.
629626
630627 - `type: "agent.tool_result"`
631628
632 - `"agent.tool_result"`
633
634629 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
635630
636631 The result content returned by the tool.
637632
638 - `BetaManagedAgentsTextBlock object { text, type }`
633 - `BetaManagedAgentsTextBlock object`
639634
640635 Regular text content.
641636
642 - `BetaManagedAgentsImageBlock object { source, type }`
637 - `BetaManagedAgentsImageBlock object`
643638
644639 Image content specified directly as base64 data or as a reference via a URL.
645640
646 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
641 - `BetaManagedAgentsDocumentBlock object`
647642
648643 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
649644
650 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
645 - `BetaManagedAgentsSearchResultBlock object`
651646
652647 A block containing a web search result.
653648
from line 650
655650
656651 Whether the tool execution resulted in an error.
657652
658 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
653 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
659654
660655 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
661656
from line 662
667662
668663 Message content blocks.
669664
670 - `BetaManagedAgentsTextBlock object { text, type }`
665 - `BetaManagedAgentsTextBlock object`
671666
672667 Regular text content.
673668
674 - `BetaManagedAgentsImageBlock object { source, type }`
669 - `BetaManagedAgentsImageBlock object`
675670
676671 Image content specified directly as base64 data or as a reference via a URL.
677672
678 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
673 - `BetaManagedAgentsDocumentBlock object`
679674
680675 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
681676
682 - `BetaManagedAgentsRedactedBlock object { type }`
677 - `BetaManagedAgentsRedactedBlock object`
683678
684679 Placeholder for content withheld by Anthropic model policy.
685680
from line 686
691686
692687 A timestamp in RFC 3339 format
693688
689 format: date-time
690
694691 - `type: "agent.thread_message_received"`
695692
696 - `"agent.thread_message_received"`
697
698693 - `from_agent_name: optional string or null`
699694
700695 Name of the callable agent this message came from. Absent when received from the primary agent.
701696
702 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
697 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
703698
704699 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
705700
from line 706
711706
712707 Message content blocks.
713708
714 - `BetaManagedAgentsTextBlock object { text, type }`
709 - `BetaManagedAgentsTextBlock object`
715710
716711 Regular text content.
717712
718 - `BetaManagedAgentsImageBlock object { source, type }`
713 - `BetaManagedAgentsImageBlock object`
719714
720715 Image content specified directly as base64 data or as a reference via a URL.
721716
722 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
717 - `BetaManagedAgentsDocumentBlock object`
723718
724719 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
725720
726 - `BetaManagedAgentsRedactedBlock object { type }`
721 - `BetaManagedAgentsRedactedBlock object`
727722
728723 Placeholder for content withheld by Anthropic model policy.
729724
from line 726
731726
732727 A timestamp in RFC 3339 format
733728
729 format: date-time
730
734731 - `to_session_thread_id: string`
735732
736733 Public `sthr_` ID of the thread the message was sent to.
737734
738735 - `type: "agent.thread_message_sent"`
739736
740 - `"agent.thread_message_sent"`
741
742737 - `to_agent_name: optional string or null`
743738
744739 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
745740
746 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
741 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
747742
748743 Indicates that context compaction (summarization) occurred during the session.
749744
from line 750
755750
756751 A timestamp in RFC 3339 format
757752
753 format: date-time
754
758755 - `type: "agent.thread_context_compacted"`
759756
760 - `"agent.thread_context_compacted"`
761
762 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
757 - `BetaManagedAgentsSessionErrorEvent object`
763758
764759 An error event indicating a problem occurred during session execution.
765760
from line 766
771766
772767 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
773768
774 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
769 - `BetaManagedAgentsUnknownError object`
775770
776771 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
777772
from line 778
783778
784779 What the client should do next in response to this error.
785780
786 - `BetaManagedAgentsRetryStatusRetrying object { type }`
781 - `BetaManagedAgentsRetryStatusRetrying object`
787782
788783 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
789784
790785 - `type: "retrying"`
791786
792 - `"retrying"`
793
794 - `BetaManagedAgentsRetryStatusExhausted object { type }`
787 - `BetaManagedAgentsRetryStatusExhausted object`
795788
796789 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
797790
798791 - `type: "exhausted"`
799792
800 - `"exhausted"`
801
802 - `BetaManagedAgentsRetryStatusTerminal object { type }`
793 - `BetaManagedAgentsRetryStatusTerminal object`
803794
804795 The session encountered a terminal error and will transition to `terminated` state.
805796
806797 - `type: "terminal"`
807798
808 - `"terminal"`
809
810799 - `type: "unknown_error"`
811800
812 - `"unknown_error"`
813
814 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
801 - `BetaManagedAgentsModelOverloadedError object`
815802
816803 The model is currently overloaded. Emitted after automatic retries are exhausted.
817804
from line 810
823810
824811 What the client should do next in response to this error.
825812
826 - `BetaManagedAgentsRetryStatusRetrying object { type }`
813 - `BetaManagedAgentsRetryStatusRetrying object`
827814
828815 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
829816
830 - `BetaManagedAgentsRetryStatusExhausted object { type }`
817 - `BetaManagedAgentsRetryStatusExhausted object`
831818
832819 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
833820
834 - `BetaManagedAgentsRetryStatusTerminal object { type }`
821 - `BetaManagedAgentsRetryStatusTerminal object`
835822
836823 The session encountered a terminal error and will transition to `terminated` state.
837824
838825 - `type: "model_overloaded_error"`
839826
840 - `"model_overloaded_error"`
841
842 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
827 - `BetaManagedAgentsModelRateLimitedError object`
843828
844829 The model request was rate-limited.
845830
from line 836
851836
852837 What the client should do next in response to this error.
853838
854 - `BetaManagedAgentsRetryStatusRetrying object { type }`
839 - `BetaManagedAgentsRetryStatusRetrying object`
855840
856841 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
857842
858 - `BetaManagedAgentsRetryStatusExhausted object { type }`
843 - `BetaManagedAgentsRetryStatusExhausted object`
859844
860845 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
861846
862 - `BetaManagedAgentsRetryStatusTerminal object { type }`
847 - `BetaManagedAgentsRetryStatusTerminal object`
863848
864849 The session encountered a terminal error and will transition to `terminated` state.
865850
866851 - `type: "model_rate_limited_error"`
867852
868 - `"model_rate_limited_error"`
869
870 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
853 - `BetaManagedAgentsModelRequestFailedError object`
871854
872855 A model request failed for a reason other than overload or rate-limiting.
873856
from line 862
879862
880863 What the client should do next in response to this error.
881864
882 - `BetaManagedAgentsRetryStatusRetrying object { type }`
865 - `BetaManagedAgentsRetryStatusRetrying object`
883866
884867 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
885868
886 - `BetaManagedAgentsRetryStatusExhausted object { type }`
869 - `BetaManagedAgentsRetryStatusExhausted object`
887870
888871 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
889872
890 - `BetaManagedAgentsRetryStatusTerminal object { type }`
873 - `BetaManagedAgentsRetryStatusTerminal object`
891874
892875 The session encountered a terminal error and will transition to `terminated` state.
893876
894877 - `type: "model_request_failed_error"`
895878
896 - `"model_request_failed_error"`
897
898 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
879 - `BetaManagedAgentsMCPConnectionFailedError object`
899880
900881 Failed to connect to an MCP server.
901882
from line 892
911892
912893 What the client should do next in response to this error.
913894
914 - `BetaManagedAgentsRetryStatusRetrying object { type }`
895 - `BetaManagedAgentsRetryStatusRetrying object`
915896
916897 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
917898
918 - `BetaManagedAgentsRetryStatusExhausted object { type }`
899 - `BetaManagedAgentsRetryStatusExhausted object`
919900
920901 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
921902
922 - `BetaManagedAgentsRetryStatusTerminal object { type }`
903 - `BetaManagedAgentsRetryStatusTerminal object`
923904
924905 The session encountered a terminal error and will transition to `terminated` state.
925906
926907 - `type: "mcp_connection_failed_error"`
927908
928 - `"mcp_connection_failed_error"`
929
930 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
909 - `BetaManagedAgentsMCPAuthenticationFailedError object`
931910
932911 Authentication to an MCP server failed.
933912
from line 922
943922
944923 What the client should do next in response to this error.
945924
946 - `BetaManagedAgentsRetryStatusRetrying object { type }`
925 - `BetaManagedAgentsRetryStatusRetrying object`
947926
948927 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
949928
950 - `BetaManagedAgentsRetryStatusExhausted object { type }`
929 - `BetaManagedAgentsRetryStatusExhausted object`
951930
952931 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
953932
954 - `BetaManagedAgentsRetryStatusTerminal object { type }`
933 - `BetaManagedAgentsRetryStatusTerminal object`
955934
956935 The session encountered a terminal error and will transition to `terminated` state.
957936
958937 - `type: "mcp_authentication_failed_error"`
959938
960 - `"mcp_authentication_failed_error"`
961
962 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
939 - `BetaManagedAgentsBillingError object`
963940
964941 The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
965942
from line 948
971948
972949 What the client should do next in response to this error.
973950
974 - `BetaManagedAgentsRetryStatusRetrying object { type }`
951 - `BetaManagedAgentsRetryStatusRetrying object`
975952
976953 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
977954
978 - `BetaManagedAgentsRetryStatusExhausted object { type }`
955 - `BetaManagedAgentsRetryStatusExhausted object`
979956
980957 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
981958
982 - `BetaManagedAgentsRetryStatusTerminal object { type }`
959 - `BetaManagedAgentsRetryStatusTerminal object`
983960
984961 The session encountered a terminal error and will transition to `terminated` state.
985962
986963 - `type: "billing_error"`
987964
988 - `"billing_error"`
989
990 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
965 - `BetaManagedAgentsCredentialHostUnreachableError object`
991966
992967 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
993968
from line 978
1003978
1004979 What the client should do next in response to this error.
1005980
1006 - `BetaManagedAgentsRetryStatusRetrying object { type }`
981 - `BetaManagedAgentsRetryStatusRetrying object`
1007982
1008983 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
1009984
1010 - `BetaManagedAgentsRetryStatusExhausted object { type }`
985 - `BetaManagedAgentsRetryStatusExhausted object`
1011986
1012987 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1013988
1014 - `BetaManagedAgentsRetryStatusTerminal object { type }`
989 - `BetaManagedAgentsRetryStatusTerminal object`
1015990
1016991 The session encountered a terminal error and will transition to `terminated` state.
1017992
1018993 - `type: "credential_host_unreachable_error"`
1019994
1020 - `"credential_host_unreachable_error"`
1021
1022995 - `vault_id: string`
1023996
1024997 ID of the vault containing the affected credential.
from line 1000
10271000
10281001 A timestamp in RFC 3339 format
10291002
1003 format: date-time
1004
10301005 - `type: "session.error"`
10311006
1032 - `"session.error"`
1033
1034 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
1007 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
10351008
10361009 Indicates the session is recovering from an error state and is rescheduled for execution.
10371010
from line 1016
10431016
10441017 A timestamp in RFC 3339 format
10451018
1019 format: date-time
1020
10461021 - `type: "session.status_rescheduled"`
10471022
1048 - `"session.status_rescheduled"`
1049
1050 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
1023 - `BetaManagedAgentsSessionStatusRunningEvent object`
10511024
10521025 Indicates the session is actively running and the agent is working.
10531026
from line 1032
10591032
10601033 A timestamp in RFC 3339 format
10611034
1035 format: date-time
1036
10621037 - `type: "session.status_running"`
10631038
1064 - `"session.status_running"`
1065
1066 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
1039 - `BetaManagedAgentsSessionStatusIdleEvent object`
10671040
10681041 Indicates the agent has paused and is awaiting user input.
10691042
from line 1048
10751048
10761049 A timestamp in RFC 3339 format
10771050
1051 format: date-time
1052
10781053 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
10791054
10801055 The agent completed its turn naturally and is ready for the next user message.
10811056
1082 - `BetaManagedAgentsSessionEndTurn object { type }`
1057 - `BetaManagedAgentsSessionEndTurn object`
10831058
10841059 The agent completed its turn naturally and is ready for the next user message.
10851060
10861061 - `type: "end_turn"`
10871062
1088 - `"end_turn"`
1089
1090 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1063 - `BetaManagedAgentsSessionRequiresAction object`
10911064
10921065 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
10931066
from line 1070
10971070
10981071 - `type: "requires_action"`
10991072
1100 - `"requires_action"`
1101
1102 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1073 - `BetaManagedAgentsSessionRetriesExhausted object`
11031074
11041075 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
11051076
11061077 - `type: "retries_exhausted"`
11071078
1108 - `"retries_exhausted"`
1109
1110 - `BetaManagedAgentsSessionBudgetReached object { type }`
1079 - `BetaManagedAgentsSessionBudgetReached object`
11111080
11121081 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
11131082
11141083 - `type: "budget_reached"`
11151084
1116 - `"budget_reached"`
1117
11181085 - `type: "session.status_idle"`
11191086
1120 - `"session.status_idle"`
1121
1122 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
1087 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
11231088
11241089 Indicates the session has terminated, either due to an error or completion.
11251090
from line 1096
11311096
11321097 A timestamp in RFC 3339 format
11331098
1099 format: date-time
1100
11341101 - `type: "session.status_terminated"`
11351102
1136 - `"session.status_terminated"`
1137
1138 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
1103 - `BetaManagedAgentsSessionThreadCreatedEvent object`
11391104
11401105 Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
11411106
from line 1116
11511116
11521117 A timestamp in RFC 3339 format
11531118
1119 format: date-time
1120
11541121 - `session_thread_id: string`
11551122
11561123 Public `sthr_` ID of the newly created thread.
11571124
11581125 - `type: "session.thread_created"`
11591126
1160 - `"session.thread_created"`
1161
1162 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
1127 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
11631128
11641129 Emitted when an outcome evaluation cycle begins.
11651130
from line 1136
11711136
11721137 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
11731138
1139 format: int32
1140
11741141 - `outcome_id: string`
11751142
11761143 The `outc_` ID of the outcome being evaluated.
from line 1146
11791146
11801147 A timestamp in RFC 3339 format
11811148
1149 format: date-time
1150
11821151 - `type: "span.outcome_evaluation_start"`
11831152
1184 - `"span.outcome_evaluation_start"`
1185
1186 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
1153 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
11871154
11881155 Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.
11891156
from line 1166
11991166
12001167 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
12011168
1169 format: int32
1170
12021171 - `outcome_evaluation_start_id: string`
12031172
12041173 The id of the corresponding `span.outcome_evaluation_start` event.
from line 1180
12111180
12121181 A timestamp in RFC 3339 format
12131182
1183 format: date-time
1184
12141185 - `result: string`
12151186
12161187 Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
12171188
12181189 - `type: "span.outcome_evaluation_end"`
12191190
1220 - `"span.outcome_evaluation_end"`
1221
12221191 - `usage: BetaManagedAgentsSpanModelUsage`
12231192
12241193 Token usage for a single model request.
from line 1196
12271196
12281197 Tokens used to create prompt cache in this request.
12291198
1199 format: int32
1200
12301201 - `cache_read_input_tokens: number`
12311202
12321203 Tokens read from prompt cache in this request.
12331204
1205 format: int32
1206
12341207 - `input_tokens: number`
12351208
12361209 Input tokens consumed by this request.
12371210
1211 format: int32
1212
12381213 - `output_tokens: number`
12391214
12401215 Output tokens generated by this request.
12411216
1217 format: int32
1218
12421219 - `speed: optional "standard" or "fast" or null`
12431220
12441221 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1224
12471224
12481225 - `"fast"`
12491226
1250 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
1227 - `BetaManagedAgentsSpanModelRequestStartEvent object`
12511228
12521229 Emitted when a model request is initiated by the agent.
12531230
from line 1236
12591236
12601237 A timestamp in RFC 3339 format
12611238
1239 format: date-time
1240
12621241 - `type: "span.model_request_start"`
12631242
1264 - `"span.model_request_start"`
1265
1266 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
1243 - `BetaManagedAgentsSpanModelRequestEndEvent object`
12671244
12681245 Emitted when a model request completes.
12691246
from line 1264
12871264
12881265 A timestamp in RFC 3339 format
12891266
1267 format: date-time
1268
12901269 - `type: "span.model_request_end"`
12911270
1292 - `"span.model_request_end"`
1293
1294 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
1271 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
12951272
12961273 Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.
12971274
from line 1280
13031280
13041281 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
13051282
1283 format: int32
1284
13061285 - `outcome_id: string`
13071286
13081287 The `outc_` ID of the outcome being evaluated.
from line 1290
13111290
13121291 A timestamp in RFC 3339 format
13131292
1293 format: date-time
1294
13141295 - `type: "span.outcome_evaluation_ongoing"`
13151296
1316 - `"span.outcome_evaluation_ongoing"`
1317
1318 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
1297 - `BetaManagedAgentsUserDefineOutcomeEvent object`
13191298
13201299 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
13211300
from line 1310
13311310
13321311 Evaluate-then-revise cycles before giving up. Default 3, max 20.
13331312
1313 format: int32
1314
13341315 - `outcome_id: string`
13351316
13361317 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1320
13391320
13401321 A timestamp in RFC 3339 format
13411322
1323 format: date-time
1324
13421325 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
13431326
13441327 Rubric for grading the quality of an outcome.
13451328
1346 - `BetaManagedAgentsFileRubric object { file_id, type }`
1329 - `BetaManagedAgentsFileRubric object`
13471330
13481331 Rubric referenced by a file uploaded via the Files API.
13491332
from line 1336
13531336
13541337 - `type: "file"`
13551338
1356 - `"file"`
1357
1358 - `BetaManagedAgentsTextRubric object { content, type }`
1339 - `BetaManagedAgentsTextRubric object`
13591340
13601341 Rubric content provided inline as text.
13611342
from line 1346
13651346
13661347 - `type: "text"`
13671348
1368 - `"text"`
1369
13701349 - `type: "user.define_outcome"`
13711350
1372 - `"user.define_outcome"`
1373
1374 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
1351 - `BetaManagedAgentsSessionDeletedEvent object`
13751352
13761353 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
13771354
from line 1360
13831360
13841361 A timestamp in RFC 3339 format
13851362
1363 format: date-time
1364
13861365 - `type: "session.deleted"`
13871366
1388 - `"session.deleted"`
1389
1390 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
1367 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
13911368
13921369 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
13931370
from line 1380
14031380
14041381 A timestamp in RFC 3339 format
14051382
1383 format: date-time
1384
14061385 - `session_thread_id: string`
14071386
14081387 Public sthr_ ID of the thread that started running.
14091388
14101389 - `type: "session.thread_status_running"`
14111390
1412 - `"session.thread_status_running"`
1413
1414 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
1391 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
14151392
14161393 A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14171394
from line 1404
14271404
14281405 A timestamp in RFC 3339 format
14291406
1407 format: date-time
1408
14301409 - `session_thread_id: string`
14311410
14321411 Public sthr_ ID of the thread that went idle.
from line 1414
14351414
14361415 The agent completed its turn naturally and is ready for the next user message.
14371416
1438 - `BetaManagedAgentsSessionEndTurn object { type }`
1417 - `BetaManagedAgentsSessionEndTurn object`
14391418
14401419 The agent completed its turn naturally and is ready for the next user message.
14411420
1442 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1421 - `BetaManagedAgentsSessionRequiresAction object`
14431422
14441423 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
14451424
1446 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1425 - `BetaManagedAgentsSessionRetriesExhausted object`
14471426
14481427 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
14491428
1450 - `BetaManagedAgentsSessionBudgetReached object { type }`
1429 - `BetaManagedAgentsSessionBudgetReached object`
14511430
14521431 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
14531432
14541433 - `type: "session.thread_status_idle"`
14551434
1456 - `"session.thread_status_idle"`
1457
1458 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
1435 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
14591436
14601437 A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14611438
from line 1448
14711448
14721449 A timestamp in RFC 3339 format
14731450
1451 format: date-time
1452
14741453 - `session_thread_id: string`
14751454
14761455 Public sthr_ ID of the thread that terminated.
14771456
14781457 - `type: "session.thread_status_terminated"`
14791458
1480 - `"session.thread_status_terminated"`
1481
1482 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
1459 - `BetaManagedAgentsUserToolResultEvent object`
14831460
14841461 Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.
14851462
from line 1470
14931470
14941471 - `type: "user.tool_result"`
14951472
1496 - `"user.tool_result"`
1497
14981473 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
14991474
15001475 The result content returned by the tool.
15011476
1502 - `BetaManagedAgentsTextBlock object { text, type }`
1477 - `BetaManagedAgentsTextBlock object`
15031478
15041479 Regular text content.
15051480
1506 - `BetaManagedAgentsImageBlock object { source, type }`
1481 - `BetaManagedAgentsImageBlock object`
15071482
15081483 Image content specified directly as base64 data or as a reference via a URL.
15091484
1510 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1485 - `BetaManagedAgentsDocumentBlock object`
15111486
15121487 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
15131488
1514 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
1489 - `BetaManagedAgentsSearchResultBlock object`
15151490
15161491 A block containing a web search result.
15171492
from line 1498
15231498
15241499 A timestamp in RFC 3339 format
15251500
1501 format: date-time
1502
15261503 - `session_thread_id: optional string or null`
15271504
15281505 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
15291506
1530 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
1507 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
15311508
15321509 A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
15331510
from line 1520
15431520
15441521 A timestamp in RFC 3339 format
15451522
1523 format: date-time
1524
15461525 - `session_thread_id: string`
15471526
15481527 Public sthr_ ID of the thread that is retrying.
15491528
15501529 - `type: "session.thread_status_rescheduled"`
15511530
1552 - `"session.thread_status_rescheduled"`
1553
1554 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
1531 - `BetaManagedAgentsSessionUpdatedEvent object`
15551532
15561533 Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
15571534
from line 1540
15631540
15641541 A timestamp in RFC 3339 format
15651542
1543 format: date-time
1544
15661545 - `type: "session.updated"`
15671546
1568 - `"session.updated"`
1569
15701547 - `agent: optional BetaManagedAgentsSessionAgent or null`
15711548
15721549 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1558
15811558
15821559 - `type: "url"`
15831560
1584 - `"url"`
1585
15861561 - `url: string`
15871562
15881563 - `model: BetaManagedAgentsModelConfig`
from line 1634
16591634
16601635 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16611636
1662 - `BetaManagedAgentsEffortLow object { type }`
1637 - `BetaManagedAgentsEffortLow object`
16631638
16641639 Low effort. Favors latency over reasoning depth.
16651640
16661641 - `type: "low"`
16671642
1668 - `"low"`
1669
1670 - `BetaManagedAgentsEffortMedium object { type }`
1643 - `BetaManagedAgentsEffortMedium object`
16711644
16721645 Medium effort. Balances latency and reasoning depth.
16731646
16741647 - `type: "medium"`
16751648
1676 - `"medium"`
1677
1678 - `BetaManagedAgentsEffortHigh object { type }`
1649 - `BetaManagedAgentsEffortHigh object`
16791650
16801651 High effort. Favors reasoning depth.
16811652
16821653 - `type: "high"`
16831654
1684 - `"high"`
1685
1686 - `BetaManagedAgentsEffortXhigh object { type }`
1655 - `BetaManagedAgentsEffortXhigh object`
16871656
16881657 Extra-high effort. Not all models accept this level.
16891658
16901659 - `type: "xhigh"`
16911660
1692 - `"xhigh"`
1693
1694 - `BetaManagedAgentsEffortMax object { type }`
1661 - `BetaManagedAgentsEffortMax object`
16951662
16961663 Maximum effort. Favors reasoning depth over latency.
16971664
16981665 - `type: "max"`
16991666
1700 - `"max"`
1701
17021667 - `inference_geo: optional string`
17031668
17041669 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1684
17191684
17201685 Full `agent` definitions the coordinator may spawn as session threads.
17211686
1722 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1687 - `BetaManagedAgentsSessionThreadAgent object`
17231688
17241689 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`.
17251690
from line 1708
17431708
17441709 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17451710
1746 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1711 - `BetaManagedAgentsAnthropicSkill object`
17471712
17481713 A resolved Anthropic-managed skill.
17491714
from line 1716
17511716
17521717 - `type: "anthropic"`
17531718
1754 - `"anthropic"`
1755
17561719 - `version: string`
17571720
1758 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1721 - `BetaManagedAgentsCustomSkill object`
17591722
17601723 A resolved user-created custom skill.
17611724
from line 1726
17631726
17641727 - `type: "custom"`
17651728
1766 - `"custom"`
1767
17681729 - `version: string`
17691730
17701731 - `system: string or null`
17711732
17721733 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17731734
1774 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1735 - `BetaManagedAgentsAgentToolset20260401 object`
17751736
17761737 - `configs: array of BetaManagedAgentsAgentToolConfig`
17771738
1778 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1739 - `BetaManagedAgentsBashToolConfig object`
17791740
17801741 Configuration for the bash tool.
17811742
from line 1744
17831744
17841745 - `name: "bash"`
17851746
1786 - `"bash"`
1787
17881747 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
17891748
17901749 Permission policy for tool execution.
17911750
1792 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1751 - `BetaManagedAgentsAlwaysAllowPolicy object`
17931752
17941753 Tool calls are automatically approved without user confirmation.
17951754
17961755 - `type: "always_allow"`
17971756
1798 - `"always_allow"`
1799
1800 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1757 - `BetaManagedAgentsAlwaysAskPolicy object`
18011758
18021759 Tool calls require user confirmation before execution.
18031760
18041761 - `type: "always_ask"`
18051762
1806 - `"always_ask"`
1807
18081763 - `type: "bash"`
18091764
1810 - `"bash"`
1811
1812 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1765 - `BetaManagedAgentsEditToolConfig object`
18131766
18141767 Configuration for the edit tool.
18151768
from line 1770
18171770
18181771 - `name: "edit"`
18191772
1820 - `"edit"`
1821
18221773 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18231774
18241775 Permission policy for tool execution.
18251776
1826 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1777 - `BetaManagedAgentsAlwaysAllowPolicy object`
18271778
18281779 Tool calls are automatically approved without user confirmation.
18291780
1830 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1781 - `BetaManagedAgentsAlwaysAskPolicy object`
18311782
18321783 Tool calls require user confirmation before execution.
18331784
18341785 - `type: "edit"`
18351786
1836 - `"edit"`
1837
1838 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1787 - `BetaManagedAgentsReadToolConfig object`
18391788
18401789 Configuration for the read tool.
18411790
from line 1792
18431792
18441793 - `name: "read"`
18451794
1846 - `"read"`
1847
18481795 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18491796
18501797 Permission policy for tool execution.
18511798
1852 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1799 - `BetaManagedAgentsAlwaysAllowPolicy object`
18531800
18541801 Tool calls are automatically approved without user confirmation.
18551802
1856 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1803 - `BetaManagedAgentsAlwaysAskPolicy object`
18571804
18581805 Tool calls require user confirmation before execution.
18591806
18601807 - `type: "read"`
18611808
1862 - `"read"`
1863
1864 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1809 - `BetaManagedAgentsWriteToolConfig object`
18651810
18661811 Configuration for the write tool.
18671812
from line 1814
18691814
18701815 - `name: "write"`
18711816
1872 - `"write"`
1873
18741817 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18751818
18761819 Permission policy for tool execution.
18771820
1878 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1821 - `BetaManagedAgentsAlwaysAllowPolicy object`
18791822
18801823 Tool calls are automatically approved without user confirmation.
18811824
1882 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1825 - `BetaManagedAgentsAlwaysAskPolicy object`
18831826
18841827 Tool calls require user confirmation before execution.
18851828
18861829 - `type: "write"`
18871830
1888 - `"write"`
1889
1890 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1831 - `BetaManagedAgentsGlobToolConfig object`
18911832
18921833 Configuration for the glob tool.
18931834
from line 1836
18951836
18961837 - `name: "glob"`
18971838
1898 - `"glob"`
1899
19001839 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19011840
19021841 Permission policy for tool execution.
19031842
1904 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1843 - `BetaManagedAgentsAlwaysAllowPolicy object`
19051844
19061845 Tool calls are automatically approved without user confirmation.
19071846
1908 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1847 - `BetaManagedAgentsAlwaysAskPolicy object`
19091848
19101849 Tool calls require user confirmation before execution.
19111850
19121851 - `type: "glob"`
19131852
1914 - `"glob"`
1915
1916 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1853 - `BetaManagedAgentsGrepToolConfig object`
19171854
19181855 Configuration for the grep tool.
19191856
from line 1858
19211858
19221859 - `name: "grep"`
19231860
1924 - `"grep"`
1925
19261861 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19271862
19281863 Permission policy for tool execution.
19291864
1930 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1865 - `BetaManagedAgentsAlwaysAllowPolicy object`
19311866
19321867 Tool calls are automatically approved without user confirmation.
19331868
1934 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1869 - `BetaManagedAgentsAlwaysAskPolicy object`
19351870
19361871 Tool calls require user confirmation before execution.
19371872
19381873 - `type: "grep"`
19391874
1940 - `"grep"`
1941
1942 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1875 - `BetaManagedAgentsWebFetchToolConfig object`
19431876
19441877 Configuration for the web_fetch tool.
19451878
from line 1880
19471880
19481881 - `name: "web_fetch"`
19491882
1950 - `"web_fetch"`
1951
19521883 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19531884
19541885 Permission policy for tool execution.
19551886
1956 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1887 - `BetaManagedAgentsAlwaysAllowPolicy object`
19571888
19581889 Tool calls are automatically approved without user confirmation.
19591890
1960 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1891 - `BetaManagedAgentsAlwaysAskPolicy object`
19611892
19621893 Tool calls require user confirmation before execution.
19631894
19641895 - `type: "web_fetch"`
19651896
1966 - `"web_fetch"`
1967
19681897 - `allowed_domains: optional array of string`
19691898
19701899 - `blocked_domains: optional array of string`
19711900
19721901 - `max_content_tokens: optional number or null`
19731902
1974 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1903 format: int32
1904
1905 - `BetaManagedAgentsWebSearchToolConfig object`
19751906
19761907 Configuration for the web_search tool.
19771908
from line 1910
19791910
19801911 - `name: "web_search"`
19811912
1982 - `"web_search"`
1983
19841913 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19851914
19861915 Permission policy for tool execution.
19871916
1988 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1917 - `BetaManagedAgentsAlwaysAllowPolicy object`
19891918
19901919 Tool calls are automatically approved without user confirmation.
19911920
1992 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1921 - `BetaManagedAgentsAlwaysAskPolicy object`
19931922
19941923 Tool calls require user confirmation before execution.
19951924
19961925 - `type: "web_search"`
19971926
1998 - `"web_search"`
1999
20001927 - `allowed_domains: optional array of string`
20011928
20021929 - `blocked_domains: optional array of string`
from line 1936
20091936
20101937 Location precision. Only "approximate" is supported.
20111938
2012 - `"approximate"`
2013
20141939 - `city: optional string or null`
20151940
20161941 City name.
20171942
1943 minLength: 1, maxLength: 255
1944
20181945 - `country: optional string or null`
20191946
20201947 Two-letter ISO 3166-1 country code, uppercase.
from line 1950
20231950
20241951 Region or state name.
20251952
1953 minLength: 1, maxLength: 255
1954
20261955 - `timezone: optional string or null`
20271956
20281957 IANA timezone identifier, e.g. "America/Los_Angeles".
20291958
1959 minLength: 1, maxLength: 255
1960
20301961 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20311962
20321963 Resolved default configuration for agent tools.
from line 1968
20371968
20381969 Permission policy for tool execution.
20391970
2040 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1971 - `BetaManagedAgentsAlwaysAllowPolicy object`
20411972
20421973 Tool calls are automatically approved without user confirmation.
20431974
2044 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1975 - `BetaManagedAgentsAlwaysAskPolicy object`
20451976
20461977 Tool calls require user confirmation before execution.
20471978
20481979 - `type: "agent_toolset_20260401"`
20491980
2050 - `"agent_toolset_20260401"`
2051
2052 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1981 - `BetaManagedAgentsMCPToolset object`
20531982
20541983 - `configs: array of BetaManagedAgentsMCPToolConfig`
20551984
from line 1990
20611990
20621991 Permission policy for tool execution.
20631992
2064 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1993 - `BetaManagedAgentsAlwaysAllowPolicy object`
20651994
20661995 Tool calls are automatically approved without user confirmation.
20671996
2068 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1997 - `BetaManagedAgentsAlwaysAskPolicy object`
20691998
20701999 Tool calls require user confirmation before execution.
20712000
from line 2008
20792008
20802009 Permission policy for tool execution.
20812010
2082 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2011 - `BetaManagedAgentsAlwaysAllowPolicy object`
20832012
20842013 Tool calls are automatically approved without user confirmation.
20852014
2086 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2015 - `BetaManagedAgentsAlwaysAskPolicy object`
20872016
20882017 Tool calls require user confirmation before execution.
20892018
from line 2020
20912020
20922021 - `type: "mcp_toolset"`
20932022
2094 - `"mcp_toolset"`
2095
2096 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2023 - `BetaManagedAgentsCustomTool object`
20972024
20982025 A custom tool as returned in API responses.
20992026
from line 2032
21052032
21062033 - `type: "object"`
21072034
2108 - `"object"`
2109
21102035 - `properties: optional map[unknown] or null`
21112036
21122037 - `required: optional array of string or null`
from line 2040
21152040
21162041 - `type: "custom"`
21172042
2118 - `"custom"`
2119
21202043 - `type: "agent"`
21212044
2122 - `"agent"`
2123
21242045 - `version: number`
21252046
2126 - `BetaManagedAgentsAdvisor object { model, type }`
2047 format: int32
2048
2049 - `BetaManagedAgentsAdvisor object`
21272050
21282051 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
21292052
from line 2056
21332056
21342057 - `type: "advisor"`
21352058
2136 - `"advisor"`
2137
21382059 - `type: "coordinator"`
21392060
2140 - `"coordinator"`
2141
21422061 - `name: string`
21432062
21442063 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
21452064
2146 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2065 - `BetaManagedAgentsAnthropicSkill object`
21472066
21482067 A resolved Anthropic-managed skill.
21492068
2150 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2069 - `BetaManagedAgentsCustomSkill object`
21512070
21522071 A resolved user-created custom skill.
21532072
from line 2074
21552074
21562075 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
21572076
2158 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2159
2160 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2161
2162 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2077 - `BetaManagedAgentsAgentToolset20260401 object`
2078
2079 - `BetaManagedAgentsMCPToolset object`
2080
2081 - `BetaManagedAgentsCustomTool object`
21632082
21642083 A custom tool as returned in API responses.
21652084
21662085 - `type: "agent"`
21672086
2168 - `"agent"`
2169
21702087 - `version: number`
21712088
2089 format: int32
2090
21722091 - `budget: optional BetaManagedAgentsBudgetLimit or null`
21732092
21742093 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2104
21852104
21862105 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.
21872106
2188 - `"USD"`
2189
21902107 - `type: "limit"`
21912108
2192 - `"limit"`
2193
21942109 - `metadata: optional map[string]`
21952110
21962111 The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
from line 2114
21992114
22002115 The session's new title. Present only when the update changed it.
22012116
2202 - `BetaManagedAgentsStartEvent object { event, type }`
2117 - `BetaManagedAgentsStartEvent object`
22032118
22042119 Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
22052120
from line 2122
22072122
22082123 The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.
22092124
2210 - `BetaManagedAgentsAgentMessagePreview object { id, type }`
2125 - `BetaManagedAgentsAgentMessagePreview object`
22112126
22122127 - `id: string`
22132128
from line 2130
22152130
22162131 - `type: "agent.message"`
22172132
2218 - `"agent.message"`
2219
2220 - `BetaManagedAgentsAgentThinkingPreview object { id, type }`
2133 - `BetaManagedAgentsAgentThinkingPreview object`
22212134
22222135 - `id: string`
22232136
from line 2138
22252138
22262139 - `type: "agent.thinking"`
22272140
2228 - `"agent.thinking"`
2229
22302141 - `type: "event_start"`
22312142
2232 - `"event_start"`
2233
2234 - `BetaManagedAgentsDeltaEvent object { delta, event_id, type }`
2143 - `BetaManagedAgentsDeltaEvent object`
22352144
22362145 An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
22372146
from line 2154
22452154
22462155 - `type: "content_delta"`
22472156
2248 - `"content_delta"`
2249
22502157 - `index: optional number`
22512158
22522159 Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.
22532160
2161 format: uint32
2162
22542163 - `event_id: string`
22552164
22562165 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
22572166
22582167 - `type: "event_delta"`
22592168
2260 - `"event_delta"`
2261
2262 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
2169 - `BetaManagedAgentsSystemMessageEvent object`
22632170
22642171 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
22652172
from line 2182
22752182
22762183 The text content.
22772184
2185 minLength: 1
2186
22782187 - `type: "text"`
22792188
2280 - `"text"`
2281
22822189 - `type: "system.message"`
22832190
2284 - `"system.message"`
2285
22862191 - `processed_at: optional string or null`
22872192
22882193 A timestamp in RFC 3339 format
22892194
2290 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
2195 format: date-time
2196
2197 - `BetaManagedAgentsSessionUsageEvent object`
22912198
22922199 Periodic snapshot of the session's cumulative usage and tracked list cost.
22932200
from line 2206
22992206
23002207 A timestamp in RFC 3339 format
23012208
2209 format: date-time
2210
23022211 - `type: "session.usage"`
23032212
2304 - `"session.usage"`
2305
23062213 - `usage: BetaManagedAgentsSessionUsageSnapshot`
23072214
23082215 Point-in-time snapshot of a session's cumulative usage.
from line 2218
23112218
23122219 Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
23132220
2221 format: double
2222
23142223 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
23152224
23162225 Prompt-cache creation token usage broken down by cache lifetime.
from line 2228
23192228
23202229 Tokens used to create 1-hour ephemeral cache entries.
23212230
2231 format: int32
2232
23222233 - `ephemeral_5m_input_tokens: optional number`
23232234
23242235 Tokens used to create 5-minute ephemeral cache entries.
23252236
2237 format: int32
2238
23262239 - `cache_read_input_tokens: optional number`
23272240
23282241 Total tokens read from prompt cache.
23292242
2243 format: int32
2244
23302245 - `input_tokens: optional number`
23312246
23322247 Total input tokens consumed across all turns.
23332248
2249 format: int32
2250
23342251 - `list_cost: optional BetaMonetaryAmount`
23352252
23362253 A monetary amount in a specific currency.
from line 2256
23392256
23402257 Total output tokens generated across all turns.
23412258
2259 format: int32
2260
23422261 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
23432262
23442263 Cumulative count of server-executed tool invocations, broken down by tool.
from line 2266
23472266
23482267 Number of server-executed web fetch requests.
23492268
2269 format: int32
2270
23502271 - `web_search_requests: optional number`
23512272
23522273 Number of server-executed web search requests.
23532274
2275 format: int32
2276
23542277 - `budget: optional BetaManagedAgentsBudgetLimit or null`
23552278
23562279 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
23572280
2358### Example
2359
2360```http
2281- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
2282
2283 Server-sent event in a single thread's stream.
2284
2285## Example
2286
2287```bash
23612288curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream \
23622289 -H 'anthropic-version: 2023-06-01' \
23632290 -H 'anthropic-beta: managed-agents-2026-04-01' \
23642291 -H "X-Api-Key: $ANTHROPIC_API_KEY"
23652292```
23662293
2367#### Response
2294### Response (200)
23682295
23692296```json
23702297{
23712298
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
1---
2title: List Session Threads
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/list
4---
1# List Session Threads
52
6## List Session Threads
3**GET** `/v1/sessions/{session_id}/threads`
74
8**get** `/v1/sessions/{session_id}/threads`
9
105List Session Threads
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
16### Query Parameters
11## Query parameters
1712
1813- `limit: optional number`
1914
2015 Maximum results per page. Defaults to 1000.
2116
17 format: int32
18
2219- `page: optional string`
2320
2421 Opaque pagination cursor from a previous response's next_page. Forward-only.
2522
26### Header Parameters
23## Headers
2724
2825- `"anthropic-beta": optional array of AnthropicBeta`
2926
from line 98
10198
10299 - `"mid-conversation-tool-changes-2026-07-01"`
103100
104### Returns
101## Returns
105102
106103- `data: optional array of BetaManagedAgentsSessionThread`
107104
from line 112
115112
116113 A session-resolved multiagent roster entry.
117114
118 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
115 - `BetaManagedAgentsSessionThreadAgent object`
119116
120117 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`.
121118
from line 126
129126
130127 - `type: "url"`
131128
132 - `"url"`
133
134129 - `url: string`
135130
136131 - `model: BetaManagedAgentsModelConfig`
from line 202
207202
208203 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
209204
210 - `BetaManagedAgentsEffortLow object { type }`
205 - `BetaManagedAgentsEffortLow object`
211206
212207 Low effort. Favors latency over reasoning depth.
213208
214209 - `type: "low"`
215210
216 - `"low"`
211 - `BetaManagedAgentsEffortMedium object`
217212
218 - `BetaManagedAgentsEffortMedium object { type }`
219
220213 Medium effort. Balances latency and reasoning depth.
221214
222215 - `type: "medium"`
223216
224 - `"medium"`
217 - `BetaManagedAgentsEffortHigh object`
225218
226 - `BetaManagedAgentsEffortHigh object { type }`
227
228219 High effort. Favors reasoning depth.
229220
230221 - `type: "high"`
231222
232 - `"high"`
223 - `BetaManagedAgentsEffortXhigh object`
233224
234 - `BetaManagedAgentsEffortXhigh object { type }`
235
236225 Extra-high effort. Not all models accept this level.
237226
238227 - `type: "xhigh"`
239228
240 - `"xhigh"`
229 - `BetaManagedAgentsEffortMax object`
241230
242 - `BetaManagedAgentsEffortMax object { type }`
243
244231 Maximum effort. Favors reasoning depth over latency.
245232
246233 - `type: "max"`
247234
248 - `"max"`
249
250235 - `inference_geo: optional string`
251236
252237 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 248
263248
264249 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
265250
266 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
251 - `BetaManagedAgentsAnthropicSkill object`
267252
268253 A resolved Anthropic-managed skill.
269254
from line 256
271256
272257 - `type: "anthropic"`
273258
274 - `"anthropic"`
275
276259 - `version: string`
277260
278 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
261 - `BetaManagedAgentsCustomSkill object`
279262
280263 A resolved user-created custom skill.
281264
from line 266
283266
284267 - `type: "custom"`
285268
286 - `"custom"`
287
288269 - `version: string`
289270
290271 - `system: string or null`
from line 272
291272
292273 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
293274
294 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
275 - `BetaManagedAgentsAgentToolset20260401 object`
295276
296277 - `configs: array of BetaManagedAgentsAgentToolConfig`
297278
298 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
279 - `BetaManagedAgentsBashToolConfig object`
299280
300281 Configuration for the bash tool.
301282
from line 284
303284
304285 - `name: "bash"`
305286
306 - `"bash"`
307
308287 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
309288
310289 Permission policy for tool execution.
311290
312 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
291 - `BetaManagedAgentsAlwaysAllowPolicy object`
313292
314293 Tool calls are automatically approved without user confirmation.
315294
316295 - `type: "always_allow"`
317296
318 - `"always_allow"`
297 - `BetaManagedAgentsAlwaysAskPolicy object`
319298
320 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
321
322299 Tool calls require user confirmation before execution.
323300
324301 - `type: "always_ask"`
325302
326 - `"always_ask"`
327
328303 - `type: "bash"`
329304
330 - `"bash"`
305 - `BetaManagedAgentsEditToolConfig object`
331306
332 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
333
334307 Configuration for the edit tool.
335308
336309 - `enabled: boolean`
from line 310
337310
338311 - `name: "edit"`
339312
340 - `"edit"`
341
342313 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
343314
344315 Permission policy for tool execution.
345316
346 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
317 - `BetaManagedAgentsAlwaysAllowPolicy object`
347318
348319 Tool calls are automatically approved without user confirmation.
349320
350 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
321 - `BetaManagedAgentsAlwaysAskPolicy object`
351322
352323 Tool calls require user confirmation before execution.
353324
354325 - `type: "edit"`
355326
356 - `"edit"`
327 - `BetaManagedAgentsReadToolConfig object`
357328
358 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
359
360329 Configuration for the read tool.
361330
362331 - `enabled: boolean`
from line 332
363332
364333 - `name: "read"`
365334
366 - `"read"`
367
368335 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
369336
370337 Permission policy for tool execution.
371338
372 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
339 - `BetaManagedAgentsAlwaysAllowPolicy object`
373340
374341 Tool calls are automatically approved without user confirmation.
375342
376 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
343 - `BetaManagedAgentsAlwaysAskPolicy object`
377344
378345 Tool calls require user confirmation before execution.
379346
380347 - `type: "read"`
381348
382 - `"read"`
349 - `BetaManagedAgentsWriteToolConfig object`
383350
384 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
385
386351 Configuration for the write tool.
387352
388353 - `enabled: boolean`
from line 354
389354
390355 - `name: "write"`
391356
392 - `"write"`
393
394357 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
395358
396359 Permission policy for tool execution.
397360
398 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
361 - `BetaManagedAgentsAlwaysAllowPolicy object`
399362
400363 Tool calls are automatically approved without user confirmation.
401364
402 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
365 - `BetaManagedAgentsAlwaysAskPolicy object`
403366
404367 Tool calls require user confirmation before execution.
405368
406369 - `type: "write"`
407370
408 - `"write"`
371 - `BetaManagedAgentsGlobToolConfig object`
409372
410 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
411
412373 Configuration for the glob tool.
413374
414375 - `enabled: boolean`
from line 376
415376
416377 - `name: "glob"`
417378
418 - `"glob"`
419
420379 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
421380
422381 Permission policy for tool execution.
423382
424 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
383 - `BetaManagedAgentsAlwaysAllowPolicy object`
425384
426385 Tool calls are automatically approved without user confirmation.
427386
428 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
387 - `BetaManagedAgentsAlwaysAskPolicy object`
429388
430389 Tool calls require user confirmation before execution.
431390
432391 - `type: "glob"`
433392
434 - `"glob"`
393 - `BetaManagedAgentsGrepToolConfig object`
435394
436 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
437
438395 Configuration for the grep tool.
439396
440397 - `enabled: boolean`
from line 398
441398
442399 - `name: "grep"`
443400
444 - `"grep"`
445
446401 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
447402
448403 Permission policy for tool execution.
449404
450 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
405 - `BetaManagedAgentsAlwaysAllowPolicy object`
451406
452407 Tool calls are automatically approved without user confirmation.
453408
454 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
409 - `BetaManagedAgentsAlwaysAskPolicy object`
455410
456411 Tool calls require user confirmation before execution.
457412
458413 - `type: "grep"`
459414
460 - `"grep"`
415 - `BetaManagedAgentsWebFetchToolConfig object`
461416
462 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
463
464417 Configuration for the web_fetch tool.
465418
466419 - `enabled: boolean`
from line 420
467420
468421 - `name: "web_fetch"`
469422
470 - `"web_fetch"`
471
472423 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
473424
474425 Permission policy for tool execution.
475426
476 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
427 - `BetaManagedAgentsAlwaysAllowPolicy object`
477428
478429 Tool calls are automatically approved without user confirmation.
479430
480 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
431 - `BetaManagedAgentsAlwaysAskPolicy object`
481432
482433 Tool calls require user confirmation before execution.
483434
484435 - `type: "web_fetch"`
485436
486 - `"web_fetch"`
487
488437 - `allowed_domains: optional array of string`
489438
490439 - `blocked_domains: optional array of string`
from line 440
491440
492441 - `max_content_tokens: optional number or null`
493442
494 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
443 format: int32
495444
445 - `BetaManagedAgentsWebSearchToolConfig object`
446
496447 Configuration for the web_search tool.
497448
498449 - `enabled: boolean`
from line 450
499450
500451 - `name: "web_search"`
501452
502 - `"web_search"`
503
504453 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
505454
506455 Permission policy for tool execution.
507456
508 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
457 - `BetaManagedAgentsAlwaysAllowPolicy object`
509458
510459 Tool calls are automatically approved without user confirmation.
511460
512 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
461 - `BetaManagedAgentsAlwaysAskPolicy object`
513462
514463 Tool calls require user confirmation before execution.
515464
516465 - `type: "web_search"`
517466
518 - `"web_search"`
519
520467 - `allowed_domains: optional array of string`
521468
522469 - `blocked_domains: optional array of string`
from line 476
529476
530477 Location precision. Only "approximate" is supported.
531478
532 - `"approximate"`
533
534479 - `city: optional string or null`
535480
536481 City name.
537482
483 minLength: 1, maxLength: 255
484
538485 - `country: optional string or null`
539486
540487 Two-letter ISO 3166-1 country code, uppercase.
from line 490
543490
544491 Region or state name.
545492
493 minLength: 1, maxLength: 255
494
546495 - `timezone: optional string or null`
547496
548497 IANA timezone identifier, e.g. "America/Los_Angeles".
549498
499 minLength: 1, maxLength: 255
500
550501 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
551502
552503 Resolved default configuration for agent tools.
from line 508
557508
558509 Permission policy for tool execution.
559510
560 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
511 - `BetaManagedAgentsAlwaysAllowPolicy object`
561512
562513 Tool calls are automatically approved without user confirmation.
563514
564 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
515 - `BetaManagedAgentsAlwaysAskPolicy object`
565516
566517 Tool calls require user confirmation before execution.
567518
568519 - `type: "agent_toolset_20260401"`
569520
570 - `"agent_toolset_20260401"`
521 - `BetaManagedAgentsMCPToolset object`
571522
572 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
573
574523 - `configs: array of BetaManagedAgentsMCPToolConfig`
575524
576525 - `enabled: boolean`
from line 530
581530
582531 Permission policy for tool execution.
583532
584 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
533 - `BetaManagedAgentsAlwaysAllowPolicy object`
585534
586535 Tool calls are automatically approved without user confirmation.
587536
588 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
537 - `BetaManagedAgentsAlwaysAskPolicy object`
589538
590539 Tool calls require user confirmation before execution.
591540
from line 548
599548
600549 Permission policy for tool execution.
601550
602 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
551 - `BetaManagedAgentsAlwaysAllowPolicy object`
603552
604553 Tool calls are automatically approved without user confirmation.
605554
606 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
555 - `BetaManagedAgentsAlwaysAskPolicy object`
607556
608557 Tool calls require user confirmation before execution.
609558
from line 560
611560
612561 - `type: "mcp_toolset"`
613562
614 - `"mcp_toolset"`
563 - `BetaManagedAgentsCustomTool object`
615564
616 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
617
618565 A custom tool as returned in API responses.
619566
620567 - `description: string`
from line 572
625572
626573 - `type: "object"`
627574
628 - `"object"`
629
630575 - `properties: optional map[unknown] or null`
631576
632577 - `required: optional array of string or null`
from line 580
635580
636581 - `type: "custom"`
637582
638 - `"custom"`
639
640583 - `type: "agent"`
641584
642 - `"agent"`
643
644585 - `version: number`
645586
646 - `BetaManagedAgentsAdvisor object { model, type }`
587 format: int32
647588
589 - `BetaManagedAgentsAdvisor object`
590
648591 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
649592
650593 - `model: string`
from line 596
653596
654597 - `type: "advisor"`
655598
656 - `"advisor"`
657
658599 - `archived_at: string or null`
659600
660601 A timestamp in RFC 3339 format
661602
603 format: date-time
604
662605 - `created_at: string`
663606
664607 A timestamp in RFC 3339 format
665608
609 format: date-time
610
666611 - `parent_thread_id: string or null`
667612
668613 Parent thread that spawned this thread. Null for the primary thread.
from line 624
679624
680625 Cumulative time in seconds the thread spent actively running. Excludes idle time.
681626
627 format: double
628
682629 - `duration_seconds: optional number`
683630
684631 Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.
685632
633 format: double
634
686635 - `startup_seconds: optional number`
687636
688637 Time in seconds for the thread to begin running. Zero for child threads, which start immediately.
689638
639 format: double
640
690641 - `status: BetaManagedAgentsSessionThreadStatus`
691642
692643 SessionThreadStatus enum
from line 652
701652
702653 - `type: "session_thread"`
703654
704 - `"session_thread"`
705
706655 - `updated_at: string`
707656
708657 A timestamp in RFC 3339 format
709658
659 format: date-time
660
710661 - `usage: BetaManagedAgentsSessionThreadUsage or null`
711662
712663 Cumulative token usage for a session thread across all turns.
from line 666
715666
716667 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.
717668
669 format: double
670
718671 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
719672
720673 Prompt-cache creation token usage broken down by cache lifetime.
from line 676
723676
724677 Tokens used to create 1-hour ephemeral cache entries.
725678
679 format: int32
680
726681 - `ephemeral_5m_input_tokens: optional number`
727682
728683 Tokens used to create 5-minute ephemeral cache entries.
729684
685 format: int32
686
730687 - `cache_read_input_tokens: optional number`
731688
732689 Total tokens read from prompt cache.
733690
691 format: int32
692
734693 - `input_tokens: optional number`
735694
736695 Total input tokens consumed across all turns.
737696
697 format: int32
698
738699 - `list_cost: optional BetaMonetaryAmount or null`
739700
740701 A monetary amount in a specific currency.
from line 708
747708
748709 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.
749710
750 - `"USD"`
751
752711 - `output_tokens: optional number`
753712
754713 Total output tokens generated across all turns.
755714
715 format: int32
716
756717 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null`
757718
758719 Cumulative count of server-executed tool invocations, broken down by tool.
from line 722
761722
762723 Number of server-executed web fetch requests.
763724
725 format: int32
726
764727 - `web_search_requests: optional number`
765728
766729 Number of server-executed web search requests.
767730
731 format: int32
732
768733- `next_page: optional string or null`
769734
770735 Opaque cursor for the next page. Null when no more results.
771736
772### Example
737## Example
773738
774```http
739```bash
775740curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads \
776741 -H 'anthropic-version: 2023-06-01' \
777742 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 743
778743 -H "X-Api-Key: $ANTHROPIC_API_KEY"
779744```
780745
781#### Response
746### Response (200)
782747
783748```json
784749{
api/beta/sessions/threads/retrieve Changed · +92 / -129 lines
# Get Session Thread ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Session Thread ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Session Thread
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/retrieve
4---
1# Get Session Thread
52
6## Get Session Thread
3**GET** `/v1/sessions/{session_id}/threads/{thread_id}`
74
8**get** `/v1/sessions/{session_id}/threads/{thread_id}`
9
105Get Session Thread
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
1611- `thread_id: string`
1712
18### Header Parameters
13## Headers
1914
2015- `"anthropic-beta": optional array of AnthropicBeta`
2116
from line 88
9388
9489 - `"mid-conversation-tool-changes-2026-07-01"`
9590
96### Returns
91## Returns
9792
98- `BetaManagedAgentsSessionThread object { id, agent, archived_at, 8 more }`
93- `BetaManagedAgentsSessionThread object`
9994
10095 An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator.
10196
from line 102
107102
108103 A session-resolved multiagent roster entry.
109104
110 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
105 - `BetaManagedAgentsSessionThreadAgent object`
111106
112107 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`.
113108
from line 116
121116
122117 - `type: "url"`
123118
124 - `"url"`
125
126119 - `url: string`
127120
128121 - `model: BetaManagedAgentsModelConfig`
from line 192
199192
200193 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
201194
202 - `BetaManagedAgentsEffortLow object { type }`
195 - `BetaManagedAgentsEffortLow object`
203196
204197 Low effort. Favors latency over reasoning depth.
205198
206199 - `type: "low"`
207200
208 - `"low"`
201 - `BetaManagedAgentsEffortMedium object`
209202
210 - `BetaManagedAgentsEffortMedium object { type }`
211
212203 Medium effort. Balances latency and reasoning depth.
213204
214205 - `type: "medium"`
215206
216 - `"medium"`
207 - `BetaManagedAgentsEffortHigh object`
217208
218 - `BetaManagedAgentsEffortHigh object { type }`
219
220209 High effort. Favors reasoning depth.
221210
222211 - `type: "high"`
223212
224 - `"high"`
213 - `BetaManagedAgentsEffortXhigh object`
225214
226 - `BetaManagedAgentsEffortXhigh object { type }`
227
228215 Extra-high effort. Not all models accept this level.
229216
230217 - `type: "xhigh"`
231218
232 - `"xhigh"`
219 - `BetaManagedAgentsEffortMax object`
233220
234 - `BetaManagedAgentsEffortMax object { type }`
235
236221 Maximum effort. Favors reasoning depth over latency.
237222
238223 - `type: "max"`
239224
240 - `"max"`
241
242225 - `inference_geo: optional string`
243226
244227 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 238
255238
256239 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
257240
258 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
241 - `BetaManagedAgentsAnthropicSkill object`
259242
260243 A resolved Anthropic-managed skill.
261244
from line 246
263246
264247 - `type: "anthropic"`
265248
266 - `"anthropic"`
267
268249 - `version: string`
269250
270 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
251 - `BetaManagedAgentsCustomSkill object`
271252
272253 A resolved user-created custom skill.
273254
from line 256
275256
276257 - `type: "custom"`
277258
278 - `"custom"`
279
280259 - `version: string`
281260
282261 - `system: string or null`
from line 262
283262
284263 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
285264
286 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
265 - `BetaManagedAgentsAgentToolset20260401 object`
287266
288267 - `configs: array of BetaManagedAgentsAgentToolConfig`
289268
290 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
269 - `BetaManagedAgentsBashToolConfig object`
291270
292271 Configuration for the bash tool.
293272
from line 274
295274
296275 - `name: "bash"`
297276
298 - `"bash"`
299
300277 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
301278
302279 Permission policy for tool execution.
303280
304 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
281 - `BetaManagedAgentsAlwaysAllowPolicy object`
305282
306283 Tool calls are automatically approved without user confirmation.
307284
308285 - `type: "always_allow"`
309286
310 - `"always_allow"`
287 - `BetaManagedAgentsAlwaysAskPolicy object`
311288
312 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
313
314289 Tool calls require user confirmation before execution.
315290
316291 - `type: "always_ask"`
317292
318 - `"always_ask"`
319
320293 - `type: "bash"`
321294
322 - `"bash"`
295 - `BetaManagedAgentsEditToolConfig object`
323296
324 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
325
326297 Configuration for the edit tool.
327298
328299 - `enabled: boolean`
from line 300
329300
330301 - `name: "edit"`
331302
332 - `"edit"`
333
334303 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
335304
336305 Permission policy for tool execution.
337306
338 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
307 - `BetaManagedAgentsAlwaysAllowPolicy object`
339308
340309 Tool calls are automatically approved without user confirmation.
341310
342 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
311 - `BetaManagedAgentsAlwaysAskPolicy object`
343312
344313 Tool calls require user confirmation before execution.
345314
346315 - `type: "edit"`
347316
348 - `"edit"`
317 - `BetaManagedAgentsReadToolConfig object`
349318
350 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
351
352319 Configuration for the read tool.
353320
354321 - `enabled: boolean`
from line 322
355322
356323 - `name: "read"`
357324
358 - `"read"`
359
360325 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
361326
362327 Permission policy for tool execution.
363328
364 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
329 - `BetaManagedAgentsAlwaysAllowPolicy object`
365330
366331 Tool calls are automatically approved without user confirmation.
367332
368 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
333 - `BetaManagedAgentsAlwaysAskPolicy object`
369334
370335 Tool calls require user confirmation before execution.
371336
372337 - `type: "read"`
373338
374 - `"read"`
339 - `BetaManagedAgentsWriteToolConfig object`
375340
376 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
377
378341 Configuration for the write tool.
379342
380343 - `enabled: boolean`
from line 344
381344
382345 - `name: "write"`
383346
384 - `"write"`
385
386347 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
387348
388349 Permission policy for tool execution.
389350
390 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
351 - `BetaManagedAgentsAlwaysAllowPolicy object`
391352
392353 Tool calls are automatically approved without user confirmation.
393354
394 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
355 - `BetaManagedAgentsAlwaysAskPolicy object`
395356
396357 Tool calls require user confirmation before execution.
397358
398359 - `type: "write"`
399360
400 - `"write"`
361 - `BetaManagedAgentsGlobToolConfig object`
401362
402 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
403
404363 Configuration for the glob tool.
405364
406365 - `enabled: boolean`
from line 366
407366
408367 - `name: "glob"`
409368
410 - `"glob"`
411
412369 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
413370
414371 Permission policy for tool execution.
415372
416 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
373 - `BetaManagedAgentsAlwaysAllowPolicy object`
417374
418375 Tool calls are automatically approved without user confirmation.
419376
420 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
377 - `BetaManagedAgentsAlwaysAskPolicy object`
421378
422379 Tool calls require user confirmation before execution.
423380
424381 - `type: "glob"`
425382
426 - `"glob"`
383 - `BetaManagedAgentsGrepToolConfig object`
427384
428 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
429
430385 Configuration for the grep tool.
431386
432387 - `enabled: boolean`
from line 388
433388
434389 - `name: "grep"`
435390
436 - `"grep"`
437
438391 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
439392
440393 Permission policy for tool execution.
441394
442 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
395 - `BetaManagedAgentsAlwaysAllowPolicy object`
443396
444397 Tool calls are automatically approved without user confirmation.
445398
446 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
399 - `BetaManagedAgentsAlwaysAskPolicy object`
447400
448401 Tool calls require user confirmation before execution.
449402
450403 - `type: "grep"`
451404
452 - `"grep"`
405 - `BetaManagedAgentsWebFetchToolConfig object`
453406
454 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
455
456407 Configuration for the web_fetch tool.
457408
458409 - `enabled: boolean`
from line 410
459410
460411 - `name: "web_fetch"`
461412
462 - `"web_fetch"`
463
464413 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
465414
466415 Permission policy for tool execution.
467416
468 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
417 - `BetaManagedAgentsAlwaysAllowPolicy object`
469418
470419 Tool calls are automatically approved without user confirmation.
471420
472 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
421 - `BetaManagedAgentsAlwaysAskPolicy object`
473422
474423 Tool calls require user confirmation before execution.
475424
476425 - `type: "web_fetch"`
477426
478 - `"web_fetch"`
479
480427 - `allowed_domains: optional array of string`
481428
482429 - `blocked_domains: optional array of string`
from line 430
483430
484431 - `max_content_tokens: optional number or null`
485432
486 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
433 format: int32
487434
435 - `BetaManagedAgentsWebSearchToolConfig object`
436
488437 Configuration for the web_search tool.
489438
490439 - `enabled: boolean`
from line 440
491440
492441 - `name: "web_search"`
493442
494 - `"web_search"`
495
496443 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
497444
498445 Permission policy for tool execution.
499446
500 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
447 - `BetaManagedAgentsAlwaysAllowPolicy object`
501448
502449 Tool calls are automatically approved without user confirmation.
503450
504 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
451 - `BetaManagedAgentsAlwaysAskPolicy object`
505452
506453 Tool calls require user confirmation before execution.
507454
508455 - `type: "web_search"`
509456
510 - `"web_search"`
511
512457 - `allowed_domains: optional array of string`
513458
514459 - `blocked_domains: optional array of string`
from line 466
521466
522467 Location precision. Only "approximate" is supported.
523468
524 - `"approximate"`
525
526469 - `city: optional string or null`
527470
528471 City name.
529472
473 minLength: 1, maxLength: 255
474
530475 - `country: optional string or null`
531476
532477 Two-letter ISO 3166-1 country code, uppercase.
from line 480
535480
536481 Region or state name.
537482
483 minLength: 1, maxLength: 255
484
538485 - `timezone: optional string or null`
539486
540487 IANA timezone identifier, e.g. "America/Los_Angeles".
541488
489 minLength: 1, maxLength: 255
490
542491 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
543492
544493 Resolved default configuration for agent tools.
from line 498
549498
550499 Permission policy for tool execution.
551500
552 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
501 - `BetaManagedAgentsAlwaysAllowPolicy object`
553502
554503 Tool calls are automatically approved without user confirmation.
555504
556 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
505 - `BetaManagedAgentsAlwaysAskPolicy object`
557506
558507 Tool calls require user confirmation before execution.
559508
560509 - `type: "agent_toolset_20260401"`
561510
562 - `"agent_toolset_20260401"`
511 - `BetaManagedAgentsMCPToolset object`
563512
564 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
565
566513 - `configs: array of BetaManagedAgentsMCPToolConfig`
567514
568515 - `enabled: boolean`
from line 520
573520
574521 Permission policy for tool execution.
575522
576 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
523 - `BetaManagedAgentsAlwaysAllowPolicy object`
577524
578525 Tool calls are automatically approved without user confirmation.
579526
580 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
527 - `BetaManagedAgentsAlwaysAskPolicy object`
581528
582529 Tool calls require user confirmation before execution.
583530
from line 538
591538
592539 Permission policy for tool execution.
593540
594 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
541 - `BetaManagedAgentsAlwaysAllowPolicy object`
595542
596543 Tool calls are automatically approved without user confirmation.
597544
598 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
545 - `BetaManagedAgentsAlwaysAskPolicy object`
599546
600547 Tool calls require user confirmation before execution.
601548
from line 550
603550
604551 - `type: "mcp_toolset"`
605552
606 - `"mcp_toolset"`
553 - `BetaManagedAgentsCustomTool object`
607554
608 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
609
610555 A custom tool as returned in API responses.
611556
612557 - `description: string`
from line 562
617562
618563 - `type: "object"`
619564
620 - `"object"`
621
622565 - `properties: optional map[unknown] or null`
623566
624567 - `required: optional array of string or null`
from line 570
627570
628571 - `type: "custom"`
629572
630 - `"custom"`
631
632573 - `type: "agent"`
633574
634 - `"agent"`
635
636575 - `version: number`
637576
638 - `BetaManagedAgentsAdvisor object { model, type }`
577 format: int32
639578
579 - `BetaManagedAgentsAdvisor object`
580
640581 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
641582
642583 - `model: string`
from line 586
645586
646587 - `type: "advisor"`
647588
648 - `"advisor"`
649
650589 - `archived_at: string or null`
651590
652591 A timestamp in RFC 3339 format
653592
593 format: date-time
594
654595 - `created_at: string`
655596
656597 A timestamp in RFC 3339 format
657598
599 format: date-time
600
658601 - `parent_thread_id: string or null`
659602
660603 Parent thread that spawned this thread. Null for the primary thread.
from line 614
671614
672615 Cumulative time in seconds the thread spent actively running. Excludes idle time.
673616
617 format: double
618
674619 - `duration_seconds: optional number`
675620
676621 Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.
677622
623 format: double
624
678625 - `startup_seconds: optional number`
679626
680627 Time in seconds for the thread to begin running. Zero for child threads, which start immediately.
681628
629 format: double
630
682631 - `status: BetaManagedAgentsSessionThreadStatus`
683632
684633 SessionThreadStatus enum
from line 642
693642
694643 - `type: "session_thread"`
695644
696 - `"session_thread"`
697
698645 - `updated_at: string`
699646
700647 A timestamp in RFC 3339 format
701648
649 format: date-time
650
702651 - `usage: BetaManagedAgentsSessionThreadUsage or null`
703652
704653 Cumulative token usage for a session thread across all turns.
from line 656
707656
708657 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.
709658
659 format: double
660
710661 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
711662
712663 Prompt-cache creation token usage broken down by cache lifetime.
from line 666
715666
716667 Tokens used to create 1-hour ephemeral cache entries.
717668
669 format: int32
670
718671 - `ephemeral_5m_input_tokens: optional number`
719672
720673 Tokens used to create 5-minute ephemeral cache entries.
721674
675 format: int32
676
722677 - `cache_read_input_tokens: optional number`
723678
724679 Total tokens read from prompt cache.
725680
681 format: int32
682
726683 - `input_tokens: optional number`
727684
728685 Total input tokens consumed across all turns.
729686
687 format: int32
688
730689 - `list_cost: optional BetaMonetaryAmount or null`
731690
732691 A monetary amount in a specific currency.
from line 698
739698
740699 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.
741700
742 - `"USD"`
743
744701 - `output_tokens: optional number`
745702
746703 Total output tokens generated across all turns.
747704
705 format: int32
706
748707 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null`
749708
750709 Cumulative count of server-executed tool invocations, broken down by tool.
from line 712
753712
754713 Number of server-executed web fetch requests.
755714
715 format: int32
716
756717 - `web_search_requests: optional number`
757718
758719 Number of server-executed web search requests.
759720
760### Example
721 format: int32
761722
762```http
723## Example
724
725```bash
763726curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID \
764727 -H 'anthropic-version: 2023-06-01' \
765728 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 729
766729 -H "X-Api-Key: $ANTHROPIC_API_KEY"
767730```
768731
769#### Response
732### Response (200)
770733
771734```json
772735{
api/beta/sessions/update Changed · +178 / -245 lines
# Update Session ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Update Session ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Update Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/update
4---
5
6## Update Session
7
8**post** `/v1/sessions/{session_id}`
1# Update Session
2
3**POST** `/v1/sessions/{session_id}`
94
105Update Session
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Body Parameters
89## Body parameters
9590
9691- `agent: optional BetaManagedAgentsSessionAgentUpdate`
9792
from line 100
105100
106101 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
107102
103 minLength: 1, maxLength: 255
104
108105 - `type: "url"`
109106
110 - `"url"`
111
112107 - `url: string`
113108
114109 Endpoint URL for the MCP server.
115110
111 maxLength: 2048
112
116113 - `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams`
117114
118115 Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.
119116
120 - `BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }`
117 - `BetaManagedAgentsAgentToolset20260401Params object`
121118
122119 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
123120
124121 - `type: "agent_toolset_20260401"`
125122
126 - `"agent_toolset_20260401"`
127
128123 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`
129124
130125 Per-tool configuration overrides.
131126
132 - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
127 - `BetaManagedAgentsBashToolConfigParams object`
133128
134129 Configuration override for the bash tool.
135130
from line 132
137132
138133 Must be "bash".
139134
140 - `"bash"`
141
142135 - `enabled: optional boolean or null`
143136
144137 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 140
147140
148141 Permission policy for tool execution.
149142
150 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
143 - `BetaManagedAgentsAlwaysAllowPolicy object`
151144
152145 Tool calls are automatically approved without user confirmation.
153146
154147 - `type: "always_allow"`
155148
156 - `"always_allow"`
157
158 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
149 - `BetaManagedAgentsAlwaysAskPolicy object`
159150
160151 Tool calls require user confirmation before execution.
161152
162153 - `type: "always_ask"`
163154
164 - `"always_ask"`
165
166155 - `type: optional "bash"`
167156
168 - `"bash"`
169
170 - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
157 - `BetaManagedAgentsEditToolConfigParams object`
171158
172159 Configuration override for the edit tool.
173160
from line 162
175162
176163 Must be "edit".
177164
178 - `"edit"`
179
180165 - `enabled: optional boolean or null`
181166
182167 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 170
185170
186171 Permission policy for tool execution.
187172
188 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
173 - `BetaManagedAgentsAlwaysAllowPolicy object`
189174
190175 Tool calls are automatically approved without user confirmation.
191176
192 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
177 - `BetaManagedAgentsAlwaysAskPolicy object`
193178
194179 Tool calls require user confirmation before execution.
195180
196181 - `type: optional "edit"`
197182
198 - `"edit"`
199
200 - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
183 - `BetaManagedAgentsReadToolConfigParams object`
201184
202185 Configuration override for the read tool.
203186
from line 188
205188
206189 Must be "read".
207190
208 - `"read"`
209
210191 - `enabled: optional boolean or null`
211192
212193 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 196
215196
216197 Permission policy for tool execution.
217198
218 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
199 - `BetaManagedAgentsAlwaysAllowPolicy object`
219200
220201 Tool calls are automatically approved without user confirmation.
221202
222 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
203 - `BetaManagedAgentsAlwaysAskPolicy object`
223204
224205 Tool calls require user confirmation before execution.
225206
226207 - `type: optional "read"`
227208
228 - `"read"`
229
230 - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
209 - `BetaManagedAgentsWriteToolConfigParams object`
231210
232211 Configuration override for the write tool.
233212
from line 214
235214
236215 Must be "write".
237216
238 - `"write"`
239
240217 - `enabled: optional boolean or null`
241218
242219 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 222
245222
246223 Permission policy for tool execution.
247224
248 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
225 - `BetaManagedAgentsAlwaysAllowPolicy object`
249226
250227 Tool calls are automatically approved without user confirmation.
251228
252 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
229 - `BetaManagedAgentsAlwaysAskPolicy object`
253230
254231 Tool calls require user confirmation before execution.
255232
256233 - `type: optional "write"`
257234
258 - `"write"`
259
260 - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
235 - `BetaManagedAgentsGlobToolConfigParams object`
261236
262237 Configuration override for the glob tool.
263238
from line 240
265240
266241 Must be "glob".
267242
268 - `"glob"`
269
270243 - `enabled: optional boolean or null`
271244
272245 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 248
275248
276249 Permission policy for tool execution.
277250
278 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
251 - `BetaManagedAgentsAlwaysAllowPolicy object`
279252
280253 Tool calls are automatically approved without user confirmation.
281254
282 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
255 - `BetaManagedAgentsAlwaysAskPolicy object`
283256
284257 Tool calls require user confirmation before execution.
285258
286259 - `type: optional "glob"`
287260
288 - `"glob"`
289
290 - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
261 - `BetaManagedAgentsGrepToolConfigParams object`
291262
292263 Configuration override for the grep tool.
293264
from line 266
295266
296267 Must be "grep".
297268
298 - `"grep"`
299
300269 - `enabled: optional boolean or null`
301270
302271 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 274
305274
306275 Permission policy for tool execution.
307276
308 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
277 - `BetaManagedAgentsAlwaysAllowPolicy object`
309278
310279 Tool calls are automatically approved without user confirmation.
311280
312 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
281 - `BetaManagedAgentsAlwaysAskPolicy object`
313282
314283 Tool calls require user confirmation before execution.
315284
316285 - `type: optional "grep"`
317286
318 - `"grep"`
319
320 - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
287 - `BetaManagedAgentsWebFetchToolConfigParams object`
321288
322289 Configuration override for the web_fetch tool.
323290
from line 292
325292
326293 Must be "web_fetch".
327294
328 - `"web_fetch"`
329
330295 - `allowed_domains: optional array of string`
331296
332297 Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 308
343308
344309 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
345310
311 format: int32
312
346313 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
347314
348315 Permission policy for tool execution.
349316
350 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
317 - `BetaManagedAgentsAlwaysAllowPolicy object`
351318
352319 Tool calls are automatically approved without user confirmation.
353320
354 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
321 - `BetaManagedAgentsAlwaysAskPolicy object`
355322
356323 Tool calls require user confirmation before execution.
357324
358325 - `type: optional "web_fetch"`
359326
360 - `"web_fetch"`
361
362 - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
327 - `BetaManagedAgentsWebSearchToolConfigParams object`
363328
364329 Configuration override for the web_search tool.
365330
from line 332
367332
368333 Must be "web_search".
369334
370 - `"web_search"`
371
372335 - `allowed_domains: optional array of string`
373336
374337 Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 348
385348
386349 Permission policy for tool execution.
387350
388 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
351 - `BetaManagedAgentsAlwaysAllowPolicy object`
389352
390353 Tool calls are automatically approved without user confirmation.
391354
392 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
355 - `BetaManagedAgentsAlwaysAskPolicy object`
393356
394357 Tool calls require user confirmation before execution.
395358
396359 - `type: optional "web_search"`
397360
398 - `"web_search"`
399
400361 - `user_location: optional BetaManagedAgentsUserLocation or null`
401362
402363 Approximate user location for search result localization.
from line 366
405366
406367 Location precision. Only "approximate" is supported.
407368
408 - `"approximate"`
409
410369 - `city: optional string or null`
411370
412371 City name.
413372
373 minLength: 1, maxLength: 255
374
414375 - `country: optional string or null`
415376
416377 Two-letter ISO 3166-1 country code, uppercase.
from line 380
419380
420381 Region or state name.
421382
383 minLength: 1, maxLength: 255
384
422385 - `timezone: optional string or null`
423386
424387 IANA timezone identifier, e.g. "America/Los_Angeles".
425388
389 minLength: 1, maxLength: 255
390
426391 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`
427392
428393 Default configuration for all tools in a toolset.
from line 400
435400
436401 Permission policy for tool execution.
437402
438 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
403 - `BetaManagedAgentsAlwaysAllowPolicy object`
439404
440405 Tool calls are automatically approved without user confirmation.
441406
442 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
407 - `BetaManagedAgentsAlwaysAskPolicy object`
443408
444409 Tool calls require user confirmation before execution.
445410
446 - `BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }`
411 - `BetaManagedAgentsMCPToolsetParams object`
447412
448413 Configuration for tools from an MCP server defined in `mcp_servers`.
449414
from line 416
451416
452417 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
453418
419 minLength: 1, maxLength: 255
420
454421 - `type: "mcp_toolset"`
455422
456 - `"mcp_toolset"`
457
458423 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
459424
460425 Per-tool configuration overrides.
from line 428
463428
464429 Name of the MCP tool to configure. 1-128 characters.
465430
431 minLength: 1, maxLength: 128
432
466433 - `enabled: optional boolean or null`
467434
468435 Whether this tool is enabled. Overrides the `default_config` setting.
from line 438
471438
472439 Permission policy for tool execution.
473440
474 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
441 - `BetaManagedAgentsAlwaysAllowPolicy object`
475442
476443 Tool calls are automatically approved without user confirmation.
477444
478 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
445 - `BetaManagedAgentsAlwaysAskPolicy object`
479446
480447 Tool calls require user confirmation before execution.
481448
from line 458
491458
492459 Permission policy for tool execution.
493460
494 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
461 - `BetaManagedAgentsAlwaysAllowPolicy object`
495462
496463 Tool calls are automatically approved without user confirmation.
497464
498 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
465 - `BetaManagedAgentsAlwaysAskPolicy object`
499466
500467 Tool calls require user confirmation before execution.
501468
502 - `BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }`
469 - `BetaManagedAgentsCustomToolParams object`
503470
504471 A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.
505472
from line 474
507474
508475 Description of what the tool does, shown to the agent to help it decide when to use the tool.
509476
477 minLength: 1
478
510479 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
511480
512481 JSON Schema for custom tool input parameters.
513482
514483 - `type: "object"`
515484
516 - `"object"`
517
518485 - `properties: optional map[unknown] or null`
519486
520487 - `required: optional array of string or null`
from line 490
523490
524491 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
525492
493 minLength: 1, maxLength: 128
494
526495 - `type: "custom"`
527496
528 - `"custom"`
529
530497- `budget: optional BetaManagedAgentsBudgetLimit or null`
531498
532499 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 510
543510
544511 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.
545512
546 - `"USD"`
547
548513 - `type: "limit"`
549514
550 - `"limit"`
551
552515- `metadata: optional map[string] or null`
553516
554517 Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.
from line 520
557520
558521 Human-readable session title.
559522
523 minLength: 1, maxLength: 500
524
560525- `vault_ids: optional array of string`
561526
562527 Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.
563528
564### Returns
565
566- `BetaManagedAgentsSession object { id, agent, archived_at, 14 more }`
529## Returns
530
531- `BetaManagedAgentsSession object`
567532
568533 A Managed Agents `session`.
569534
from line 548
583548
584549 - `type: "url"`
585550
586 - `"url"`
587
588551 - `url: string`
589552
590553 - `model: BetaManagedAgentsModelConfig`
from line 624
661624
662625 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
663626
664 - `BetaManagedAgentsEffortLow object { type }`
627 - `BetaManagedAgentsEffortLow object`
665628
666629 Low effort. Favors latency over reasoning depth.
667630
668631 - `type: "low"`
669632
670 - `"low"`
671
672 - `BetaManagedAgentsEffortMedium object { type }`
633 - `BetaManagedAgentsEffortMedium object`
673634
674635 Medium effort. Balances latency and reasoning depth.
675636
676637 - `type: "medium"`
677638
678 - `"medium"`
679
680 - `BetaManagedAgentsEffortHigh object { type }`
639 - `BetaManagedAgentsEffortHigh object`
681640
682641 High effort. Favors reasoning depth.
683642
684643 - `type: "high"`
685644
686 - `"high"`
687
688 - `BetaManagedAgentsEffortXhigh object { type }`
645 - `BetaManagedAgentsEffortXhigh object`
689646
690647 Extra-high effort. Not all models accept this level.
691648
692649 - `type: "xhigh"`
693650
694 - `"xhigh"`
695
696 - `BetaManagedAgentsEffortMax object { type }`
651 - `BetaManagedAgentsEffortMax object`
697652
698653 Maximum effort. Favors reasoning depth over latency.
699654
700655 - `type: "max"`
701656
702 - `"max"`
703
704657 - `inference_geo: optional string`
705658
706659 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 674
721674
722675 Full `agent` definitions the coordinator may spawn as session threads.
723676
724 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
677 - `BetaManagedAgentsSessionThreadAgent object`
725678
726679 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`.
727680
from line 698
745698
746699 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
747700
748 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
701 - `BetaManagedAgentsAnthropicSkill object`
749702
750703 A resolved Anthropic-managed skill.
751704
from line 706
753706
754707 - `type: "anthropic"`
755708
756 - `"anthropic"`
757
758709 - `version: string`
759710
760 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
711 - `BetaManagedAgentsCustomSkill object`
761712
762713 A resolved user-created custom skill.
763714
from line 716
765716
766717 - `type: "custom"`
767718
768 - `"custom"`
769
770719 - `version: string`
771720
772721 - `system: string or null`
773722
774723 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
775724
776 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
725 - `BetaManagedAgentsAgentToolset20260401 object`
777726
778727 - `configs: array of BetaManagedAgentsAgentToolConfig`
779728
780 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
729 - `BetaManagedAgentsBashToolConfig object`
781730
782731 Configuration for the bash tool.
783732
from line 734
785734
786735 - `name: "bash"`
787736
788 - `"bash"`
789
790737 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
791738
792739 Permission policy for tool execution.
793740
794 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
741 - `BetaManagedAgentsAlwaysAllowPolicy object`
795742
796743 Tool calls are automatically approved without user confirmation.
797744
798745 - `type: "always_allow"`
799746
800 - `"always_allow"`
801
802 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
747 - `BetaManagedAgentsAlwaysAskPolicy object`
803748
804749 Tool calls require user confirmation before execution.
805750
806751 - `type: "always_ask"`
807752
808 - `"always_ask"`
809
810753 - `type: "bash"`
811754
812 - `"bash"`
813
814 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
755 - `BetaManagedAgentsEditToolConfig object`
815756
816757 Configuration for the edit tool.
817758
from line 760
819760
820761 - `name: "edit"`
821762
822 - `"edit"`
823
824763 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
825764
826765 Permission policy for tool execution.
827766
828 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
767 - `BetaManagedAgentsAlwaysAllowPolicy object`
829768
830769 Tool calls are automatically approved without user confirmation.
831770
832 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
771 - `BetaManagedAgentsAlwaysAskPolicy object`
833772
834773 Tool calls require user confirmation before execution.
835774
836775 - `type: "edit"`
837776
838 - `"edit"`
839
840 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
777 - `BetaManagedAgentsReadToolConfig object`
841778
842779 Configuration for the read tool.
843780
from line 782
845782
846783 - `name: "read"`
847784
848 - `"read"`
849
850785 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
851786
852787 Permission policy for tool execution.
853788
854 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
789 - `BetaManagedAgentsAlwaysAllowPolicy object`
855790
856791 Tool calls are automatically approved without user confirmation.
857792
858 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
793 - `BetaManagedAgentsAlwaysAskPolicy object`
859794
860795 Tool calls require user confirmation before execution.
861796
862797 - `type: "read"`
863798
864 - `"read"`
865
866 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
799 - `BetaManagedAgentsWriteToolConfig object`
867800
868801 Configuration for the write tool.
869802
from line 804
871804
872805 - `name: "write"`
873806
874 - `"write"`
875
876807 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
877808
878809 Permission policy for tool execution.
879810
880 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
811 - `BetaManagedAgentsAlwaysAllowPolicy object`
881812
882813 Tool calls are automatically approved without user confirmation.
883814
884 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
815 - `BetaManagedAgentsAlwaysAskPolicy object`
885816
886817 Tool calls require user confirmation before execution.
887818
888819 - `type: "write"`
889820
890 - `"write"`
891
892 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
821 - `BetaManagedAgentsGlobToolConfig object`
893822
894823 Configuration for the glob tool.
895824
from line 826
897826
898827 - `name: "glob"`
899828
900 - `"glob"`
901
902829 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
903830
904831 Permission policy for tool execution.
905832
906 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
833 - `BetaManagedAgentsAlwaysAllowPolicy object`
907834
908835 Tool calls are automatically approved without user confirmation.
909836
910 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
837 - `BetaManagedAgentsAlwaysAskPolicy object`
911838
912839 Tool calls require user confirmation before execution.
913840
914841 - `type: "glob"`
915842
916 - `"glob"`
917
918 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
843 - `BetaManagedAgentsGrepToolConfig object`
919844
920845 Configuration for the grep tool.
921846
from line 848
923848
924849 - `name: "grep"`
925850
926 - `"grep"`
927
928851 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
929852
930853 Permission policy for tool execution.
931854
932 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
855 - `BetaManagedAgentsAlwaysAllowPolicy object`
933856
934857 Tool calls are automatically approved without user confirmation.
935858
936 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
859 - `BetaManagedAgentsAlwaysAskPolicy object`
937860
938861 Tool calls require user confirmation before execution.
939862
940863 - `type: "grep"`
941864
942 - `"grep"`
943
944 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
865 - `BetaManagedAgentsWebFetchToolConfig object`
945866
946867 Configuration for the web_fetch tool.
947868
from line 870
949870
950871 - `name: "web_fetch"`
951872
952 - `"web_fetch"`
953
954873 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
955874
956875 Permission policy for tool execution.
957876
958 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
877 - `BetaManagedAgentsAlwaysAllowPolicy object`
959878
960879 Tool calls are automatically approved without user confirmation.
961880
962 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
881 - `BetaManagedAgentsAlwaysAskPolicy object`
963882
964883 Tool calls require user confirmation before execution.
965884
966885 - `type: "web_fetch"`
967886
968 - `"web_fetch"`
969
970887 - `allowed_domains: optional array of string`
971888
972889 - `blocked_domains: optional array of string`
973890
974891 - `max_content_tokens: optional number or null`
975892
976 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
893 format: int32
894
895 - `BetaManagedAgentsWebSearchToolConfig object`
977896
978897 Configuration for the web_search tool.
979898
from line 900
981900
982901 - `name: "web_search"`
983902
984 - `"web_search"`
985
986903 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
987904
988905 Permission policy for tool execution.
989906
990 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
907 - `BetaManagedAgentsAlwaysAllowPolicy object`
991908
992909 Tool calls are automatically approved without user confirmation.
993910
994 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
911 - `BetaManagedAgentsAlwaysAskPolicy object`
995912
996913 Tool calls require user confirmation before execution.
997914
998915 - `type: "web_search"`
999916
1000 - `"web_search"`
1001
1002917 - `allowed_domains: optional array of string`
1003918
1004919 - `blocked_domains: optional array of string`
from line 926
1011926
1012927 Location precision. Only "approximate" is supported.
1013928
1014 - `"approximate"`
1015
1016929 - `city: optional string or null`
1017930
1018931 City name.
1019932
933 minLength: 1, maxLength: 255
934
1020935 - `country: optional string or null`
1021936
1022937 Two-letter ISO 3166-1 country code, uppercase.
from line 940
1025940
1026941 Region or state name.
1027942
943 minLength: 1, maxLength: 255
944
1028945 - `timezone: optional string or null`
1029946
1030947 IANA timezone identifier, e.g. "America/Los_Angeles".
1031948
949 minLength: 1, maxLength: 255
950
1032951 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
1033952
1034953 Resolved default configuration for agent tools.
from line 958
1039958
1040959 Permission policy for tool execution.
1041960
1042 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
961 - `BetaManagedAgentsAlwaysAllowPolicy object`
1043962
1044963 Tool calls are automatically approved without user confirmation.
1045964
1046 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
965 - `BetaManagedAgentsAlwaysAskPolicy object`
1047966
1048967 Tool calls require user confirmation before execution.
1049968
1050969 - `type: "agent_toolset_20260401"`
1051970
1052 - `"agent_toolset_20260401"`
1053
1054 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
971 - `BetaManagedAgentsMCPToolset object`
1055972
1056973 - `configs: array of BetaManagedAgentsMCPToolConfig`
1057974
from line 980
1063980
1064981 Permission policy for tool execution.
1065982
1066 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
983 - `BetaManagedAgentsAlwaysAllowPolicy object`
1067984
1068985 Tool calls are automatically approved without user confirmation.
1069986
1070 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
987 - `BetaManagedAgentsAlwaysAskPolicy object`
1071988
1072989 Tool calls require user confirmation before execution.
1073990
from line 998
1081998
1082999 Permission policy for tool execution.
10831000
1084 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1001 - `BetaManagedAgentsAlwaysAllowPolicy object`
10851002
10861003 Tool calls are automatically approved without user confirmation.
10871004
1088 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1005 - `BetaManagedAgentsAlwaysAskPolicy object`
10891006
10901007 Tool calls require user confirmation before execution.
10911008
from line 1010
10931010
10941011 - `type: "mcp_toolset"`
10951012
1096 - `"mcp_toolset"`
1097
1098 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1013 - `BetaManagedAgentsCustomTool object`
10991014
11001015 A custom tool as returned in API responses.
11011016
from line 1022
11071022
11081023 - `type: "object"`
11091024
1110 - `"object"`
1111
11121025 - `properties: optional map[unknown] or null`
11131026
11141027 - `required: optional array of string or null`
from line 1030
11171030
11181031 - `type: "custom"`
11191032
1120 - `"custom"`
1121
11221033 - `type: "agent"`
11231034
1124 - `"agent"`
1125
11261035 - `version: number`
11271036
1128 - `BetaManagedAgentsAdvisor object { model, type }`
1037 format: int32
1038
1039 - `BetaManagedAgentsAdvisor object`
11291040
11301041 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
11311042
from line 1046
11351046
11361047 - `type: "advisor"`
11371048
1138 - `"advisor"`
1139
11401049 - `type: "coordinator"`
11411050
1142 - `"coordinator"`
1143
11441051 - `name: string`
11451052
11461053 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
11471054
1148 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1055 - `BetaManagedAgentsAnthropicSkill object`
11491056
11501057 A resolved Anthropic-managed skill.
11511058
1152 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1059 - `BetaManagedAgentsCustomSkill object`
11531060
11541061 A resolved user-created custom skill.
11551062
from line 1064
11571064
11581065 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
11591066
1160 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1161
1162 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1163
1164 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1067 - `BetaManagedAgentsAgentToolset20260401 object`
1068
1069 - `BetaManagedAgentsMCPToolset object`
1070
1071 - `BetaManagedAgentsCustomTool object`
11651072
11661073 A custom tool as returned in API responses.
11671074
11681075 - `type: "agent"`
11691076
1170 - `"agent"`
1171
11721077 - `version: number`
11731078
1079 format: int32
1080
11741081 - `archived_at: string or null`
11751082
11761083 A timestamp in RFC 3339 format
11771084
1085 format: date-time
1086
11781087 - `budget: BetaManagedAgentsBudgetLimit or null`
11791088
11801089 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 1100
11911100
11921101 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.
11931102
1194 - `"USD"`
1195
11961103 - `type: "limit"`
11971104
1198 - `"limit"`
1199
12001105 - `created_at: string`
12011106
12021107 A timestamp in RFC 3339 format
12031108
1109 format: date-time
1110
12041111 - `environment_id: string`
12051112
12061113 - `metadata: map[string]`
from line 1120
12131120
12141121 A timestamp in RFC 3339 format
12151122
1123 format: date-time
1124
12161125 - `description: string`
12171126
12181127 What the agent should produce.
from line 1134
12251134
12261135 0-indexed revision cycle the outcome is currently on.
12271136
1137 format: int32
1138
12281139 - `outcome_id: string`
12291140
12301141 Server-generated outc_ ID for this outcome.
from line 1146
12351146
12361147 - `type: "outcome_evaluation"`
12371148
1238 - `"outcome_evaluation"`
1239
12401149 - `resources: array of BetaManagedAgentsSessionResource`
12411150
1242 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
1151 - `BetaManagedAgentsGitHubRepositoryResource object`
12431152
12441153 - `id: string`
12451154
from line 1156
12471156
12481157 A timestamp in RFC 3339 format
12491158
1159 format: date-time
1160
12501161 - `mount_path: string`
12511162
12521163 - `type: "github_repository"`
12531164
1254 - `"github_repository"`
1255
12561165 - `updated_at: string`
12571166
12581167 A timestamp in RFC 3339 format
12591168
1169 format: date-time
1170
12601171 - `url: string`
12611172
12621173 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
12631174
1264 - `BetaManagedAgentsBranchCheckout object { name, type }`
1175 - `BetaManagedAgentsBranchCheckout object`
12651176
12661177 - `name: string`
12671178
12681179 Branch name to check out.
12691180
1181 minLength: 1, maxLength: 255
1182
12701183 - `type: "branch"`
12711184
1272 - `"branch"`
1273
1274 - `BetaManagedAgentsCommitCheckout object { sha, type }`
1185 - `BetaManagedAgentsCommitCheckout object`
12751186
12761187 - `sha: string`
12771188
12781189 Full commit SHA to check out.
12791190
1191 minLength: 7, maxLength: 64
1192
12801193 - `type: "commit"`
12811194
1282 - `"commit"`
1283
1284 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
1195 - `BetaManagedAgentsFileResource object`
12851196
12861197 - `id: string`
12871198
from line 1200
12891200
12901201 A timestamp in RFC 3339 format
12911202
1203 format: date-time
1204
12921205 - `file_id: string`
12931206
12941207 - `mount_path: string`
12951208
12961209 - `type: "file"`
12971210
1298 - `"file"`
1299
13001211 - `updated_at: string`
13011212
13021213 A timestamp in RFC 3339 format
13031214
1304 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
1215 format: date-time
1216
1217 - `BetaManagedAgentsMemoryStoreResource object`
13051218
13061219 A memory store attached to an agent session.
13071220
from line 1224
13111224
13121225 - `type: "memory_store"`
13131226
1314 - `"memory_store"`
1315
13161227 - `access: optional "read_write" or "read_only" or null`
13171228
13181229 Access mode for an attached memory store.
from line 1240
13291240
13301241 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
13311242
1243 maxLength: 4096
1244
13321245 - `mount_path: optional string or null`
13331246
13341247 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 1258
13451258
13461259 Cumulative time in seconds the session spent in running status. Excludes idle time.
13471260
1261 format: double
1262
13481263 - `duration_seconds: optional number`
13491264
13501265 Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
13511266
1267 format: double
1268
13521269 - `status: "rescheduling" or "running" or "idle" or "terminated"`
13531270
13541271 SessionStatus enum
from line 1282
13651282
13661283 - `type: "session"`
13671284
1368 - `"session"`
1369
13701285 - `updated_at: string`
13711286
13721287 A timestamp in RFC 3339 format
13731288
1289 format: date-time
1290
13741291 - `usage: BetaManagedAgentsSessionUsage`
13751292
13761293 Cumulative token usage for a session across all turns.
from line 1296
13791296
13801297 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.
13811298
1299 format: double
1300
13821301 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
13831302
13841303 Prompt-cache creation token usage broken down by cache lifetime.
from line 1306
13871306
13881307 Tokens used to create 1-hour ephemeral cache entries.
13891308
1309 format: int32
1310
13901311 - `ephemeral_5m_input_tokens: optional number`
13911312
13921313 Tokens used to create 5-minute ephemeral cache entries.
13931314
1315 format: int32
1316
13941317 - `cache_read_input_tokens: optional number`
13951318
13961319 Total tokens read from prompt cache.
13971320
1321 format: int32
1322
13981323 - `input_tokens: optional number`
13991324
14001325 Total input tokens consumed across all turns.
14011326
1327 format: int32
1328
14021329 - `list_cost: optional BetaMonetaryAmount or null`
14031330
14041331 A monetary amount in a specific currency.
from line 1334
14071334
14081335 Total output tokens generated across all turns.
14091336
1337 format: int32
1338
14101339 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null`
14111340
14121341 Cumulative count of server-executed tool invocations, broken down by tool.
from line 1344
14151344
14161345 Number of server-executed web fetch requests.
14171346
1347 format: int32
1348
14181349 - `web_search_requests: optional number`
14191350
14201351 Number of server-executed web search requests.
14211352
1353 format: int32
1354
14221355 - `vault_ids: array of string`
14231356
14241357 Vault IDs attached to the session at creation. Empty when no vaults were supplied.
from line 1360
14271360
14281361 Deployment ID when the session was created from a deployment reference. Null otherwise.
14291362
1430### Example
1431
1432```http
1363## Example
1364
1365```bash
14331366curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
14341367 -H 'Content-Type: application/json' \
14351368 -H 'anthropic-version: 2023-06-01' \
from line 1373
14401373 }'
14411374```
14421375
1443#### Response
1376### Response (200)
14441377
14451378```json
14461379{
14471380
api/beta/skills Changed · +126 / -245 lines
### Headers ### Body parameters (form-data) #### Response (200) ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ## Skills › Versions ### Create Skill Version #### Path parameters #### Headers #### Body parameters (form-data) #### Returns #### Example ##### Response (200) ### List Skill Versions #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Download Skill Version Content #### Path parameters #### Headers #### Example ### Get Skill Version #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Delete Skill Version #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Header Parameters #### Response ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types # Versions ## Create Skill Version ### Path Parameters ### Header Parameters #### Response ## List Skill Versions ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Download Skill Version Content ### Path Parameters ### Header Parameters ## Get Skill Version ### Path Parameters ### Header Parameters #### Response ## Delete Skill Version ### Path Parameters ### Header Parameters #### Response ## Domain Types ### Version Create Response ### Version List Response ### Version Retrieve Response ### Version Delete Response
from line 1
1---
2title: Skills
3url: https://platform.claude.com/docs/en/api/beta/skills
4---
5
61# Skills
72
83## Create Skill
94
10**post** `/v1/skills`
5**POST** `/v1/skills`
116
127Create Skill
138
14### Header Parameters
9### Headers
1510
1611- `"anthropic-beta": optional array of AnthropicBeta`
1712
from line 84
8984
9085 - `"mid-conversation-tool-changes-2026-07-01"`
9186
87### Body parameters (form-data)
88
89- `files: array of string`
90
91 Files to upload for the skill.
92
93 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
94
95- `display_title: optional string or null`
96
97 Display title for the skill.
98
99 This is a human-readable label that is not included in the prompt sent to the model.
100
92101### Returns
93102
94103- `id: string`
from line 137
128137
129138 For Skills, this is always `"skill"`.
130139
140 default: skill
141
131142- `updated_at: string`
132143
133144 ISO 8601 timestamp of when the skill was last updated.
from line 145
134145
135146### Example
136147
137```http
148```bash
138149curl https://api.anthropic.com/v1/skills \
139150 -H 'Content-Type: multipart/form-data' \
140151 -H 'anthropic-version: 2023-06-01' \
from line 154
143154 -F files='["Example data"]'
144155```
145156
146#### Response
157#### Response (200)
147158
148159```json
149160{
from line 170
159170
160171## List Skills
161172
162**get** `/v1/skills`
173**GET** `/v1/skills`
163174
164175List Skills
165176
166### Query Parameters
177### Query parameters
167178
168179- `limit: optional number`
169180
from line 182
171182
172183 Maximum value is 100. Defaults to 20.
173184
185 default: 20
186
174187- `page: optional string`
175188
176189 Pagination token for fetching a specific page of results.
from line 199
186199 * `"custom"`: only return user-created skills
187200 * `"anthropic"`: only return Anthropic-created skills
188201
189### Header Parameters
202### Headers
190203
191204- `"anthropic-beta": optional array of AnthropicBeta`
192205
from line 279
266279
267280### Returns
268281
269- `data: array of object { id, created_at, display_title, 4 more }`
282- `data: array of object`
270283
271284 List of skills.
272285
from line 320
307320
308321 For Skills, this is always `"skill"`.
309322
323 default: skill
324
310325 - `updated_at: string`
311326
312327 ISO 8601 timestamp of when the skill was last updated.
from line 340
325340
326341### Example
327342
328```http
343```bash
329344curl https://api.anthropic.com/v1/skills \
330345 -H 'anthropic-version: 2023-06-01' \
331346 -H 'anthropic-beta: skills-2025-10-02' \
from line 347
332347 -H "X-Api-Key: $ANTHROPIC_API_KEY"
333348```
334349
335#### Response
350#### Response (200)
336351
337352```json
338353{
from line 369
354369
355370## Get Skill
356371
357**get** `/v1/skills/{skill_id}`
372**GET** `/v1/skills/{skill_id}`
358373
359374Get Skill
360375
361### Path Parameters
376### Path parameters
362377
363378- `skill_id: string`
364379
from line 381
366381
367382 The format and length of IDs may change over time.
368383
369### Header Parameters
384### Headers
370385
371386- `"anthropic-beta": optional array of AnthropicBeta`
372387
from line 498
483498
484499 For Skills, this is always `"skill"`.
485500
501 default: skill
502
486503- `updated_at: string`
487504
488505 ISO 8601 timestamp of when the skill was last updated.
from line 506
489506
490507### Example
491508
492```http
509```bash
493510curl https://api.anthropic.com/v1/skills/$SKILL_ID \
494511 -H 'anthropic-version: 2023-06-01' \
495512 -H 'anthropic-beta: skills-2025-10-02' \
from line 513
496513 -H "X-Api-Key: $ANTHROPIC_API_KEY"
497514```
498515
499#### Response
516#### Response (200)
500517
501518```json
502519{
from line 529
512529
513530## Delete Skill
514531
515**delete** `/v1/skills/{skill_id}`
532**DELETE** `/v1/skills/{skill_id}`
516533
517534Delete Skill
518535
519### Path Parameters
536### Path parameters
520537
521538- `skill_id: string`
522539
from line 541
524541
525542 The format and length of IDs may change over time.
526543
527### Header Parameters
544### Headers
528545
529546- `"anthropic-beta": optional array of AnthropicBeta`
530547
from line 633
616633
617634 For Skills, this is always `"skill_deleted"`.
618635
636 default: skill_deleted
637
619638### Example
620639
621```http
640```bash
622641curl https://api.anthropic.com/v1/skills/$SKILL_ID \
623642 -X DELETE \
624643 -H 'anthropic-version: 2023-06-01' \
from line 645
626645 -H "X-Api-Key: $ANTHROPIC_API_KEY"
627646```
628647
629#### Response
648#### Response (200)
630649
631650```json
632651{
from line 654
635654}
636655```
637656
638## Domain Types
657## Domain types
639658
640659### Skill Create Response
641660
642- `SkillCreateResponse object { id, created_at, display_title, 4 more }`
661- `SkillCreateResponse object`
643662
644663 - `id: string`
645664
from line 697
678697
679698 For Skills, this is always `"skill"`.
680699
700 default: skill
701
681702 - `updated_at: string`
682703
683704 ISO 8601 timestamp of when the skill was last updated.
from line 705
684705
685706### Skill List Response
686707
687- `SkillListResponse object { id, created_at, display_title, 4 more }`
708- `SkillListResponse object`
688709
689710 - `id: string`
690711
from line 744
723744
724745 For Skills, this is always `"skill"`.
725746
747 default: skill
748
726749 - `updated_at: string`
727750
728751 ISO 8601 timestamp of when the skill was last updated.
from line 752
729752
730753### Skill Retrieve Response
731754
732- `SkillRetrieveResponse object { id, created_at, display_title, 4 more }`
755- `SkillRetrieveResponse object`
733756
734757 - `id: string`
735758
from line 791
768791
769792 For Skills, this is always `"skill"`.
770793
794 default: skill
795
771796 - `updated_at: string`
772797
773798 ISO 8601 timestamp of when the skill was last updated.
from line 799
774799
775800### Skill Delete Response
776801
777- `SkillDeleteResponse object { id, type }`
802- `SkillDeleteResponse object`
778803
779804 - `id: string`
780805
from line 813
788813
789814 For Skills, this is always `"skill_deleted"`.
790815
791# Versions
816 default: skill_deleted
792817
793## Create Skill Version
818## Skills › Versions
794819
795**post** `/v1/skills/{skill_id}/versions`
820### Create Skill Version
796821
822**POST** `/v1/skills/{skill_id}/versions`
823
797824Create Skill Version
798825
799### Path Parameters
826#### Path parameters
800827
801828- `skill_id: string`
802829
from line 831
804831
805832 The format and length of IDs may change over time.
806833
807### Header Parameters
834#### Headers
808835
809836- `"anthropic-beta": optional array of AnthropicBeta`
810837
from line 909
882909
883910 - `"mid-conversation-tool-changes-2026-07-01"`
884911
885### Returns
912#### Body parameters (form-data)
886913
914- `files: array of string`
915
916 Files to upload for the skill.
917
918 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
919
920#### Returns
921
887922- `id: string`
888923
889924 Unique identifier for the skill version.
from line 957
922957
923958 For Skill Versions, this is always `"skill_version"`.
924959
960 default: skill_version
961
925962- `version: string`
926963
927964 Version identifier for the skill.
from line 965
928965
929966 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
930967
931### Example
968#### Example
932969
933```http
970```bash
934971curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
935972 -H 'Content-Type: multipart/form-data' \
936973 -H 'anthropic-version: 2023-06-01' \
from line 976
939976 -F files='["Example data"]'
940977```
941978
942#### Response
979##### Response (200)
943980
944981```json
945982{
from line 991
954991}
955992```
956993
957## List Skill Versions
994### List Skill Versions
958995
959**get** `/v1/skills/{skill_id}/versions`
996**GET** `/v1/skills/{skill_id}/versions`
960997
961998List Skill Versions
962999
963### Path Parameters
1000#### Path parameters
9641001
9651002- `skill_id: string`
9661003
from line 1005
9681005
9691006 The format and length of IDs may change over time.
9701007
971### Query Parameters
1008#### Query parameters
9721009
9731010- `limit: optional number`
9741011
from line 1017
9801017
9811018 Optionally set to the `next_page` token from the previous response.
9821019
983### Header Parameters
1020#### Headers
9841021
9851022- `"anthropic-beta": optional array of AnthropicBeta`
9861023
from line 1095
10581095
10591096 - `"mid-conversation-tool-changes-2026-07-01"`
10601097
1061### Returns
1098#### Returns
10621099
1063- `data: array of object { id, created_at, description, 5 more }`
1100- `data: array of object`
10641101
10651102 List of skill versions.
10661103
from line 1139
11021139
11031140 For Skill Versions, this is always `"skill_version"`.
11041141
1142 default: skill_version
1143
11051144 - `version: string`
11061145
11071146 Version identifier for the skill.
from line 1155
11161155
11171156 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
11181157
1119### Example
1158#### Example
11201159
1121```http
1160```bash
11221161curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
11231162 -H 'anthropic-version: 2023-06-01' \
11241163 -H 'anthropic-beta: skills-2025-10-02' \
from line 1164
11251164 -H "X-Api-Key: $ANTHROPIC_API_KEY"
11261165```
11271166
1128#### Response
1167##### Response (200)
11291168
11301169```json
11311170{
from line 1185
11461185}
11471186```
11481187
1149## Download Skill Version Content
1188### Download Skill Version Content
11501189
1151**get** `/v1/skills/{skill_id}/versions/{version}/content`
1190**GET** `/v1/skills/{skill_id}/versions/{version}/content`
11521191
11531192Download a skill version's content as a zip archive.
11541193
1155### Path Parameters
1194#### Path parameters
11561195
11571196- `skill_id: string`
11581197
from line 1205
11661205
11671206 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
11681207
1169### Header Parameters
1208#### Headers
11701209
11711210- `"anthropic-beta": optional array of AnthropicBeta`
11721211
from line 1283
12441283
12451284 - `"mid-conversation-tool-changes-2026-07-01"`
12461285
1247### Example
1286#### Example
12481287
1249```http
1288```bash
12501289curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION/content \
12511290 -H 'anthropic-version: 2023-06-01' \
12521291 -H 'anthropic-beta: skills-2025-10-02' \
from line 1292
12531292 -H "X-Api-Key: $ANTHROPIC_API_KEY"
12541293```
12551294
1256## Get Skill Version
1295### Get Skill Version
12571296
1258**get** `/v1/skills/{skill_id}/versions/{version}`
1297**GET** `/v1/skills/{skill_id}/versions/{version}`
12591298
12601299Get Skill Version
12611300
1262### Path Parameters
1301#### Path parameters
12631302
12641303- `skill_id: string`
12651304
from line 1312
12731312
12741313 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
12751314
1276### Header Parameters
1315#### Headers
12771316
12781317- `"anthropic-beta": optional array of AnthropicBeta`
12791318
from line 1390
13511390
13521391 - `"mid-conversation-tool-changes-2026-07-01"`
13531392
1354### Returns
1393#### Returns
13551394
13561395- `id: string`
13571396
from line 1430
13911430
13921431 For Skill Versions, this is always `"skill_version"`.
13931432
1433 default: skill_version
1434
13941435- `version: string`
13951436
13961437 Version identifier for the skill.
from line 1438
13971438
13981439 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
13991440
1400### Example
1441#### Example
14011442
1402```http
1443```bash
14031444curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
14041445 -H 'anthropic-version: 2023-06-01' \
14051446 -H 'anthropic-beta: skills-2025-10-02' \
from line 1447
14061447 -H "X-Api-Key: $ANTHROPIC_API_KEY"
14071448```
14081449
1409#### Response
1450##### Response (200)
14101451
14111452```json
14121453{
from line 1462
14211462}
14221463```
14231464
1424## Delete Skill Version
1465### Delete Skill Version
14251466
1426**delete** `/v1/skills/{skill_id}/versions/{version}`
1467**DELETE** `/v1/skills/{skill_id}/versions/{version}`
14271468
14281469Delete Skill Version
14291470
1430### Path Parameters
1471#### Path parameters
14311472
14321473- `skill_id: string`
14331474
from line 1482
14411482
14421483 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
14431484
1444### Header Parameters
1485#### Headers
14451486
14461487- `"anthropic-beta": optional array of AnthropicBeta`
14471488
from line 1560
15191560
15201561 - `"mid-conversation-tool-changes-2026-07-01"`
15211562
1522### Returns
1563#### Returns
15231564
15241565- `id: string`
15251566
from line 1574
15331574
15341575 For Skill Versions, this is always `"skill_version_deleted"`.
15351576
1536### Example
1577 default: skill_version_deleted
15371578
1538```http
1579#### Example
1580
1581```bash
15391582curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
15401583 -X DELETE \
15411584 -H 'anthropic-version: 2023-06-01' \
from line 1586
15431586 -H "X-Api-Key: $ANTHROPIC_API_KEY"
15441587```
15451588
1546#### Response
1589##### Response (200)
15471590
15481591```json
15491592{
from line 1594
15511594 "type": "type"
15521595}
15531596```
1554
1555## Domain Types
1556
1557### Version Create Response
1558
1559- `VersionCreateResponse object { id, created_at, description, 5 more }`
1560
1561 - `id: string`
1562
1563 Unique identifier for the skill version.
1564
1565 The format and length of IDs may change over time.
1566
1567 - `created_at: string`
1568
1569 ISO 8601 timestamp of when the skill version was created.
1570
1571 - `description: string`
1572
1573 Description of the skill version.
1574
1575 This is extracted from the SKILL.md file in the skill upload.
1576
1577 - `directory: string`
1578
1579 Directory name of the skill version.
1580
1581 This is the top-level directory name that was extracted from the uploaded files.
1582
1583 - `name: string`
1584
1585 Human-readable name of the skill version.
1586
1587 This is extracted from the SKILL.md file in the skill upload.
1588
1589 - `skill_id: string`
1590
1591 Identifier for the skill that this version belongs to.
1592
1593 - `type: string`
1594
1595 Object type.
1596
1597 For Skill Versions, this is always `"skill_version"`.
1598
1599 - `version: string`
1600
1601 Version identifier for the skill.
1602
1603 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1604
1605### Version List Response
1606
1607- `VersionListResponse object { id, created_at, description, 5 more }`
1608
1609 - `id: string`
1610
1611 Unique identifier for the skill version.
1612
1613 The format and length of IDs may change over time.
1614
1615 - `created_at: string`
1616
1617 ISO 8601 timestamp of when the skill version was created.
1618
1619 - `description: string`
1620
1621 Description of the skill version.
1622
1623 This is extracted from the SKILL.md file in the skill upload.
1624
1625 - `directory: string`
1626
1627 Directory name of the skill version.
1628
1629 This is the top-level directory name that was extracted from the uploaded files.
1630
1631 - `name: string`
1632
1633 Human-readable name of the skill version.
1634
1635 This is extracted from the SKILL.md file in the skill upload.
1636
1637 - `skill_id: string`
1638
1639 Identifier for the skill that this version belongs to.
1640
1641 - `type: string`
1642
1643 Object type.
1644
1645 For Skill Versions, this is always `"skill_version"`.
1646
1647 - `version: string`
1648
1649 Version identifier for the skill.
1650
1651 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1652
1653### Version Retrieve Response
1654
1655- `VersionRetrieveResponse object { id, created_at, description, 5 more }`
1656
1657 - `id: string`
1658
1659 Unique identifier for the skill version.
1660
1661 The format and length of IDs may change over time.
1662
1663 - `created_at: string`
1664
1665 ISO 8601 timestamp of when the skill version was created.
1666
1667 - `description: string`
1668
1669 Description of the skill version.
1670
1671 This is extracted from the SKILL.md file in the skill upload.
1672
1673 - `directory: string`
1674
1675 Directory name of the skill version.
1676
1677 This is the top-level directory name that was extracted from the uploaded files.
1678
1679 - `name: string`
1680
1681 Human-readable name of the skill version.
1682
1683 This is extracted from the SKILL.md file in the skill upload.
1684
1685 - `skill_id: string`
1686
1687 Identifier for the skill that this version belongs to.
1688
1689 - `type: string`
1690
1691 Object type.
1692
1693 For Skill Versions, this is always `"skill_version"`.
1694
1695 - `version: string`
1696
1697 Version identifier for the skill.
1698
1699 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1700
1701### Version Delete Response
1702
1703- `VersionDeleteResponse object { id, type }`
1704
1705 - `id: string`
1706
1707 Version identifier for the skill.
1708
1709 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
1710
1711 - `type: string`
1712
1713 Deleted object type.
1714
1715 For Skill Versions, this is always `"skill_version_deleted"`.
17161597
api/beta/skills/create Changed · +23 / -12 lines
# Create Skill ## Headers ## Body parameters (form-data) ## Returns ## Example ### Response (200) ## Create Skill ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Create Skill
3url: https://platform.claude.com/docs/en/api/beta/skills/create
4---
1# Create Skill
52
6## Create Skill
3**POST** `/v1/skills`
74
8**post** `/v1/skills`
9
105Create Skill
116
12### Header Parameters
7## Headers
138
149- `"anthropic-beta": optional array of AnthropicBeta`
1510
from line 82
8782
8883 - `"mid-conversation-tool-changes-2026-07-01"`
8984
90### Returns
85## Body parameters (form-data)
9186
87- `files: array of string`
88
89 Files to upload for the skill.
90
91 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
92
93- `display_title: optional string or null`
94
95 Display title for the skill.
96
97 This is a human-readable label that is not included in the prompt sent to the model.
98
99## Returns
100
92101- `id: string`
93102
94103 Unique identifier for the skill.
from line 135
126135
127136 For Skills, this is always `"skill"`.
128137
138 default: skill
139
129140- `updated_at: string`
130141
131142 ISO 8601 timestamp of when the skill was last updated.
132143
133### Example
144## Example
134145
135```http
146```bash
136147curl https://api.anthropic.com/v1/skills \
137148 -H 'Content-Type: multipart/form-data' \
138149 -H 'anthropic-version: 2023-06-01' \
from line 152
141152 -F files='["Example data"]'
142153```
143154
144#### Response
155### Response (200)
145156
146157```json
147158{
api/beta/skills/delete Changed · +10 / -13 lines
# Delete Skill ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Delete Skill ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Delete Skill
3url: https://platform.claude.com/docs/en/api/beta/skills/delete
4---
1# Delete Skill
52
6## Delete Skill
3**DELETE** `/v1/skills/{skill_id}`
74
8**delete** `/v1/skills/{skill_id}`
9
105Delete Skill
116
12### Path Parameters
7## Path parameters
138
149- `skill_id: string`
1510
from line 12
1712
1813 The format and length of IDs may change over time.
1914
20### Header Parameters
15## Headers
2116
2217- `"anthropic-beta": optional array of AnthropicBeta`
2318
from line 90
9590
9691 - `"mid-conversation-tool-changes-2026-07-01"`
9792
98### Returns
93## Returns
9994
10095- `id: string`
10196
from line 104
109104
110105 For Skills, this is always `"skill_deleted"`.
111106
112### Example
107 default: skill_deleted
113108
114```http
109## Example
110
111```bash
115112curl https://api.anthropic.com/v1/skills/$SKILL_ID \
116113 -X DELETE \
117114 -H 'anthropic-version: 2023-06-01' \
from line 116
119116 -H "X-Api-Key: $ANTHROPIC_API_KEY"
120117```
121118
122#### Response
119### Response (200)
123120
124121```json
125122{
api/beta/skills/list Changed · +13 / -14 lines
# List Skills ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Skills ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Skills
3url: https://platform.claude.com/docs/en/api/beta/skills/list
4---
1# List Skills
52
6## List Skills
3**GET** `/v1/skills`
74
8**get** `/v1/skills`
9
105List Skills
116
12### Query Parameters
7## Query parameters
138
149- `limit: optional number`
1510
from line 12
1712
1813 Maximum value is 100. Defaults to 20.
1914
15 default: 20
16
2017- `page: optional string`
2118
2219 Pagination token for fetching a specific page of results.
from line 29
3229 * `"custom"`: only return user-created skills
3330 * `"anthropic"`: only return Anthropic-created skills
3431
35### Header Parameters
32## Headers
3633
3734- `"anthropic-beta": optional array of AnthropicBeta`
3835
from line 107
110107
111108 - `"mid-conversation-tool-changes-2026-07-01"`
112109
113### Returns
110## Returns
114111
115- `data: array of object { id, created_at, display_title, 4 more }`
112- `data: array of object`
116113
117114 List of skills.
118115
from line 150
153150
154151 For Skills, this is always `"skill"`.
155152
153 default: skill
154
156155 - `updated_at: string`
157156
158157 ISO 8601 timestamp of when the skill was last updated.
from line 168
169168
170169 If `null`, there are no more results available. Pass this value to the `page` parameter in the next request to get the next page.
171170
172### Example
171## Example
173172
174```http
173```bash
175174curl https://api.anthropic.com/v1/skills \
176175 -H 'anthropic-version: 2023-06-01' \
177176 -H 'anthropic-beta: skills-2025-10-02' \
from line 177
178177 -H "X-Api-Key: $ANTHROPIC_API_KEY"
179178```
180179
181#### Response
180### Response (200)
182181
183182```json
184183{
api/beta/skills/retrieve Changed · +10 / -13 lines
# Get Skill ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Skill ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Skill
3url: https://platform.claude.com/docs/en/api/beta/skills/retrieve
4---
1# Get Skill
52
6## Get Skill
3**GET** `/v1/skills/{skill_id}`
74
8**get** `/v1/skills/{skill_id}`
9
105Get Skill
116
12### Path Parameters
7## Path parameters
138
149- `skill_id: string`
1510
from line 12
1712
1813 The format and length of IDs may change over time.
1914
20### Header Parameters
15## Headers
2116
2217- `"anthropic-beta": optional array of AnthropicBeta`
2318
from line 90
9590
9691 - `"mid-conversation-tool-changes-2026-07-01"`
9792
98### Returns
93## Returns
9994
10095- `id: string`
10196
from line 129
134129
135130 For Skills, this is always `"skill"`.
136131
132 default: skill
133
137134- `updated_at: string`
138135
139136 ISO 8601 timestamp of when the skill was last updated.
140137
141### Example
138## Example
142139
143```http
140```bash
144141curl https://api.anthropic.com/v1/skills/$SKILL_ID \
145142 -H 'anthropic-version: 2023-06-01' \
146143 -H 'anthropic-beta: skills-2025-10-02' \
from line 144
147144 -H "X-Api-Key: $ANTHROPIC_API_KEY"
148145```
149146
150#### Response
147### Response (200)
151148
152149```json
153150{
api/beta/skills/versions Changed · +55 / -36 lines
### Path parameters ### Headers ### Body parameters (form-data) #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types
from line 1
1---
2title: Versions
3url: https://platform.claude.com/docs/en/api/beta/skills/versions
4---
5
61# Versions
72
83## Create Skill Version
94
10**post** `/v1/skills/{skill_id}/versions`
5**POST** `/v1/skills/{skill_id}/versions`
116
127Create Skill Version
138
14### Path Parameters
9### Path parameters
1510
1611- `skill_id: string`
1712
from line 14
1914
2015 The format and length of IDs may change over time.
2116
22### Header Parameters
17### Headers
2318
2419- `"anthropic-beta": optional array of AnthropicBeta`
2520
from line 92
9792
9893 - `"mid-conversation-tool-changes-2026-07-01"`
9994
95### Body parameters (form-data)
96
97- `files: array of string`
98
99 Files to upload for the skill.
100
101 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
102
100103### Returns
101104
102105- `id: string`
from line 140
137140
138141 For Skill Versions, this is always `"skill_version"`.
139142
143 default: skill_version
144
140145- `version: string`
141146
142147 Version identifier for the skill.
from line 150
145150
146151### Example
147152
148```http
153```bash
149154curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
150155 -H 'Content-Type: multipart/form-data' \
151156 -H 'anthropic-version: 2023-06-01' \
from line 159
154159 -F files='["Example data"]'
155160```
156161
157#### Response
162#### Response (200)
158163
159164```json
160165{
from line 176
171176
172177## List Skill Versions
173178
174**get** `/v1/skills/{skill_id}/versions`
179**GET** `/v1/skills/{skill_id}/versions`
175180
176181List Skill Versions
177182
178### Path Parameters
183### Path parameters
179184
180185- `skill_id: string`
181186
from line 188
183188
184189 The format and length of IDs may change over time.
185190
186### Query Parameters
191### Query parameters
187192
188193- `limit: optional number`
189194
from line 200
195200
196201 Optionally set to the `next_page` token from the previous response.
197202
198### Header Parameters
203### Headers
199204
200205- `"anthropic-beta": optional array of AnthropicBeta`
201206
from line 280
275280
276281### Returns
277282
278- `data: array of object { id, created_at, description, 5 more }`
283- `data: array of object`
279284
280285 List of skill versions.
281286
from line 322
317322
318323 For Skill Versions, this is always `"skill_version"`.
319324
325 default: skill_version
326
320327 - `version: string`
321328
322329 Version identifier for the skill.
from line 340
333340
334341### Example
335342
336```http
343```bash
337344curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
338345 -H 'anthropic-version: 2023-06-01' \
339346 -H 'anthropic-beta: skills-2025-10-02' \
from line 347
340347 -H "X-Api-Key: $ANTHROPIC_API_KEY"
341348```
342349
343#### Response
350#### Response (200)
344351
345352```json
346353{
from line 370
363370
364371## Download Skill Version Content
365372
366**get** `/v1/skills/{skill_id}/versions/{version}/content`
373**GET** `/v1/skills/{skill_id}/versions/{version}/content`
367374
368375Download a skill version's content as a zip archive.
369376
370### Path Parameters
377### Path parameters
371378
372379- `skill_id: string`
373380
from line 388
381388
382389 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
383390
384### Header Parameters
391### Headers
385392
386393- `"anthropic-beta": optional array of AnthropicBeta`
387394
from line 468
461468
462469### Example
463470
464```http
471```bash
465472curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION/content \
466473 -H 'anthropic-version: 2023-06-01' \
467474 -H 'anthropic-beta: skills-2025-10-02' \
from line 477
470477
471478## Get Skill Version
472479
473**get** `/v1/skills/{skill_id}/versions/{version}`
480**GET** `/v1/skills/{skill_id}/versions/{version}`
474481
475482Get Skill Version
476483
477### Path Parameters
484### Path parameters
478485
479486- `skill_id: string`
480487
from line 495
488495
489496 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
490497
491### Header Parameters
498### Headers
492499
493500- `"anthropic-beta": optional array of AnthropicBeta`
494501
from line 613
606613
607614 For Skill Versions, this is always `"skill_version"`.
608615
616 default: skill_version
617
609618- `version: string`
610619
611620 Version identifier for the skill.
from line 623
614623
615624### Example
616625
617```http
626```bash
618627curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
619628 -H 'anthropic-version: 2023-06-01' \
620629 -H 'anthropic-beta: skills-2025-10-02' \
from line 630
621630 -H "X-Api-Key: $ANTHROPIC_API_KEY"
622631```
623632
624#### Response
633#### Response (200)
625634
626635```json
627636{
from line 647
638647
639648## Delete Skill Version
640649
641**delete** `/v1/skills/{skill_id}/versions/{version}`
650**DELETE** `/v1/skills/{skill_id}/versions/{version}`
642651
643652Delete Skill Version
644653
645### Path Parameters
654### Path parameters
646655
647656- `skill_id: string`
648657
from line 665
656665
657666 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
658667
659### Header Parameters
668### Headers
660669
661670- `"anthropic-beta": optional array of AnthropicBeta`
662671
from line 757
748757
749758 For Skill Versions, this is always `"skill_version_deleted"`.
750759
760 default: skill_version_deleted
761
751762### Example
752763
753```http
764```bash
754765curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
755766 -X DELETE \
756767 -H 'anthropic-version: 2023-06-01' \
from line 769
758769 -H "X-Api-Key: $ANTHROPIC_API_KEY"
759770```
760771
761#### Response
772#### Response (200)
762773
763774```json
764775{
from line 778
767778}
768779```
769780
770## Domain Types
781## Domain types
771782
772783### Version Create Response
773784
774- `VersionCreateResponse object { id, created_at, description, 5 more }`
785- `VersionCreateResponse object`
775786
776787 - `id: string`
777788
from line 822
811822
812823 For Skill Versions, this is always `"skill_version"`.
813824
825 default: skill_version
826
814827 - `version: string`
815828
816829 Version identifier for the skill.
from line 832
819832
820833### Version List Response
821834
822- `VersionListResponse object { id, created_at, description, 5 more }`
835- `VersionListResponse object`
823836
824837 - `id: string`
825838
from line 872
859872
860873 For Skill Versions, this is always `"skill_version"`.
861874
875 default: skill_version
876
862877 - `version: string`
863878
864879 Version identifier for the skill.
from line 882
867882
868883### Version Retrieve Response
869884
870- `VersionRetrieveResponse object { id, created_at, description, 5 more }`
885- `VersionRetrieveResponse object`
871886
872887 - `id: string`
873888
from line 922
907922
908923 For Skill Versions, this is always `"skill_version"`.
909924
925 default: skill_version
926
910927 - `version: string`
911928
912929 Version identifier for the skill.
from line 932
915932
916933### Version Delete Response
917934
918- `VersionDeleteResponse object { id, type }`
935- `VersionDeleteResponse object`
919936
920937 - `id: string`
921938
from line 945
928945 Deleted object type.
929946
930947 For Skill Versions, this is always `"skill_version_deleted"`.
948
949 default: skill_version_deleted
931950
api/beta/skills/versions/create Changed · +18 / -13 lines
# Create Skill Version ## Path parameters ## Headers ## Body parameters (form-data) ## Returns ## Example ### Response (200) ## Create Skill Version ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Create Skill Version
3url: https://platform.claude.com/docs/en/api/beta/skills/versions/create
4---
1# Create Skill Version
52
6## Create Skill Version
3**POST** `/v1/skills/{skill_id}/versions`
74
8**post** `/v1/skills/{skill_id}/versions`
9
105Create Skill Version
116
12### Path Parameters
7## Path parameters
138
149- `skill_id: string`
1510
from line 12
1712
1813 The format and length of IDs may change over time.
1914
20### Header Parameters
15## Headers
2116
2217- `"anthropic-beta": optional array of AnthropicBeta`
2318
from line 90
9590
9691 - `"mid-conversation-tool-changes-2026-07-01"`
9792
98### Returns
93## Body parameters (form-data)
9994
95- `files: array of string`
96
97 Files to upload for the skill.
98
99 All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.
100
101## Returns
102
100103- `id: string`
101104
102105 Unique identifier for the skill version.
from line 138
135138
136139 For Skill Versions, this is always `"skill_version"`.
137140
141 default: skill_version
142
138143- `version: string`
139144
140145 Version identifier for the skill.
from line 146
141146
142147 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
143148
144### Example
149## Example
145150
146```http
151```bash
147152curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
148153 -H 'Content-Type: multipart/form-data' \
149154 -H 'anthropic-version: 2023-06-01' \
from line 157
152157 -F files='["Example data"]'
153158```
154159
155#### Response
160### Response (200)
156161
157162```json
158163{
api/beta/skills/versions/delete Changed · +10 / -13 lines
# Delete Skill Version ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Delete Skill Version ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Delete Skill Version
3url: https://platform.claude.com/docs/en/api/beta/skills/versions/delete
4---
1# Delete Skill Version
52
6## Delete Skill Version
3**DELETE** `/v1/skills/{skill_id}/versions/{version}`
74
8**delete** `/v1/skills/{skill_id}/versions/{version}`
9
105Delete Skill Version
116
12### Path Parameters
7## Path parameters
138
149- `skill_id: string`
1510
from line 18
2318
2419 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
2520
26### Header Parameters
21## Headers
2722
2823- `"anthropic-beta": optional array of AnthropicBeta`
2924
from line 96
10196
10297 - `"mid-conversation-tool-changes-2026-07-01"`
10398
104### Returns
99## Returns
105100
106101- `id: string`
107102
from line 110
115110
116111 For Skill Versions, this is always `"skill_version_deleted"`.
117112
118### Example
113 default: skill_version_deleted
119114
120```http
115## Example
116
117```bash
121118curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
122119 -X DELETE \
123120 -H 'anthropic-version: 2023-06-01' \
from line 122
125122 -H "X-Api-Key: $ANTHROPIC_API_KEY"
126123```
127124
128#### Response
125### Response (200)
129126
130127```json
131128{
api/beta/skills/versions/download Changed · +6 / -11 lines
# Download Skill Version Content ## Path parameters ## Headers ## Example ## Download Skill Version Content ### Path Parameters ### Header Parameters ### Example
from line 1
1---
2title: Download Skill Version Content
3url: https://platform.claude.com/docs/en/api/beta/skills/versions/download
4---
1# Download Skill Version Content
52
6## Download Skill Version Content
3**GET** `/v1/skills/{skill_id}/versions/{version}/content`
74
8**get** `/v1/skills/{skill_id}/versions/{version}/content`
9
105Download a skill version's content as a zip archive.
116
12### Path Parameters
7## Path parameters
138
149- `skill_id: string`
1510
from line 18
2318
2419 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
2520
26### Header Parameters
21## Headers
2722
2823- `"anthropic-beta": optional array of AnthropicBeta`
2924
from line 96
10196
10297 - `"mid-conversation-tool-changes-2026-07-01"`
10398
104### Example
99## Example
105100
106```http
101```bash
107102curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION/content \
108103 -H 'anthropic-version: 2023-06-01' \
109104 -H 'anthropic-beta: skills-2025-10-02' \
api/beta/skills/versions/list Changed · +12 / -15 lines
# List Skill Versions ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Skill Versions ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Skill Versions
3url: https://platform.claude.com/docs/en/api/beta/skills/versions/list
4---
1# List Skill Versions
52
6## List Skill Versions
3**GET** `/v1/skills/{skill_id}/versions`
74
8**get** `/v1/skills/{skill_id}/versions`
9
105List Skill Versions
116
12### Path Parameters
7## Path parameters
138
149- `skill_id: string`
1510
from line 12
1712
1813 The format and length of IDs may change over time.
1914
20### Query Parameters
15## Query parameters
2116
2217- `limit: optional number`
2318
from line 24
2924
3025 Optionally set to the `next_page` token from the previous response.
3126
32### Header Parameters
27## Headers
3328
3429- `"anthropic-beta": optional array of AnthropicBeta`
3530
from line 102
107102
108103 - `"mid-conversation-tool-changes-2026-07-01"`
109104
110### Returns
105## Returns
111106
112- `data: array of object { id, created_at, description, 5 more }`
107- `data: array of object`
113108
114109 List of skill versions.
115110
from line 146
151146
152147 For Skill Versions, this is always `"skill_version"`.
153148
149 default: skill_version
150
154151 - `version: string`
155152
156153 Version identifier for the skill.
from line 162
165162
166163 Token to provide in as `page` in the subsequent request to retrieve the next page of data.
167164
168### Example
165## Example
169166
170```http
167```bash
171168curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
172169 -H 'anthropic-version: 2023-06-01' \
173170 -H 'anthropic-beta: skills-2025-10-02' \
from line 171
174171 -H "X-Api-Key: $ANTHROPIC_API_KEY"
175172```
176173
177#### Response
174### Response (200)
178175
179176```json
180177{
api/beta/skills/versions/retrieve Changed · +10 / -13 lines
# Get Skill Version ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Skill Version ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Skill Version
3url: https://platform.claude.com/docs/en/api/beta/skills/versions/retrieve
4---
1# Get Skill Version
52
6## Get Skill Version
3**GET** `/v1/skills/{skill_id}/versions/{version}`
74
8**get** `/v1/skills/{skill_id}/versions/{version}`
9
105Get Skill Version
116
12### Path Parameters
7## Path parameters
138
149- `skill_id: string`
1510
from line 18
2318
2419 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
2520
26### Header Parameters
21## Headers
2722
2823- `"anthropic-beta": optional array of AnthropicBeta`
2924
from line 96
10196
10297 - `"mid-conversation-tool-changes-2026-07-01"`
10398
104### Returns
99## Returns
105100
106101- `id: string`
107102
from line 136
141136
142137 For Skill Versions, this is always `"skill_version"`.
143138
139 default: skill_version
140
144141- `version: string`
145142
146143 Version identifier for the skill.
from line 144
147144
148145 Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").
149146
150### Example
147## Example
151148
152```http
149```bash
153150curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
154151 -H 'anthropic-version: 2023-06-01' \
155152 -H 'anthropic-beta: skills-2025-10-02' \
from line 153
156153 -H "X-Api-Key: $ANTHROPIC_API_KEY"
157154```
158155
159#### Response
156### Response (200)
160157
161158```json
162159{
api/beta/tunnels Changed · +143 / -154 lines
### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ## Domain types ## Tunnels › Certificates ### Create Tunnel Certificate #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Get Tunnel Certificate #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### List Tunnel Certificates #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive Tunnel Certificate #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ## Domain Types # Certificates ## Create Tunnel Certificate ### Path Parameters ### Header Parameters ### Body Parameters #### Response ## Get Tunnel Certificate ### Path Parameters ### Header Parameters #### Response ## List Tunnel Certificates ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Archive Tunnel Certificate ### Path Parameters ### Header Parameters #### Response ## Domain Types ### Beta Tunnel Certificate
from line 1
1---
2title: Tunnels
3url: https://platform.claude.com/docs/en/api/beta/tunnels
4---
5
61# Tunnels
72
83## Create Tunnel
94
10**post** `/v1/tunnels`
5**POST** `/v1/tunnels`
116
127The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
138
149Creates a tunnel. Creation allocates a fresh hostname and provisions the tunnel; it is not idempotent. The new tunnel rejects MCP traffic until at least one CA certificate is added.
1510
16### Header Parameters
11### Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Body Parameters
89### Body parameters
9590
9691- `display_name: optional string or null`
9792
9893 Optional human-readable name for the tunnel (1-255 characters).
9994
95 minLength: 1, maxLength: 255
96
10097### Returns
10198
102- `BetaTunnel object { id, archived_at, created_at, 3 more }`
99- `BetaTunnel object`
103100
104101 An MCP tunnel.
105102
from line 108
111108
112109 A timestamp in RFC 3339 format
113110
111 format: date-time
112
114113 - `created_at: string`
115114
116115 A timestamp in RFC 3339 format
117116
117 format: date-time
118
118119 - `display_name: string or null`
119120
120121 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 126
125126
126127 - `type: "tunnel"`
127128
128 - `"tunnel"`
129
130129### Example
131130
132```http
131```bash
133132curl https://api.anthropic.com/v1/tunnels \
134133 -H 'Content-Type: application/json' \
135134 -H 'anthropic-version: 2023-06-01' \
from line 137
138137 -d '{}'
139138```
140139
141#### Response
140#### Response (200)
142141
143142```json
144143{
from line 152
153152
154153## Get Tunnel
155154
156**get** `/v1/tunnels/{tunnel_id}`
155**GET** `/v1/tunnels/{tunnel_id}`
157156
158157The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
159158
160159Fetches a tunnel by ID.
161160
162### Path Parameters
161### Path parameters
163162
164163- `tunnel_id: string`
165164
166### Header Parameters
165### Headers
167166
168167- `"anthropic-beta": optional array of AnthropicBeta`
169168
from line 242
243242
244243### Returns
245244
246- `BetaTunnel object { id, archived_at, created_at, 3 more }`
245- `BetaTunnel object`
247246
248247 An MCP tunnel.
249248
from line 254
255254
256255 A timestamp in RFC 3339 format
257256
257 format: date-time
258
258259 - `created_at: string`
259260
260261 A timestamp in RFC 3339 format
261262
263 format: date-time
264
262265 - `display_name: string or null`
263266
264267 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 272
269272
270273 - `type: "tunnel"`
271274
272 - `"tunnel"`
273
274275### Example
275276
276```http
277```bash
277278curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID \
278279 -H 'anthropic-version: 2023-06-01' \
279280 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 281
280281 -H "X-Api-Key: $ANTHROPIC_API_KEY"
281282```
282283
283#### Response
284#### Response (200)
284285
285286```json
286287{
from line 296
295296
296297## List Tunnels
297298
298**get** `/v1/tunnels`
299**GET** `/v1/tunnels`
299300
300301The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
301302
302303Lists tunnels. Results are ordered by creation time, newest first; archived tunnels are excluded unless include_archived is set.
303304
304### Query Parameters
305### Query parameters
305306
306307- `include_archived: optional boolean`
307308
from line 312
311312
312313 Maximum number of tunnels to return per page. Defaults to 20, maximum 1000.
313314
315 format: int32
316
314317- `page: optional string`
315318
316319 Opaque pagination cursor from a previous `list_tunnels` response.
317320
318### Header Parameters
321### Headers
319322
320323- `"anthropic-beta": optional array of AnthropicBeta`
321324
from line 410
407410
408411 A timestamp in RFC 3339 format
409412
413 format: date-time
414
410415 - `created_at: string`
411416
412417 A timestamp in RFC 3339 format
413418
419 format: date-time
420
414421 - `display_name: string or null`
415422
416423 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 428
421428
422429 - `type: "tunnel"`
423430
424 - `"tunnel"`
425
426431- `next_page: string or null`
427432
428433 Pagination cursor for the next page, or null if no more results.
from line 434
429434
430435### Example
431436
432```http
437```bash
433438curl https://api.anthropic.com/v1/tunnels \
434439 -H 'anthropic-version: 2023-06-01' \
435440 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 441
436441 -H "X-Api-Key: $ANTHROPIC_API_KEY"
437442```
438443
439#### Response
444#### Response (200)
440445
441446```json
442447{
from line 461
456461
457462## Archive Tunnel
458463
459**post** `/v1/tunnels/{tunnel_id}/archive`
464**POST** `/v1/tunnels/{tunnel_id}/archive`
460465
461466The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
462467
463468Archives a tunnel. Archival is irreversible: every non-archived certificate on the tunnel is archived in the same operation, the hostname is retired and never re-allocated, and the tunnel token is invalidated. Retrying against an already-archived tunnel returns the existing record unchanged.
464469
465### Path Parameters
470### Path parameters
466471
467472- `tunnel_id: string`
468473
469### Header Parameters
474### Headers
470475
471476- `"anthropic-beta": optional array of AnthropicBeta`
472477
from line 551
546551
547552### Returns
548553
549- `BetaTunnel object { id, archived_at, created_at, 3 more }`
554- `BetaTunnel object`
550555
551556 An MCP tunnel.
552557
from line 563
558563
559564 A timestamp in RFC 3339 format
560565
566 format: date-time
567
561568 - `created_at: string`
562569
563570 A timestamp in RFC 3339 format
564571
572 format: date-time
573
565574 - `display_name: string or null`
566575
567576 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 581
572581
573582 - `type: "tunnel"`
574583
575 - `"tunnel"`
576
577584### Example
578585
579```http
586```bash
580587curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/archive \
581588 -X POST \
582589 -H 'anthropic-version: 2023-06-01' \
from line 591
584591 -H "X-Api-Key: $ANTHROPIC_API_KEY"
585592```
586593
587#### Response
594#### Response (200)
588595
589596```json
590597{
from line 606
599606
600607## Reveal Tunnel Token
601608
602**post** `/v1/tunnels/{tunnel_id}/reveal_token`
609**POST** `/v1/tunnels/{tunnel_id}/reveal_token`
603610
604611The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
605612
606613Reveals a tunnel's connector token. The value is fetched live on each call; Anthropic does not store it. Repeated calls return the same value until the token is rotated. Exposed as POST so the token does not appear in intermediary access logs.
607614
608### Path Parameters
615### Path parameters
609616
610617- `tunnel_id: string`
611618
612### Header Parameters
619### Headers
613620
614621- `"anthropic-beta": optional array of AnthropicBeta`
615622
from line 696
689696
690697### Returns
691698
692- `BetaTunnelToken object { id, tunnel_token, type }`
699- `BetaTunnelToken object`
693700
694701 A tunnel's connector token.
695702
from line 710
703710
704711 - `type: "tunnel_token"`
705712
706 - `"tunnel_token"`
707
708713### Example
709714
710```http
715```bash
711716curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/reveal_token \
712717 -X POST \
713718 -H 'anthropic-version: 2023-06-01' \
from line 720
715720 -H "X-Api-Key: $ANTHROPIC_API_KEY"
716721```
717722
718#### Response
723#### Response (200)
719724
720725```json
721726{
from line 732
727732
728733## Rotate Tunnel Token
729734
730**post** `/v1/tunnels/{tunnel_id}/rotate_token`
735**POST** `/v1/tunnels/{tunnel_id}/rotate_token`
731736
732737The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
733738
734739Rotates a tunnel's connector token. Rotation invalidates the current token for new connections and returns a fresh value; established connections are not severed. A connector restarted after rotation must use the new value.
735740
736### Path Parameters
741### Path parameters
737742
738743- `tunnel_id: string`
739744
740### Header Parameters
745### Headers
741746
742747- `"anthropic-beta": optional array of AnthropicBeta`
743748
from line 820
815820
816821 - `"mid-conversation-tool-changes-2026-07-01"`
817822
818### Body Parameters
823### Body parameters
819824
820825- `reason: optional string or null`
821826
822827 Optional free-text reason for the rotation, recorded for audit.
823828
829 maxLength: 1024
830
824831### Returns
825832
826- `BetaTunnelToken object { id, tunnel_token, type }`
833- `BetaTunnelToken object`
827834
828835 A tunnel's connector token.
829836
from line 844
837844
838845 - `type: "tunnel_token"`
839846
840 - `"tunnel_token"`
841
842847### Example
843848
844```http
849```bash
845850curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/rotate_token \
846851 -H 'Content-Type: application/json' \
847852 -H 'anthropic-version: 2023-06-01' \
from line 855
850855 -d '{}'
851856```
852857
853#### Response
858#### Response (200)
854859
855860```json
856861{
from line 865
860865}
861866```
862867
863## Domain Types
868## Domain types
864869
865870### Beta Tunnel
866871
867- `BetaTunnel object { id, archived_at, created_at, 3 more }`
872- `BetaTunnel object`
868873
869874 An MCP tunnel.
870875
from line 881
876881
877882 A timestamp in RFC 3339 format
878883
884 format: date-time
885
879886 - `created_at: string`
880887
881888 A timestamp in RFC 3339 format
882889
890 format: date-time
891
883892 - `display_name: string or null`
884893
885894 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 899
890899
891900 - `type: "tunnel"`
892901
893 - `"tunnel"`
894
895902### Beta Tunnel Token
896903
897- `BetaTunnelToken object { id, tunnel_token, type }`
904- `BetaTunnelToken object`
898905
899906 A tunnel's connector token.
900907
from line 915
908915
909916 - `type: "tunnel_token"`
910917
911 - `"tunnel_token"`
918## Tunnels › Certificates
912919
913# Certificates
920### Create Tunnel Certificate
914921
915## Create Tunnel Certificate
922**POST** `/v1/tunnels/{tunnel_id}/certificates`
916923
917**post** `/v1/tunnels/{tunnel_id}/certificates`
918
919924The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
920925
921926Registers a public CA certificate on a tunnel. Anthropic verifies the gateway's server certificate against this CA when it terminates the inner TLS session. A tunnel holds at most two non-archived certificates.
922927
923### Path Parameters
928#### Path parameters
924929
925930- `tunnel_id: string`
926931
927### Header Parameters
932#### Headers
928933
929934- `"anthropic-beta": optional array of AnthropicBeta`
930935
from line 1007
10021007
10031008 - `"mid-conversation-tool-changes-2026-07-01"`
10041009
1005### Body Parameters
1010#### Body parameters
10061011
10071012- `ca_certificate_pem: string`
10081013
10091014 PEM-encoded X.509 CA certificate. Must contain exactly one certificate and no private-key material. Maximum 8KB.
10101015
1011### Returns
1016 maxLength: 8192
10121017
1013- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
1018#### Returns
10141019
1020- `BetaTunnelCertificate object`
1021
10151022 A CA certificate attached to a tunnel.
10161023
10171024 - `id: string`
from line 1029
10221029
10231030 A timestamp in RFC 3339 format
10241031
1032 format: date-time
1033
10251034 - `created_at: string`
10261035
10271036 A timestamp in RFC 3339 format
10281037
1038 format: date-time
1039
10291040 - `expires_at: string or null`
10301041
10311042 A timestamp in RFC 3339 format
10321043
1044 format: date-time
1045
10331046 - `fingerprint: string`
10341047
10351048 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 1053
10401053
10411054 - `type: "tunnel_certificate"`
10421055
1043 - `"tunnel_certificate"`
1056#### Example
10441057
1045### Example
1046
1047```http
1058```bash
10481059curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates \
10491060 -H 'Content-Type: application/json' \
10501061 -H 'anthropic-version: 2023-06-01' \
from line 1066
10551066 }'
10561067```
10571068
1058#### Response
1069##### Response (200)
10591070
10601071```json
10611072{
from line 1080
10691080}
10701081```
10711082
1072## Get Tunnel Certificate
1083### Get Tunnel Certificate
10731084
1074**get** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}`
1085**GET** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}`
10751086
10761087The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
10771088
10781089Fetches a tunnel certificate by ID.
10791090
1080### Path Parameters
1091#### Path parameters
10811092
10821093- `tunnel_id: string`
10831094
10841095- `certificate_id: string`
10851096
1086### Header Parameters
1097#### Headers
10871098
10881099- `"anthropic-beta": optional array of AnthropicBeta`
10891100
from line 1172
11611172
11621173 - `"mid-conversation-tool-changes-2026-07-01"`
11631174
1164### Returns
1175#### Returns
11651176
1166- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
1177- `BetaTunnelCertificate object`
11671178
11681179 A CA certificate attached to a tunnel.
11691180
from line 1186
11751186
11761187 A timestamp in RFC 3339 format
11771188
1189 format: date-time
1190
11781191 - `created_at: string`
11791192
11801193 A timestamp in RFC 3339 format
11811194
1195 format: date-time
1196
11821197 - `expires_at: string or null`
11831198
11841199 A timestamp in RFC 3339 format
11851200
1201 format: date-time
1202
11861203 - `fingerprint: string`
11871204
11881205 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 1210
11931210
11941211 - `type: "tunnel_certificate"`
11951212
1196 - `"tunnel_certificate"`
1213#### Example
11971214
1198### Example
1199
1200```http
1215```bash
12011216curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID \
12021217 -H 'anthropic-version: 2023-06-01' \
12031218 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 1219
12041219 -H "X-Api-Key: $ANTHROPIC_API_KEY"
12051220```
12061221
1207#### Response
1222##### Response (200)
12081223
12091224```json
12101225{
from line 1233
12181233}
12191234```
12201235
1221## List Tunnel Certificates
1236### List Tunnel Certificates
12221237
1223**get** `/v1/tunnels/{tunnel_id}/certificates`
1238**GET** `/v1/tunnels/{tunnel_id}/certificates`
12241239
12251240The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
12261241
12271242Lists the certificates registered on a tunnel. Archived certificates are excluded unless include_archived is set.
12281243
1229### Path Parameters
1244#### Path parameters
12301245
12311246- `tunnel_id: string`
12321247
1233### Query Parameters
1248#### Query parameters
12341249
12351250- `include_archived: optional boolean`
12361251
from line 1255
12401255
12411256 Maximum number of certificates to return per page. Defaults to 20, maximum 1000.
12421257
1258 format: int32
1259
12431260- `page: optional string`
12441261
12451262 Opaque pagination cursor from a previous `list_tunnel_certificates` response.
12461263
1247### Header Parameters
1264#### Headers
12481265
12491266- `"anthropic-beta": optional array of AnthropicBeta`
12501267
from line 1339
13221339
13231340 - `"mid-conversation-tool-changes-2026-07-01"`
13241341
1325### Returns
1342#### Returns
13261343
13271344- `data: array of BetaTunnelCertificate`
13281345
from line 1353
13361353
13371354 A timestamp in RFC 3339 format
13381355
1356 format: date-time
1357
13391358 - `created_at: string`
13401359
13411360 A timestamp in RFC 3339 format
13421361
1362 format: date-time
1363
13431364 - `expires_at: string or null`
13441365
13451366 A timestamp in RFC 3339 format
13461367
1368 format: date-time
1369
13471370 - `fingerprint: string`
13481371
13491372 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 1377
13541377
13551378 - `type: "tunnel_certificate"`
13561379
1357 - `"tunnel_certificate"`
1358
13591380- `next_page: string or null`
13601381
13611382 Pagination cursor for the next page, or null if no more results.
13621383
1363### Example
1384#### Example
13641385
1365```http
1386```bash
13661387curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates \
13671388 -H 'anthropic-version: 2023-06-01' \
13681389 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 1390
13691390 -H "X-Api-Key: $ANTHROPIC_API_KEY"
13701391```
13711392
1372#### Response
1393##### Response (200)
13731394
13741395```json
13751396{
from line 1409
13881409}
13891410```
13901411
1391## Archive Tunnel Certificate
1412### Archive Tunnel Certificate
13921413
1393**post** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive`
1414**POST** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive`
13941415
13951416The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
13961417
13971418Archives a tunnel certificate, removing it from the set Anthropic trusts for the tunnel. The certificate record is retained. Archiving the last non-archived certificate is permitted; the tunnel rejects MCP traffic until a new certificate is added.
13981419
1399### Path Parameters
1420#### Path parameters
14001421
14011422- `tunnel_id: string`
14021423
14031424- `certificate_id: string`
14041425
1405### Header Parameters
1426#### Headers
14061427
14071428- `"anthropic-beta": optional array of AnthropicBeta`
14081429
from line 1501
14801501
14811502 - `"mid-conversation-tool-changes-2026-07-01"`
14821503
1483### Returns
1504#### Returns
14841505
1485- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
1506- `BetaTunnelCertificate object`
14861507
14871508 A CA certificate attached to a tunnel.
14881509
from line 1515
14941515
14951516 A timestamp in RFC 3339 format
14961517
1518 format: date-time
1519
14971520 - `created_at: string`
14981521
14991522 A timestamp in RFC 3339 format
15001523
1524 format: date-time
1525
15011526 - `expires_at: string or null`
15021527
15031528 A timestamp in RFC 3339 format
15041529
1530 format: date-time
1531
15051532 - `fingerprint: string`
15061533
15071534 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 1539
15121539
15131540 - `type: "tunnel_certificate"`
15141541
1515 - `"tunnel_certificate"`
1542#### Example
15161543
1517### Example
1518
1519```http
1544```bash
15201545curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID/archive \
15211546 -X POST \
15221547 -H 'anthropic-version: 2023-06-01' \
from line 1549
15241549 -H "X-Api-Key: $ANTHROPIC_API_KEY"
15251550```
15261551
1527#### Response
1552##### Response (200)
15281553
15291554```json
15301555{
from line 1562
15371562 "type": "tunnel_certificate"
15381563}
15391564```
1540
1541## Domain Types
1542
1543### Beta Tunnel Certificate
1544
1545- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
1546
1547 A CA certificate attached to a tunnel.
1548
1549 - `id: string`
1550
1551 Unique identifier for the certificate, prefixed with `tcrt_`.
1552
1553 - `archived_at: string or null`
1554
1555 A timestamp in RFC 3339 format
1556
1557 - `created_at: string`
1558
1559 A timestamp in RFC 3339 format
1560
1561 - `expires_at: string or null`
1562
1563 A timestamp in RFC 3339 format
1564
1565 - `fingerprint: string`
1566
1567 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
1568
1569 - `tunnel_id: string`
1570
1571 ID of the tunnel the certificate is registered against.
1572
1573 - `type: "tunnel_certificate"`
1574
1575 - `"tunnel_certificate"`
15761565
api/beta/tunnels/archive Changed · +13 / -16 lines
# Archive Tunnel ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Archive Tunnel ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Archive Tunnel
3url: https://platform.claude.com/docs/en/api/beta/tunnels/archive
4---
1# Archive Tunnel
52
6## Archive Tunnel
3**POST** `/v1/tunnels/{tunnel_id}/archive`
74
8**post** `/v1/tunnels/{tunnel_id}/archive`
9
105The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
116
127Archives a tunnel. Archival is irreversible: every non-archived certificate on the tunnel is archived in the same operation, the hostname is retired and never re-allocated, and the tunnel token is invalidated. Retrying against an already-archived tunnel returns the existing record unchanged.
138
14### Path Parameters
9## Path parameters
1510
1611- `tunnel_id: string`
1712
18### Header Parameters
13## Headers
1914
2015- `"anthropic-beta": optional array of AnthropicBeta`
2116
from line 88
9388
9489 - `"mid-conversation-tool-changes-2026-07-01"`
9590
96### Returns
91## Returns
9792
98- `BetaTunnel object { id, archived_at, created_at, 3 more }`
93- `BetaTunnel object`
9994
10095 An MCP tunnel.
10196
from line 102
107102
108103 A timestamp in RFC 3339 format
109104
105 format: date-time
106
110107 - `created_at: string`
111108
112109 A timestamp in RFC 3339 format
113110
111 format: date-time
112
114113 - `display_name: string or null`
115114
116115 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 120
121120
122121 - `type: "tunnel"`
123122
124 - `"tunnel"`
123## Example
125124
126### Example
127
128```http
125```bash
129126curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/archive \
130127 -X POST \
131128 -H 'anthropic-version: 2023-06-01' \
from line 130
133130 -H "X-Api-Key: $ANTHROPIC_API_KEY"
134131```
135132
136#### Response
133### Response (200)
137134
138135```json
139136{
api/beta/tunnels/certificates Changed · +61 / -42 lines
### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types
from line 1
1---
2title: Certificates
3url: https://platform.claude.com/docs/en/api/beta/tunnels/certificates
4---
5
61# Certificates
72
83## Create Tunnel Certificate
94
10**post** `/v1/tunnels/{tunnel_id}/certificates`
5**POST** `/v1/tunnels/{tunnel_id}/certificates`
116
127The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
138
149Registers a public CA certificate on a tunnel. Anthropic verifies the gateway's server certificate against this CA when it terminates the inner TLS session. A tunnel holds at most two non-archived certificates.
1510
16### Path Parameters
11### Path parameters
1712
1813- `tunnel_id: string`
1914
20### Header Parameters
15### Headers
2116
2217- `"anthropic-beta": optional array of AnthropicBeta`
2318
from line 90
9590
9691 - `"mid-conversation-tool-changes-2026-07-01"`
9792
98### Body Parameters
93### Body parameters
9994
10095- `ca_certificate_pem: string`
10196
10297 PEM-encoded X.509 CA certificate. Must contain exactly one certificate and no private-key material. Maximum 8KB.
10398
99 maxLength: 8192
100
104101### Returns
105102
106- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
103- `BetaTunnelCertificate object`
107104
108105 A CA certificate attached to a tunnel.
109106
from line 112
115112
116113 A timestamp in RFC 3339 format
117114
115 format: date-time
116
118117 - `created_at: string`
119118
120119 A timestamp in RFC 3339 format
121120
121 format: date-time
122
122123 - `expires_at: string or null`
123124
124125 A timestamp in RFC 3339 format
125126
127 format: date-time
128
126129 - `fingerprint: string`
127130
128131 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 136
133136
134137 - `type: "tunnel_certificate"`
135138
136 - `"tunnel_certificate"`
137
138139### Example
139140
140```http
141```bash
141142curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates \
142143 -H 'Content-Type: application/json' \
143144 -H 'anthropic-version: 2023-06-01' \
from line 149
148149 }'
149150```
150151
151#### Response
152#### Response (200)
152153
153154```json
154155{
from line 165
164165
165166## Get Tunnel Certificate
166167
167**get** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}`
168**GET** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}`
168169
169170The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
170171
171172Fetches a tunnel certificate by ID.
172173
173### Path Parameters
174### Path parameters
174175
175176- `tunnel_id: string`
176177
177178- `certificate_id: string`
178179
179### Header Parameters
180### Headers
180181
181182- `"anthropic-beta": optional array of AnthropicBeta`
182183
from line 257
256257
257258### Returns
258259
259- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
260- `BetaTunnelCertificate object`
260261
261262 A CA certificate attached to a tunnel.
262263
from line 269
268269
269270 A timestamp in RFC 3339 format
270271
272 format: date-time
273
271274 - `created_at: string`
272275
273276 A timestamp in RFC 3339 format
274277
278 format: date-time
279
275280 - `expires_at: string or null`
276281
277282 A timestamp in RFC 3339 format
278283
284 format: date-time
285
279286 - `fingerprint: string`
280287
281288 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 293
286293
287294 - `type: "tunnel_certificate"`
288295
289 - `"tunnel_certificate"`
290
291296### Example
292297
293```http
298```bash
294299curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID \
295300 -H 'anthropic-version: 2023-06-01' \
296301 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 302
297302 -H "X-Api-Key: $ANTHROPIC_API_KEY"
298303```
299304
300#### Response
305#### Response (200)
301306
302307```json
303308{
from line 318
313318
314319## List Tunnel Certificates
315320
316**get** `/v1/tunnels/{tunnel_id}/certificates`
321**GET** `/v1/tunnels/{tunnel_id}/certificates`
317322
318323The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
319324
320325Lists the certificates registered on a tunnel. Archived certificates are excluded unless include_archived is set.
321326
322### Path Parameters
327### Path parameters
323328
324329- `tunnel_id: string`
325330
326### Query Parameters
331### Query parameters
327332
328333- `include_archived: optional boolean`
329334
from line 338
333338
334339 Maximum number of certificates to return per page. Defaults to 20, maximum 1000.
335340
341 format: int32
342
336343- `page: optional string`
337344
338345 Opaque pagination cursor from a previous `list_tunnel_certificates` response.
339346
340### Header Parameters
347### Headers
341348
342349- `"anthropic-beta": optional array of AnthropicBeta`
343350
from line 436
429436
430437 A timestamp in RFC 3339 format
431438
439 format: date-time
440
432441 - `created_at: string`
433442
434443 A timestamp in RFC 3339 format
435444
445 format: date-time
446
436447 - `expires_at: string or null`
437448
438449 A timestamp in RFC 3339 format
439450
451 format: date-time
452
440453 - `fingerprint: string`
441454
442455 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 460
447460
448461 - `type: "tunnel_certificate"`
449462
450 - `"tunnel_certificate"`
451
452463- `next_page: string or null`
453464
454465 Pagination cursor for the next page, or null if no more results.
from line 466
455466
456467### Example
457468
458```http
469```bash
459470curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates \
460471 -H 'anthropic-version: 2023-06-01' \
461472 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 473
462473 -H "X-Api-Key: $ANTHROPIC_API_KEY"
463474```
464475
465#### Response
476#### Response (200)
466477
467478```json
468479{
from line 494
483494
484495## Archive Tunnel Certificate
485496
486**post** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive`
497**POST** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive`
487498
488499The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
489500
490501Archives a tunnel certificate, removing it from the set Anthropic trusts for the tunnel. The certificate record is retained. Archiving the last non-archived certificate is permitted; the tunnel rejects MCP traffic until a new certificate is added.
491502
492### Path Parameters
503### Path parameters
493504
494505- `tunnel_id: string`
495506
496507- `certificate_id: string`
497508
498### Header Parameters
509### Headers
499510
500511- `"anthropic-beta": optional array of AnthropicBeta`
501512
from line 586
575586
576587### Returns
577588
578- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
589- `BetaTunnelCertificate object`
579590
580591 A CA certificate attached to a tunnel.
581592
from line 598
587598
588599 A timestamp in RFC 3339 format
589600
601 format: date-time
602
590603 - `created_at: string`
591604
592605 A timestamp in RFC 3339 format
593606
607 format: date-time
608
594609 - `expires_at: string or null`
595610
596611 A timestamp in RFC 3339 format
597612
613 format: date-time
614
598615 - `fingerprint: string`
599616
600617 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 622
605622
606623 - `type: "tunnel_certificate"`
607624
608 - `"tunnel_certificate"`
609
610625### Example
611626
612```http
627```bash
613628curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID/archive \
614629 -X POST \
615630 -H 'anthropic-version: 2023-06-01' \
from line 632
617632 -H "X-Api-Key: $ANTHROPIC_API_KEY"
618633```
619634
620#### Response
635#### Response (200)
621636
622637```json
623638{
from line 646
631646}
632647```
633648
634## Domain Types
649## Domain types
635650
636651### Beta Tunnel Certificate
637652
638- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
653- `BetaTunnelCertificate object`
639654
640655 A CA certificate attached to a tunnel.
641656
from line 662
647662
648663 A timestamp in RFC 3339 format
649664
665 format: date-time
666
650667 - `created_at: string`
651668
652669 A timestamp in RFC 3339 format
653670
671 format: date-time
672
654673 - `expires_at: string or null`
655674
656675 A timestamp in RFC 3339 format
657676
677 format: date-time
678
658679 - `fingerprint: string`
659680
660681 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 685
664685 ID of the tunnel the certificate is registered against.
665686
666687 - `type: "tunnel_certificate"`
667
668 - `"tunnel_certificate"`
669688