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
201-225 of 377, page 9 of 16This capture is too large to show at once. Changes 201-225 of 377 are below, significant first; the rest are on the following screens.
api/beta/messages/batches Changed · +1988 / -1419 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 ## Domain types ### 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 ## Domain Types
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
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: Batches
3url: https://platform.claude.com/docs/en/api/beta/messages/batches
4---
5
61# Batches
72
83## Create a Message Batch
94
10**post** `/v1/messages/batches`
5**POST** `/v1/messages/batches`
116
127Send a batch of Message creation requests.
138
from line 10
1510
1611Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
1712
18### Header Parameters
13### Headers
1914
2015- `"anthropic-beta": optional array of AnthropicBeta`
2116
from line 92
9792
9893 The user profile ID to attribute the requests in this batch to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header. Applies to every request in the batch; an individual request whose `user_profile_id` body field conflicts with this header is errored.
9994
100### Body Parameters
101
102- `requests: array of object { custom_id, params }`
95### Body parameters
96
97- `requests: array of object`
10398
10499 List of requests for prompt completion. Each is an individual request to create a Message.
105100
101 maxItems: 100000, minItems: 1
102
106103 - `custom_id: string`
107104
108105 Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.
109106
110107 Must be unique for each request within the Message Batch.
111108
112 - `params: object { max_tokens, messages, model, 22 more }`
109 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,64}$
110
111 - `params: object`
113112
114113 Messages API creation parameters for the individual request.
115114
from line 123
124123 Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.
125124
126125 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
126
127 minimum: 0
127128
128129 - `messages: array of BetaMessageParam`
129130
from line 183
182183
183184 - `array of BetaContentBlockParam`
184185
185 - `BetaTextBlockParam object { text, type, cache_control, citations }`
186 - `BetaTextBlockParam object`
186187
187188 - `text: string`
188189
190 minLength: 1
191
189192 - `type: "text"`
190193
191 - `"text"`
192
193194 - `cache_control: optional BetaCacheControlEphemeral or null`
194195
195196 Create a cache control breakpoint at this content block.
196197
197198 - `type: "ephemeral"`
198
199 - `"ephemeral"`
200199
201200 - `ttl: optional "5m" or "1h"`
202201
from line 214
215214
216215 - `citations: optional array of BetaTextCitationParam or null`
217216
218 - `BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
217 - `BetaCitationCharLocationParam object`
219218
220219 - `cited_text: string`
221220
222221 - `document_index: number`
223222
223 minimum: 0
224
224225 - `document_title: string or null`
225226
227 maxLength: 500, minLength: 1
228
226229 - `end_char_index: number`
227230
228231 - `start_char_index: number`
229232
233 minimum: 0
234
230235 - `type: "char_location"`
231236
232 - `"char_location"`
233
234 - `BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
237 - `BetaCitationPageLocationParam object`
235238
236239 - `cited_text: string`
237240
238241 - `document_index: number`
239242
243 minimum: 0
244
240245 - `document_title: string or null`
241246
247 maxLength: 500, minLength: 1
248
242249 - `end_page_number: number`
243250
244251 - `start_page_number: number`
245252
253 minimum: 1
254
246255 - `type: "page_location"`
247256
248 - `"page_location"`
249
250 - `BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
257 - `BetaCitationContentBlockLocationParam object`
251258
252259 - `cited_text: string`
253260
from line 264
257264
258265 - `document_index: number`
259266
267 minimum: 0
268
260269 - `document_title: string or null`
261270
271 maxLength: 500, minLength: 1
272
262273 - `end_block_index: number`
263274
264275 Exclusive 0-based end index of the cited block range in the source's `content` array.
from line 280
269280
270281 0-based index of the first cited block in the source's `content` array.
271282
283 minimum: 0
284
272285 - `type: "content_block_location"`
273286
274 - `"content_block_location"`
275
276 - `BetaCitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
287 - `BetaCitationWebSearchResultLocationParam object`
277288
278289 - `cited_text: string`
279290
from line 292
281292
282293 - `title: string or null`
283294
295 maxLength: 512, minLength: 1
296
284297 - `type: "web_search_result_location"`
285298
286 - `"web_search_result_location"`
287
288299 - `url: string`
289300
290 - `BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
301 minLength: 1
302
303 - `BetaCitationSearchResultLocationParam object`
291304
292305 - `cited_text: string`
293306
from line 320
307320
308321 Counted separately from `document_index`; server-side web search results are not included in this count.
309322
323 minimum: 0
324
310325 - `source: string`
311326
312327 - `start_block_index: number`
313328
314329 0-based index of the first cited block in the source's `content` array.
315330
331 minimum: 0
332
316333 - `title: string or null`
317334
318335 - `type: "search_result_location"`
319336
320 - `"search_result_location"`
321
322 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
337 - `BetaImageBlockParam object`
323338
324339 - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource`
325340
326 - `BetaBase64ImageSource object { data, media_type, type }`
341 - `BetaBase64ImageSource object`
327342
328343 - `data: string`
329344
345 format: byte
346
330347 - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
331348
332349 - `"image/jpeg"`
from line 356
339356
340357 - `type: "base64"`
341358
342 - `"base64"`
343
344 - `BetaURLImageSource object { type, url }`
359 - `BetaURLImageSource object`
345360
346361 - `type: "url"`
347362
348 - `"url"`
349
350363 - `url: string`
351364
352 - `BetaFileImageSource object { file_id, type }`
365 - `BetaFileImageSource object`
353366
354367 - `file_id: string`
355368
356369 - `type: "file"`
357370
358 - `"file"`
359
360371 - `type: "image"`
361372
362 - `"image"`
363
364373 - `cache_control: optional BetaCacheControlEphemeral or null`
365374
366375 Create a cache control breakpoint at this content block.
from line 386
377386
378387 - `"error"`
379388
380 - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }`
389 - `BetaRequestDocumentBlock object`
381390
382391 - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more`
383392
384 - `BetaBase64PDFSource object { data, media_type, type }`
393 - `BetaBase64PDFSource object`
385394
386395 - `data: string`
387396
397 format: byte
398
388399 - `media_type: "application/pdf"`
389400
390 - `"application/pdf"`
391
392401 - `type: "base64"`
393402
394 - `"base64"`
395
396 - `BetaPlainTextSource object { data, media_type, type }`
403 - `BetaPlainTextSource object`
397404
398405 - `data: string`
399406
400407 - `media_type: "text/plain"`
401408
402 - `"text/plain"`
403
404409 - `type: "text"`
405410
406 - `"text"`
407
408 - `BetaContentBlockSource object { content, type }`
411 - `BetaContentBlockSource object`
409412
410413 - `content: string or array of BetaContentBlockSourceContent`
411414
from line 416
413416
414417 - `BetaContentBlockSourceContent = array of BetaContentBlockSourceContent`
415418
416 - `BetaTextBlockParam object { text, type, cache_control, citations }`
417
418 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
419 - `BetaTextBlockParam object`
420
421 - `BetaImageBlockParam object`
419422
420423 - `type: "content"`
421424
422 - `"content"`
423
424 - `BetaURLPDFSource object { type, url }`
425 - `BetaURLPDFSource object`
425426
426427 - `type: "url"`
427428
428 - `"url"`
429
430429 - `url: string`
431430
432 - `BetaFileDocumentSource object { file_id, type }`
431 - `BetaFileDocumentSource object`
433432
434433 - `file_id: string`
435434
436435 - `type: "file"`
437436
438 - `"file"`
439
440437 - `type: "document"`
441438
442 - `"document"`
443
444439 - `cache_control: optional BetaCacheControlEphemeral or null`
445440
446441 Create a cache control breakpoint at this content block.
from line 446
451446
452447 - `context: optional string or null`
453448
449 minLength: 1
450
454451 - `title: optional string or null`
455452
456 - `BetaSearchResultBlockParam object { content, source, title, 3 more }`
453 maxLength: 500, minLength: 1
454
455 - `BetaSearchResultBlockParam object`
457456
458457 - `content: array of BetaTextBlockParam`
459458
460459 - `text: string`
461460
461 minLength: 1
462
462463 - `type: "text"`
463464
464465 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 474
473474
474475 - `type: "search_result"`
475476
476 - `"search_result"`
477
478477 - `cache_control: optional BetaCacheControlEphemeral or null`
479478
480479 Create a cache control breakpoint at this content block.
481480
482481 - `citations: optional BetaCitationsConfigParam`
483482
484 - `BetaThinkingBlockParam object { signature, thinking, type }`
483 - `BetaThinkingBlockParam object`
485484
486485 - `signature: string`
487486
from line 494
495494
496495 - `type: "thinking"`
497496
498 - `"thinking"`
499
500 - `BetaRedactedThinkingBlockParam object { data, type }`
497 - `BetaRedactedThinkingBlockParam object`
501498
502499 - `data: string`
503500
from line 502
505502
506503 - `type: "redacted_thinking"`
507504
508 - `"redacted_thinking"`
509
510 - `BetaToolUseBlockParam object { id, input, name, 4 more }`
505 - `BetaToolUseBlockParam object`
511506
512507 - `id: string`
513508
509 pattern: ^[a-zA-Z0-9_-]+$
510
514511 - `input: map[unknown]`
515512
516513 - `name: string`
517514
515 maxLength: 200, minLength: 1
516
518517 - `type: "tool_use"`
519518
520 - `"tool_use"`
521
522519 - `cache_control: optional BetaCacheControlEphemeral or null`
523520
524521 Create a cache control breakpoint at this content block.
from line 524
527524
528525 Tool invocation directly from the model.
529526
530 - `BetaDirectCaller object { type }`
527 - `BetaDirectCaller object`
531528
532529 Tool invocation directly from the model.
533530
534531 - `type: "direct"`
535532
536 - `"direct"`
537
538 - `BetaServerToolCaller object { tool_id, type }`
533 - `BetaServerToolCaller object`
539534
540535 Tool invocation generated by a server-side tool.
541536
542537 - `tool_id: string`
543538
539 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
540
544541 - `type: "code_execution_20250825"`
545542
546 - `"code_execution_20250825"`
547
548 - `BetaServerToolCaller20260120 object { tool_id, type }`
543 - `BetaServerToolCaller20260120 object`
549544
550545 - `tool_id: string`
551546
547 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
548
552549 - `type: "code_execution_20260120"`
553550
554 - `"code_execution_20260120"`
555
556551 - `toolset_name: optional string or null`
557552
558553 For a toolset member tool_use, the toolset family this member belongs to.
559554
560 - `BetaToolResultBlockParam object { tool_use_id, type, cache_control, 3 more }`
555 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
556
557 - `BetaToolResultBlockParam object`
561558
562559 - `tool_use_id: string`
563560
561 pattern: ^[a-zA-Z0-9_-]+$
562
564563 - `type: "tool_result"`
565564
566 - `"tool_result"`
567
568565 - `cache_control: optional BetaCacheControlEphemeral or null`
569566
570567 Create a cache control breakpoint at this content block.
from line 572
575572
576573 - `array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 3 more`
577574
578 - `BetaTextBlockParam object { text, type, cache_control, citations }`
579
580 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
581
582 - `BetaSearchResultBlockParam object { content, source, title, 3 more }`
583
584 - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }`
585
586 - `BetaToolReferenceBlockParam object { tool_name, type, cache_control }`
575 - `BetaTextBlockParam object`
576
577 - `BetaImageBlockParam object`
578
579 - `BetaSearchResultBlockParam object`
580
581 - `BetaRequestDocumentBlock object`
582
583 - `BetaToolReferenceBlockParam object`
587584
588585 Tool reference block that can be included in tool_result content.
589586
590587 - `tool_name: string`
591588
589 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
590
592591 - `type: "tool_reference"`
593592
594 - `"tool_reference"`
595
596593 - `cache_control: optional BetaCacheControlEphemeral or null`
597594
598595 Create a cache control breakpoint at this content block.
599596
600 - `BetaBrowserStateBlockParam object { tabs, type, cache_control, state_changes }`
597 - `BetaBrowserStateBlockParam object`
601598
602599 The caller's browser state after a browser toolset member call —
603600 the full inventory of open tabs, which tab is active, and any side
from line 608
611608
612609 All tabs open in the browser after this call — the full inventory, not a delta. May be empty. Whenever non-empty, exactly one entry carries `active: true`.
613610
611 maxItems: 100
612
614613 - `tab_id: string`
615614
616615 The caller-assigned identifier for this tab, unique within the inventory.
617616
617 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
618
618619 - `title: string`
619620
620621 The title of the page the tab is showing. May be empty.
621622
623 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
624
622625 - `url: string`
623626
624627 The URL of the page the tab is showing. May be empty.
625628
629 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
630
626631 - `active: optional boolean`
627632
628633 Whether this tab is the active tab after this call. Whenever `tabs` is non-empty, exactly one entry is marked `active: true`.
629634
630635 - `type: "browser_state"`
631636
632 - `"browser_state"`
633
634637 - `cache_control: optional BetaCacheControlEphemeral or null`
635638
636639 Create a cache control breakpoint at this content block.
from line 642
639642
640643 Tabs opened and download state changes during this call. "Nothing to report" is expressed by omitting the field, never by an empty list.
641644
642 - `BetaBrowserStateChangeTabOpened object { tab_id, type }`
645 maxItems: 200, minItems: 1
646
647 - `BetaBrowserStateChangeTabOpened object`
643648
644649 A tab this call's execution opened that remains open at its end —
645650 the creation delta of the `tabs` inventory, not an event log.
from line 658
653658
654659 The `tab_id` of the opened tab, present in `tabs`.
655660
661 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
662
656663 - `type: "tab_opened"`
657664
658 - `"tab_opened"`
659
660 - `BetaBrowserStateChangeDownloadStarted object { download_id, type, url }`
665 - `BetaBrowserStateChangeDownloadStarted object`
661666
662667 A file download that started during this call.
663668
from line 670
665670
666671 The caller-assigned identifier for this download, stable across the state changes reporting it.
667672
673 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
674
668675 - `type: "download_started"`
669676
670 - `"download_started"`
671
672677 - `url: string`
673678
674679 The final post-redirect URL the download was served from.
675680
676 - `BetaBrowserStateChangeDownloadCompleted object { download_id, type, url, 2 more }`
681 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
682
683 - `BetaBrowserStateChangeDownloadCompleted object`
677684
678685 A file download that finished during this call, reported with the
679686 same `download_id` as its `download_started` — or without a prior
from line 691
684691
685692 The caller-assigned identifier for this download, stable across the state changes reporting it.
686693
694 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
695
687696 - `type: "download_completed"`
688697
689 - `"download_completed"`
690
691698 - `url: string`
692699
693700 The final post-redirect URL the download was served from.
694701
702 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
703
695704 - `path: optional string or null`
696705
697706 Where the executor saved the file, on the executor's filesystem. Only included when another tool in the same environment can read the file at that path.
698707
708 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096
709
699710 - `size_bytes: optional number or null`
700711
701712 The completed download's size.
702713
703 - `BetaBrowserStateChangeDownloadFailed object { download_id, type, url, error }`
714 minimum: 0
715
716 - `BetaBrowserStateChangeDownloadFailed object`
704717
705718 A file download that failed — or was cancelled — during this call.
706719
from line 721
708721
709722 The caller-assigned identifier for this download, stable across the state changes reporting it.
710723
724 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
725
711726 - `type: "download_failed"`
712727
713 - `"download_failed"`
714
715728 - `url: string`
716729
717730 The final post-redirect URL the download was served from.
718731
732 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
733
719734 - `error: optional string or null`
720735
721736 The failure or cancellation detail, when known.
722737
738 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096
739
723740 - `is_error: optional boolean`
724741
725742 - `toolset_name: optional string or null`
726743
727744 For a toolset member tool_result, the toolset family of the paired tool_use.
728745
729 - `BetaServerToolUseBlockParam object { id, input, name, 3 more }`
746 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
747
748 - `BetaServerToolUseBlockParam object`
730749
731750 - `id: string`
732751
752 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
753
733754 - `input: map[unknown]`
734755
735756 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 773
752773
753774 - `type: "server_tool_use"`
754775
755 - `"server_tool_use"`
756
757776 - `cache_control: optional BetaCacheControlEphemeral or null`
758777
759778 Create a cache control breakpoint at this content block.
from line 781
762781
763782 Tool invocation directly from the model.
764783
765 - `BetaDirectCaller object { type }`
784 - `BetaDirectCaller object`
766785
767786 Tool invocation directly from the model.
768787
769 - `BetaServerToolCaller object { tool_id, type }`
788 - `BetaServerToolCaller object`
770789
771790 Tool invocation generated by a server-side tool.
772791
773 - `BetaServerToolCaller20260120 object { tool_id, type }`
774
775 - `BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }`
792 - `BetaServerToolCaller20260120 object`
793
794 - `BetaWebSearchToolResultBlockParam object`
776795
777796 - `content: BetaWebSearchToolResultBlockParamContent`
778797
from line 803
784803
785804 - `type: "web_search_result"`
786805
787 - `"web_search_result"`
788
789806 - `url: string`
790807
791808 - `page_age: optional string or null`
792809
793 - `BetaWebSearchToolRequestError object { error_code, type }`
810 - `BetaWebSearchToolRequestError object`
794811
795812 - `error_code: BetaWebSearchToolResultErrorCode`
796813
from line 825
808825
809826 - `type: "web_search_tool_result_error"`
810827
811 - `"web_search_tool_result_error"`
812
813828 - `tool_use_id: string`
814829
830 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
831
815832 - `type: "web_search_tool_result"`
816833
817 - `"web_search_tool_result"`
818
819834 - `cache_control: optional BetaCacheControlEphemeral or null`
820835
821836 Create a cache control breakpoint at this content block.
from line 839
824839
825840 Tool invocation directly from the model.
826841
827 - `BetaDirectCaller object { type }`
842 - `BetaDirectCaller object`
828843
829844 Tool invocation directly from the model.
830845
831 - `BetaServerToolCaller object { tool_id, type }`
846 - `BetaServerToolCaller object`
832847
833848 Tool invocation generated by a server-side tool.
834849
835 - `BetaServerToolCaller20260120 object { tool_id, type }`
836
837 - `BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }`
850 - `BetaServerToolCaller20260120 object`
851
852 - `BetaWebFetchToolResultBlockParam object`
838853
839854 - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam`
840855
841 - `BetaWebFetchToolResultErrorBlockParam object { error_code, type }`
856 - `BetaWebFetchToolResultErrorBlockParam object`
842857
843858 - `error_code: BetaWebFetchToolResultErrorCode`
844859
from line 877
862877
863878 - `type: "web_fetch_tool_result_error"`
864879
865 - `"web_fetch_tool_result_error"`
866
867 - `BetaWebFetchBlockParam object { content, type, url, retrieved_at }`
880 - `BetaWebFetchBlockParam object`
868881
869882 - `content: BetaRequestDocumentBlock`
870883
871884 - `type: "web_fetch_result"`
872885
873 - `"web_fetch_result"`
874
875886 - `url: string`
876887
877888 Fetched content URL
from line 893
882893
883894 - `tool_use_id: string`
884895
896 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
897
885898 - `type: "web_fetch_tool_result"`
886899
887 - `"web_fetch_tool_result"`
888
889900 - `cache_control: optional BetaCacheControlEphemeral or null`
890901
891902 Create a cache control breakpoint at this content block.
from line 905
894905
895906 Tool invocation directly from the model.
896907
897 - `BetaDirectCaller object { type }`
908 - `BetaDirectCaller object`
898909
899910 Tool invocation directly from the model.
900911
901 - `BetaServerToolCaller object { tool_id, type }`
912 - `BetaServerToolCaller object`
902913
903914 Tool invocation generated by a server-side tool.
904915
905 - `BetaServerToolCaller20260120 object { tool_id, type }`
906
907 - `BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }`
916 - `BetaServerToolCaller20260120 object`
917
918 - `BetaAdvisorToolResultBlockParam object`
908919
909920 - `content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam`
910921
911 - `BetaAdvisorToolResultErrorParam object { error_code, type }`
922 - `BetaAdvisorToolResultErrorParam object`
912923
913924 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
914925
from line 939
928939
929940 - `type: "advisor_tool_result_error"`
930941
931 - `"advisor_tool_result_error"`
932
933 - `BetaAdvisorResultBlockParam object { text, type, stop_reason }`
942 - `BetaAdvisorResultBlockParam object`
934943
935944 - `text: string`
936945
937946 - `type: "advisor_result"`
938947
939 - `"advisor_result"`
940
941948 - `stop_reason: optional string or null`
942949
943 - `BetaAdvisorRedactedResultBlockParam object { encrypted_content, type, stop_reason }`
950 - `BetaAdvisorRedactedResultBlockParam object`
944951
945952 - `encrypted_content: string`
946953
from line 955
948955
949956 - `type: "advisor_redacted_result"`
950957
951 - `"advisor_redacted_result"`
952
953958 - `stop_reason: optional string or null`
954959
955960 - `tool_use_id: string`
956961
962 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
963
957964 - `type: "advisor_tool_result"`
958965
959 - `"advisor_tool_result"`
960
961966 - `cache_control: optional BetaCacheControlEphemeral or null`
962967
963968 Create a cache control breakpoint at this content block.
964969
965 - `BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
970 - `BetaCodeExecutionToolResultBlockParam object`
966971
967972 - `content: BetaCodeExecutionToolResultBlockParamContent`
968973
969974 Code execution result with encrypted stdout for PFC + web_search results.
970975
971 - `BetaCodeExecutionToolResultErrorParam object { error_code, type }`
976 - `BetaCodeExecutionToolResultErrorParam object`
972977
973978 - `error_code: BetaCodeExecutionToolResultErrorCode`
974979
from line 987
982987
983988 - `type: "code_execution_tool_result_error"`
984989
985 - `"code_execution_tool_result_error"`
986
987 - `BetaCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }`
990 - `BetaCodeExecutionResultBlockParam object`
988991
989992 - `content: array of BetaCodeExecutionOutputBlockParam`
990993
from line 995
992995
993996 - `type: "code_execution_output"`
994997
995 - `"code_execution_output"`
996
997998 - `return_code: number`
998999
9991000 - `stderr: string`
from line 1003
10021003
10031004 - `type: "code_execution_result"`
10041005
1005 - `"code_execution_result"`
1006
1007 - `BetaEncryptedCodeExecutionResultBlockParam object { content, encrypted_stdout, return_code, 2 more }`
1006 - `BetaEncryptedCodeExecutionResultBlockParam object`
10081007
10091008 Code execution result with encrypted stdout for PFC + web_search results.
10101009
from line 1021
10221021
10231022 - `type: "encrypted_code_execution_result"`
10241023
1025 - `"encrypted_code_execution_result"`
1026
10271024 - `tool_use_id: string`
10281025
1026 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1027
10291028 - `type: "code_execution_tool_result"`
10301029
1031 - `"code_execution_tool_result"`
1032
10331030 - `cache_control: optional BetaCacheControlEphemeral or null`
10341031
10351032 Create a cache control breakpoint at this content block.
10361033
1037 - `BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1034 - `BetaBashCodeExecutionToolResultBlockParam object`
10381035
10391036 - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam`
10401037
1041 - `BetaBashCodeExecutionToolResultErrorParam object { error_code, type }`
1038 - `BetaBashCodeExecutionToolResultErrorParam object`
10421039
10431040 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
10441041
from line 1051
10541051
10551052 - `type: "bash_code_execution_tool_result_error"`
10561053
1057 - `"bash_code_execution_tool_result_error"`
1058
1059 - `BetaBashCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }`
1054 - `BetaBashCodeExecutionResultBlockParam object`
10601055
10611056 - `content: array of BetaBashCodeExecutionOutputBlockParam`
10621057
from line 1059
10641059
10651060 - `type: "bash_code_execution_output"`
10661061
1067 - `"bash_code_execution_output"`
1068
10691062 - `return_code: number`
10701063
10711064 - `stderr: string`
from line 1067
10741067
10751068 - `type: "bash_code_execution_result"`
10761069
1077 - `"bash_code_execution_result"`
1078
10791070 - `tool_use_id: string`
10801071
1072 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1073
10811074 - `type: "bash_code_execution_tool_result"`
10821075
1083 - `"bash_code_execution_tool_result"`
1084
10851076 - `cache_control: optional BetaCacheControlEphemeral or null`
10861077
10871078 Create a cache control breakpoint at this content block.
10881079
1089 - `BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1080 - `BetaTextEditorCodeExecutionToolResultBlockParam object`
10901081
10911082 - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam`
10921083
1093 - `BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }`
1084 - `BetaTextEditorCodeExecutionToolResultErrorParam object`
10941085
10951086 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
10961087
from line 1097
11061097
11071098 - `type: "text_editor_code_execution_tool_result_error"`
11081099
1109 - `"text_editor_code_execution_tool_result_error"`
1110
11111100 - `error_message: optional string or null`
11121101
1113 - `BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }`
1102 - `BetaTextEditorCodeExecutionViewResultBlockParam object`
11141103
11151104 - `content: string`
11161105
from line 1113
11241113
11251114 - `type: "text_editor_code_execution_view_result"`
11261115
1127 - `"text_editor_code_execution_view_result"`
1128
11291116 - `num_lines: optional number or null`
11301117
11311118 - `start_line: optional number or null`
11321119
11331120 - `total_lines: optional number or null`
11341121
1135 - `BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }`
1122 - `BetaTextEditorCodeExecutionCreateResultBlockParam object`
11361123
11371124 - `is_file_update: boolean`
11381125
11391126 - `type: "text_editor_code_execution_create_result"`
11401127
1141 - `"text_editor_code_execution_create_result"`
1142
1143 - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }`
1128 - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object`
11441129
11451130 - `type: "text_editor_code_execution_str_replace_result"`
11461131
1147 - `"text_editor_code_execution_str_replace_result"`
1148
11491132 - `lines: optional array of string or null`
11501133
11511134 - `new_lines: optional number or null`
from line 1141
11581141
11591142 - `tool_use_id: string`
11601143
1144 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1145
11611146 - `type: "text_editor_code_execution_tool_result"`
11621147
1163 - `"text_editor_code_execution_tool_result"`
1164
11651148 - `cache_control: optional BetaCacheControlEphemeral or null`
11661149
11671150 Create a cache control breakpoint at this content block.
11681151
1169 - `BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1152 - `BetaToolSearchToolResultBlockParam object`
11701153
11711154 - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam`
11721155
1173 - `BetaToolSearchToolResultErrorParam object { error_code, type, error_message }`
1156 - `BetaToolSearchToolResultErrorParam object`
11741157
11751158 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
11761159
from line 1167
11841167
11851168 - `type: "tool_search_tool_result_error"`
11861169
1187 - `"tool_search_tool_result_error"`
1188
11891170 - `error_message: optional string or null`
11901171
1191 - `BetaToolSearchToolSearchResultBlockParam object { tool_references, type }`
1172 - `BetaToolSearchToolSearchResultBlockParam object`
11921173
11931174 - `tool_references: array of BetaToolReferenceBlockParam`
11941175
11951176 - `tool_name: string`
11961177
1178 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
1179
11971180 - `type: "tool_reference"`
11981181
11991182 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1185
12021185
12031186 - `type: "tool_search_tool_search_result"`
12041187
1205 - `"tool_search_tool_search_result"`
1206
12071188 - `tool_use_id: string`
12081189
1190 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1191
12091192 - `type: "tool_search_tool_result"`
12101193
1211 - `"tool_search_tool_result"`
1212
12131194 - `cache_control: optional BetaCacheControlEphemeral or null`
12141195
12151196 Create a cache control breakpoint at this content block.
12161197
1217 - `BetaMCPToolUseBlockParam object { id, input, name, 3 more }`
1198 - `BetaMCPToolUseBlockParam object`
12181199
12191200 - `id: string`
12201201
1202 pattern: ^[a-zA-Z0-9_-]+$
1203
12211204 - `input: map[unknown]`
12221205
12231206 - `name: string`
from line 1211
12281211
12291212 - `type: "mcp_tool_use"`
12301213
1231 - `"mcp_tool_use"`
1232
12331214 - `cache_control: optional BetaCacheControlEphemeral or null`
12341215
12351216 Create a cache control breakpoint at this content block.
12361217
1237 - `BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }`
1218 - `BetaRequestMCPToolResultBlockParam object`
12381219
12391220 - `tool_use_id: string`
12401221
1222 pattern: ^[a-zA-Z0-9_-]+$
1223
12411224 - `type: "mcp_tool_result"`
12421225
1243 - `"mcp_tool_result"`
1244
12451226 - `cache_control: optional BetaCacheControlEphemeral or null`
12461227
12471228 Create a cache control breakpoint at this content block.
from line 1235
12541235
12551236 - `text: string`
12561237
1238 minLength: 1
1239
12571240 - `type: "text"`
12581241
12591242 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1247
12641247
12651248 - `is_error: optional boolean`
12661249
1267 - `BetaContainerUploadBlockParam object { file_id, type, cache_control }`
1250 - `BetaContainerUploadBlockParam object`
12681251
12691252 A content block that represents a file to be uploaded to the container
12701253 Files uploaded via this block will be available in the container's input directory.
from line 1256
12731256
12741257 - `type: "container_upload"`
12751258
1276 - `"container_upload"`
1277
12781259 - `cache_control: optional BetaCacheControlEphemeral or null`
12791260
12801261 Create a cache control breakpoint at this content block.
12811262
1282 - `BetaCompactionBlockParam object { type, cache_control, content, encrypted_content }`
1263 - `BetaCompactionBlockParam object`
12831264
12841265 A compaction block containing summary of previous context.
12851266
from line 1272
12911272
12921273 - `type: "compaction"`
12931274
1294 - `"compaction"`
1295
12961275 - `cache_control: optional BetaCacheControlEphemeral or null`
12971276
12981277 Create a cache control breakpoint at this content block.
from line 1284
13051284
13061285 Opaque metadata from prior compaction, to be round-tripped verbatim
13071286
1308 - `BetaRequestToolAdditionBlock object { tool, type, cache_control }`
1287 - `BetaRequestToolAdditionBlock object`
13091288
13101289 Mid-conversation directive to surface a declared tool.
13111290
from line 1299
13201299 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13211300 `mcp_toolset_reference` for those.
13221301
1323 - `BetaToolChangeToolReference object { name, type }`
1302 - `BetaToolChangeToolReference object`
13241303
13251304 Reference to a single tool the caller declared directly in
13261305 `tools[]`. Does not accept the composed `{server}_{name}` form the
from line 1308
13291308
13301309 - `name: string`
13311310
1311 pattern: ^[a-zA-Z0-9_-]{1,128}$
1312
13321313 - `type: "tool_reference"`
13331314
1334 - `"tool_reference"`
1335
1336 - `BetaToolChangeMCPToolReference object { name, server_name, type }`
1315 - `BetaToolChangeMCPToolReference object`
13371316
13381317 Reference to a single MCP tool by its server and remote name — the
13391318 same `server_name`/`name` pair `mcp_tool_use` carries.
from line 1323
13441323
13451324 - `type: "mcp_tool_reference"`
13461325
1347 - `"mcp_tool_reference"`
1348
1349 - `BetaToolChangeMCPToolsetReference object { server_name, type }`
1326 - `BetaToolChangeMCPToolsetReference object`
13501327
13511328 Reference to every tool in the named MCP server's toolset.
13521329
from line 1331
13541331
13551332 - `type: "mcp_toolset_reference"`
13561333
1357 - `"mcp_toolset_reference"`
1358
13591334 - `type: "tool_addition"`
13601335
1361 - `"tool_addition"`
1362
13631336 - `cache_control: optional BetaCacheControlEphemeral or null`
13641337
13651338 Create a cache control breakpoint at this content block.
13661339
1367 - `BetaRequestToolRemovalBlock object { tool, type, cache_control }`
1340 - `BetaRequestToolRemovalBlock object`
13681341
13691342 Mid-conversation directive to withdraw a tool.
13701343
from line 1352
13791352 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13801353 `mcp_toolset_reference` for those.
13811354
1382 - `BetaToolChangeToolReference object { name, type }`
1355 - `BetaToolChangeToolReference object`
13831356
13841357 Reference to a single tool the caller declared directly in
13851358 `tools[]`. Does not accept the composed `{server}_{name}` form the
13861359 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13871360 `mcp_toolset_reference` for those.
13881361
1389 - `BetaToolChangeMCPToolReference object { name, server_name, type }`
1362 - `BetaToolChangeMCPToolReference object`
13901363
13911364 Reference to a single MCP tool by its server and remote name — the
13921365 same `server_name`/`name` pair `mcp_tool_use` carries.
13931366
1394 - `BetaToolChangeMCPToolsetReference object { server_name, type }`
1367 - `BetaToolChangeMCPToolsetReference object`
13951368
13961369 Reference to every tool in the named MCP server's toolset.
13971370
13981371 - `type: "tool_removal"`
13991372
1400 - `"tool_removal"`
1401
14021373 - `cache_control: optional BetaCacheControlEphemeral or null`
14031374
14041375 Create a cache control breakpoint at this content block.
14051376
1406 - `BetaFallbackBlockParam object { from, to, type, trigger }`
1377 - `BetaFallbackBlockParam object`
14071378
14081379 A `fallback` block echoed back from a prior response.
14091380
from line 1474
15031474
15041475 - `type: "fallback"`
15051476
1506 - `"fallback"`
1507
15081477 - `trigger: optional unknown`
15091478
15101479 The response block's `trigger`, echoed verbatim. Accepted and ignored by the server; any object or `null` is allowed.
from line 1500
15311500
15321501 Container identifier for reuse across requests.
15331502
1534 - `BetaContainerParams object { id, skills }`
1503 - `BetaContainerParams object`
15351504
15361505 Container parameters with skills to be loaded.
15371506
from line 1512
15431512
15441513 List of skills to load in the container
15451514
1515 maxItems: 20
1516
15461517 - `skill_id: string`
15471518
15481519 Skill ID
15491520
1521 maxLength: 64, minLength: 1
1522
15501523 - `type: "anthropic" or "custom"`
15511524
15521525 Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
from line 1532
15591532
15601533 Skill version or 'latest' for most recent version
15611534
1535 maxLength: 64, minLength: 1
1536
15621537 - `string`
15631538
15641539 - `context_management: optional BetaContextManagementConfig or null`
from line 1546
15711546
15721547 List of context management edits to apply
15731548
1574 - `BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }`
1549 minItems: 0
1550
1551 - `BetaClearToolUses20250919Edit object`
15751552
15761553 - `type: "clear_tool_uses_20250919"`
15771554
1578 - `"clear_tool_uses_20250919"`
1579
15801555 - `clear_at_least: optional BetaInputTokensClearAtLeast or null`
15811556
15821557 Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.
15831558
15841559 - `type: "input_tokens"`
15851560
1586 - `"input_tokens"`
1587
15881561 - `value: number`
15891562
1563 minimum: 0
1564
15901565 - `clear_tool_inputs: optional boolean or array of string or null`
15911566
15921567 Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)
from line 1580
16051580
16061581 - `type: "tool_uses"`
16071582
1608 - `"tool_uses"`
1609
16101583 - `value: number`
16111584
1585 minimum: 0
1586
16121587 - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger`
16131588
16141589 Condition that triggers the context management strategy
16151590
1616 - `BetaInputTokensTrigger object { type, value }`
1591 - `BetaInputTokensTrigger object`
16171592
16181593 - `type: "input_tokens"`
16191594
1620 - `"input_tokens"`
1621
16221595 - `value: number`
16231596
1624 - `BetaToolUsesTrigger object { type, value }`
1597 minimum: 1
1598
1599 - `BetaToolUsesTrigger object`
16251600
16261601 - `type: "tool_uses"`
16271602
1628 - `"tool_uses"`
1629
16301603 - `value: number`
16311604
1632 - `BetaClearThinking20251015Edit object { type, keep }`
1605 minimum: 1
1606
1607 - `BetaClearThinking20251015Edit object`
16331608
16341609 - `type: "clear_thinking_20251015"`
16351610
1636 - `"clear_thinking_20251015"`
1637
16381611 - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"`
16391612
16401613 Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.
16411614
1642 - `BetaThinkingTurns object { type, value }`
1615 - `BetaThinkingTurns object`
16431616
16441617 - `type: "thinking_turns"`
16451618
1646 - `"thinking_turns"`
1647
16481619 - `value: number`
16491620
1650 - `BetaAllThinkingTurns object { type }`
1621 minimum: 1
1622
1623 - `BetaAllThinkingTurns object`
16511624
16521625 - `type: "all"`
16531626
1654 - `"all"`
1655
16561627 - `"all"`
16571628
1658 - `"all"`
1659
1660 - `BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }`
1629 - `BetaCompact20260112Edit object`
16611630
16621631 Automatically compact older context when reaching the configured trigger threshold.
16631632
16641633 - `type: "compact_20260112"`
1665
1666 - `"compact_20260112"`
16671634
16681635 - `instructions: optional string or null`
16691636
from line 1652
16851652 - `previous_message_id: optional string or null`
16861653
16871654 The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare.
1655
1656 maxLength: 256
16881657
16891658 - `fallback_credit_token: optional string or BetaFallbackCreditTokenParam or null`
16901659
from line 1680
17111680
17121681 - `string`
17131682
1714 - `BetaFallbackCreditTokenParam object { token, mode }`
1683 - `BetaFallbackCreditTokenParam object`
17151684
17161685 Object form of `fallback_credit_token`: the token plus a redemption
17171686 mode.
from line 1694
17251694
17261695 The opaque `fallback_credit_token` from a prior refusal's `stop_details` — the same string the bare-string form carries.
17271696
1697 maxLength: 2048, minLength: 1
1698
17281699 - `mode: optional "strict" or "best_effort"`
17291700
17301701 How a failing token affects the retry. `strict` (the default, and the bare-string behavior): a failing redemption is a 400 and the retry is not served. `best_effort`: the retry is served either way — a token-layer failure no longer rejects the request; the retry proceeds at normal price and the outcome is reported on the response's `usage.fallback_credit`. Two failures stay hard in both modes: a malformed token, and combining `fallback_credit_token` with `fallbacks`.
from line 1744
17731744
17741745 - `type: "json_schema"`
17751746
1776 - `"json_schema"`
1777
17781747 - `task_budget: optional BetaTokenTaskBudget or null`
17791748
17801749 User-configurable total token budget across contexts.
from line 1752
17831752
17841753 Total token budget across all contexts in the session.
17851754
1755 minimum: 1024
1756
17861757 - `type: "tokens"`
17871758
17881759 The budget type. Currently only 'tokens' is supported.
17891760
1790 - `"tokens"`
1791
17921761 - `remaining: optional number or null`
17931762
17941763 Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.
17951764
1765 minimum: 0
1766
17961767 - `speed: optional "standard" or "fast" or null`
17971768
17981769 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 1774
18031774
18041775 - `thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive or null`
18051776
1806 - `BetaThinkingConfigEnabled object { budget_tokens, type, display }`
1777 - `BetaThinkingConfigEnabled object`
18071778
18081779 - `budget_tokens: number`
18091780
from line 1784
18131784
18141785 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
18151786
1787 minimum: 1024
1788
18161789 - `type: "enabled"`
18171790
1818 - `"enabled"`
1819
18201791 - `display: optional "summarized" or "omitted" or null`
18211792
18221793 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
from line 1796
18251796
18261797 - `"omitted"`
18271798
1828 - `BetaThinkingConfigDisabled object { type }`
1799 - `BetaThinkingConfigDisabled object`
18291800
18301801 - `type: "disabled"`
18311802
1832 - `"disabled"`
1833
1834 - `BetaThinkingConfigAdaptive object { type, display }`
1803 - `BetaThinkingConfigAdaptive object`
18351804
18361805 - `type: "adaptive"`
18371806
1838 - `"adaptive"`
1839
18401807 - `display: optional "summarized" or "omitted" or null`
18411808
18421809 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
from line 1814
18471814
18481815 - `Default = "default"`
18491816
1850 - `"default"`
1851
18521817 - `inference_geo: optional string or null`
18531818
18541819 Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.
from line 1822
18571822
18581823 MCP servers to be utilized in this request
18591824
1825 maxItems: 20
1826
18601827 - `name: string`
18611828
18621829 - `type: "url"`
18631830
1864 - `"url"`
1865
18661831 - `url: string`
18671832
18681833 - `authorization_token: optional string or null`
from line 1848
18831848
18841849 This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.
18851850
1851 maxLength: 512
1852
18861853 - `output_config: optional BetaOutputConfig`
18871854
18881855 Configuration options for the model's output, such as the output format.
18891856
1890 - `output_format: optional BetaJSONOutputFormat or null`
1891
1892 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
1893
1894 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
1895
18961857 - `service_tier: optional "auto" or "standard_only"`
18971858
18981859 Determines whether to use priority capacity (if available) or standard capacity for this request.
from line 1898
19371898
19381899 - `text: string`
19391900
1901 minLength: 1
1902
19401903 - `type: "text"`
19411904
19421905 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1908
19451908
19461909 - `citations: optional array of BetaTextCitationParam or null`
19471910
1948 - `temperature: optional number`
1949
1950 Amount of randomness injected into the response.
1951
1952 Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.
1953
1954 Note that even with `temperature` of `0.0`, the results will not be fully deterministic.
1955
19561911 - `thinking: optional BetaThinkingConfigParam`
19571912
19581913 Configuration for enabling Claude's extended thinking.
from line 1916
19611916
19621917 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
19631918
1964 - `BetaThinkingConfigEnabled object { budget_tokens, type, display }`
1965
1966 - `BetaThinkingConfigDisabled object { type }`
1967
1968 - `BetaThinkingConfigAdaptive object { type, display }`
1919 - `BetaThinkingConfigEnabled object`
1920
1921 - `BetaThinkingConfigDisabled object`
1922
1923 - `BetaThinkingConfigAdaptive object`
19691924
19701925 - `tool_choice: optional BetaToolChoice`
19711926
19721927 How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
19731928
1974 - `BetaToolChoiceAuto object { type, disable_parallel_tool_use }`
1929 - `BetaToolChoiceAuto object`
19751930
19761931 The model will automatically decide whether to use tools.
19771932
19781933 - `type: "auto"`
19791934
1980 - `"auto"`
1981
19821935 - `disable_parallel_tool_use: optional boolean`
19831936
19841937 Whether to disable parallel tool use.
19851938
19861939 Defaults to `false`. If set to `true`, the model will output at most one tool use.
19871940
1988 - `BetaToolChoiceAny object { type, disable_parallel_tool_use }`
1941 - `BetaToolChoiceAny object`
19891942
19901943 The model will use any available tools.
19911944
19921945 - `type: "any"`
19931946
1994 - `"any"`
1995
19961947 - `disable_parallel_tool_use: optional boolean`
19971948
19981949 Whether to disable parallel tool use.
19991950
20001951 Defaults to `false`. If set to `true`, the model will output exactly one tool use.
20011952
2002 - `BetaToolChoiceTool object { name, type, disable_parallel_tool_use }`
1953 - `BetaToolChoiceTool object`
20031954
20041955 The model will use the specified tool with `tool_choice.name`.
20051956
from line 1960
20091960
20101961 - `type: "tool"`
20111962
2012 - `"tool"`
2013
20141963 - `disable_parallel_tool_use: optional boolean`
20151964
20161965 Whether to disable parallel tool use.
20171966
20181967 Defaults to `false`. If set to `true`, the model will output exactly one tool use.
20191968
2020 - `BetaToolChoiceNone object { type }`
1969 - `BetaToolChoiceNone object`
20211970
20221971 The model will not be allowed to use tools.
20231972
20241973 - `type: "none"`
2025
2026 - `"none"`
20271974
20281975 - `tools: optional array of BetaToolUnion`
20291976
from line 2036
20892036
20902037 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
20912038
2092 - `BetaTool object { input_schema, name, allowed_callers, 7 more }`
2093
2094 - `input_schema: object { type, properties, required }`
2039 - `BetaTool object`
2040
2041 - `input_schema: object`
20952042
20962043 [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input.
20972044
from line 2046
20992046
21002047 - `type: "object"`
21012048
2102 - `"object"`
2103
21042049 - `properties: optional map[unknown] or null`
21052050
21062051 - `required: optional array of string or null`
from line 2056
21112056
21122057 This is how the tool will be called by the model and in `tool_use` blocks.
21132058
2059 maxLength: 128, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,128}$
2060
21142061 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
21152062
21162063 - `"direct"`
from line 2094
21472094
21482095 - `type: optional "custom" or null`
21492096
2150 - `"custom"`
2151
2152 - `BetaToolBash20241022 object { name, type, allowed_callers, 4 more }`
2097 - `BetaToolBash20241022 object`
21532098
21542099 - `name: "bash"`
21552100
from line 2102
21572102
21582103 This is how the tool will be called by the model and in `tool_use` blocks.
21592104
2160 - `"bash"`
2161
21622105 - `type: "bash_20241022"`
21632106
2164 - `"bash_20241022"`
2165
21662107 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
21672108
21682109 - `"direct"`
from line 2128
21872128
21882129 When true, guarantees schema validation on tool names and inputs
21892130
2190 - `BetaToolBash20250124 object { name, type, allowed_callers, 4 more }`
2131 - `BetaToolBash20250124 object`
21912132
21922133 - `name: "bash"`
21932134
from line 2136
21952136
21962137 This is how the tool will be called by the model and in `tool_use` blocks.
21972138
2198 - `"bash"`
2199
22002139 - `type: "bash_20250124"`
22012140
2202 - `"bash_20250124"`
2203
22042141 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
22052142
22062143 - `"direct"`
from line 2162
22252162
22262163 When true, guarantees schema validation on tool names and inputs
22272164
2228 - `BetaCodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }`
2165 - `BetaCodeExecutionTool20250522 object`
22292166
22302167 - `name: "code_execution"`
22312168
from line 2170
22332170
22342171 This is how the tool will be called by the model and in `tool_use` blocks.
22352172
2236 - `"code_execution"`
2237
22382173 - `type: "code_execution_20250522"`
22392174
2240 - `"code_execution_20250522"`
2241
22422175 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
22432176
22442177 - `"direct"`
from line 2194
22612194
22622195 When true, guarantees schema validation on tool names and inputs
22632196
2264 - `BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }`
2197 - `BetaCodeExecutionTool20250825 object`
22652198
22662199 - `name: "code_execution"`
22672200
from line 2202
22692202
22702203 This is how the tool will be called by the model and in `tool_use` blocks.
22712204
2272 - `"code_execution"`
2273
22742205 - `type: "code_execution_20250825"`
22752206
2207 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2208
2209 - `"direct"`
2210
22762211 - `"code_execution_20250825"`
22772212
2213 - `"code_execution_20260120"`
2214
2215 - `"code_execution_20260521"`
2216
2217 - `cache_control: optional BetaCacheControlEphemeral or null`
2218
2219 Create a cache control breakpoint at this content block.
2220
2221 - `defer_loading: optional boolean`
2222
2223 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
2224
2225 - `strict: optional boolean`
2226
2227 When true, guarantees schema validation on tool names and inputs
2228
2229 - `BetaCodeExecutionTool20260120 object`
2230
2231 Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
2232
2233 - `name: "code_execution"`
2234
2235 Name of the tool.
2236
2237 This is how the tool will be called by the model and in `tool_use` blocks.
2238
2239 - `type: "code_execution_20260120"`
2240
22782241 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
22792242
22802243 - `"direct"`
from line 2260
22972260
22982261 When true, guarantees schema validation on tool names and inputs
22992262
2300 - `BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }`
2301
2302 Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
2263 - `BetaCodeExecutionTool20260521 object`
2264
2265 Code execution tool with REPL state persistence.
23032266
23042267 - `name: "code_execution"`
23052268
from line 2270
23072270
23082271 This is how the tool will be called by the model and in `tool_use` blocks.
23092272
2310 - `"code_execution"`
2311
2312 - `type: "code_execution_20260120"`
2273 - `type: "code_execution_20260521"`
2274
2275 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2276
2277 - `"direct"`
2278
2279 - `"code_execution_20250825"`
23132280
23142281 - `"code_execution_20260120"`
23152282
2316 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2317
2318 - `"direct"`
2319
2320 - `"code_execution_20250825"`
2321
2322 - `"code_execution_20260120"`
2323
23242283 - `"code_execution_20260521"`
23252284
23262285 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 2294
23352294
23362295 When true, guarantees schema validation on tool names and inputs
23372296
2338 - `BetaCodeExecutionTool20260521 object { name, type, allowed_callers, 3 more }`
2339
2340 Code execution tool with REPL state persistence.
2341
2342 - `name: "code_execution"`
2343
2344 Name of the tool.
2345
2346 This is how the tool will be called by the model and in `tool_use` blocks.
2347
2348 - `"code_execution"`
2349
2350 - `type: "code_execution_20260521"`
2351
2352 - `"code_execution_20260521"`
2353
2354 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2355
2356 - `"direct"`
2357
2358 - `"code_execution_20250825"`
2359
2360 - `"code_execution_20260120"`
2361
2362 - `"code_execution_20260521"`
2363
2364 - `cache_control: optional BetaCacheControlEphemeral or null`
2365
2366 Create a cache control breakpoint at this content block.
2367
2368 - `defer_loading: optional boolean`
2369
2370 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
2371
2372 - `strict: optional boolean`
2373
2374 When true, guarantees schema validation on tool names and inputs
2375
2376 - `BetaBrowserToolset20260801 object { type, allowed_callers, cache_control, configs }`
2297 - `BetaBrowserToolset20260801 object`
23772298
23782299 The browser toolset: a single `tools[]` entry (carrying no
23792300 `name`) that declares the browser tool family. The model is served
from line 2302
23812302 from its schema.
23822303
23832304 - `type: "browser_toolset_20260801"`
2384
2385 - `"browser_toolset_20260801"`
23862305
23872306 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
23882307
from line 2698
27792698
27802699 Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
27812700
2782 - `BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }`
2701 - `BetaToolComputerUse20241022 object`
27832702
27842703 - `display_height_px: number`
27852704
27862705 The height of the display in pixels.
27872706
2707 minimum: 1
2708
27882709 - `display_width_px: number`
27892710
27902711 The width of the display in pixels.
27912712
2713 minimum: 1
2714
27922715 - `name: "computer"`
27932716
27942717 Name of the tool.
27952718
27962719 This is how the tool will be called by the model and in `tool_use` blocks.
27972720
2798 - `"computer"`
2799
28002721 - `type: "computer_20241022"`
28012722
2802 - `"computer_20241022"`
2803
28042723 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
28052724
28062725 - `"direct"`
from line 2742
28232742
28242743 The X11 display number (e.g. 0, 1) for the display.
28252744
2745 minimum: 0
2746
28262747 - `input_examples: optional array of map[unknown]`
28272748
28282749 - `strict: optional boolean`
28292750
28302751 When true, guarantees schema validation on tool names and inputs
28312752
2832 - `BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }`
2753 - `BetaMemoryTool20250818 object`
28332754
28342755 - `name: "memory"`
28352756
from line 2758
28372758
28382759 This is how the tool will be called by the model and in `tool_use` blocks.
28392760
2840 - `"memory"`
2841
28422761 - `type: "memory_20250818"`
28432762
2844 - `"memory_20250818"`
2845
28462763 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
28472764
28482765 - `"direct"`
from line 2784
28672784
28682785 When true, guarantees schema validation on tool names and inputs
28692786
2870 - `BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }`
2787 - `BetaToolComputerUse20250124 object`
28712788
28722789 - `display_height_px: number`
28732790
28742791 The height of the display in pixels.
28752792
2793 minimum: 1
2794
28762795 - `display_width_px: number`
28772796
28782797 The width of the display in pixels.
28792798
2799 minimum: 1
2800
28802801 - `name: "computer"`
28812802
28822803 Name of the tool.
28832804
28842805 This is how the tool will be called by the model and in `tool_use` blocks.
28852806
2886 - `"computer"`
2887
28882807 - `type: "computer_20250124"`
28892808
2890 - `"computer_20250124"`
2891
28922809 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
28932810
28942811 - `"direct"`
from line 2828
29112828
29122829 The X11 display number (e.g. 0, 1) for the display.
29132830
2831 minimum: 0
2832
29142833 - `input_examples: optional array of map[unknown]`
29152834
29162835 - `strict: optional boolean`
29172836
29182837 When true, guarantees schema validation on tool names and inputs
29192838
2920 - `BetaToolTextEditor20241022 object { name, type, allowed_callers, 4 more }`
2839 - `BetaToolTextEditor20241022 object`
29212840
29222841 - `name: "str_replace_editor"`
29232842
from line 2844
29252844
29262845 This is how the tool will be called by the model and in `tool_use` blocks.
29272846
2928 - `"str_replace_editor"`
2929
29302847 - `type: "text_editor_20241022"`
29312848
2932 - `"text_editor_20241022"`
2933
29342849 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
29352850
29362851 - `"direct"`
from line 2870
29552870
29562871 When true, guarantees schema validation on tool names and inputs
29572872
2958 - `BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }`
2873 - `BetaToolComputerUse20251124 object`
29592874
29602875 - `display_height_px: number`
29612876
29622877 The height of the display in pixels.
29632878
2879 minimum: 1
2880
29642881 - `display_width_px: number`
29652882
29662883 The width of the display in pixels.
29672884
2885 minimum: 1
2886
29682887 - `name: "computer"`
29692888
29702889 Name of the tool.
29712890
29722891 This is how the tool will be called by the model and in `tool_use` blocks.
29732892
2974 - `"computer"`
2975
29762893 - `type: "computer_20251124"`
29772894
2978 - `"computer_20251124"`
2979
29802895 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
29812896
29822897 - `"direct"`
from line 2914
29992914
30002915 The X11 display number (e.g. 0, 1) for the display.
30012916
2917 minimum: 0
2918
30022919 - `enable_zoom: optional boolean`
30032920
30042921 Whether to enable an action to take a zoomed-in screenshot of the screen.
from line 2926
30092926
30102927 When true, guarantees schema validation on tool names and inputs
30112928
3012 - `BetaComputerToolset20260801 object { type, allowed_callers, cache_control, configs }`
2929 - `BetaComputerToolset20260801 object`
30132930
30142931 The computer toolset: a single `tools[]` entry (carrying no
30152932 `name`) that declares the computer tool family. The model is
from line 2939
30222939
30232940 - `type: "computer_toolset_20260801"`
30242941
3025 - `"computer_toolset_20260801"`
3026
30272942 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
30282943
30292944 - `"direct"`
from line 3166
32513166
32523167 Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
32533168
3254 - `BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }`
3169 - `BetaToolTextEditor20250124 object`
32553170
32563171 - `name: "str_replace_editor"`
32573172
from line 3174
32593174
32603175 This is how the tool will be called by the model and in `tool_use` blocks.
32613176
3262 - `"str_replace_editor"`
3263
32643177 - `type: "text_editor_20250124"`
32653178
3266 - `"text_editor_20250124"`
3267
32683179 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
32693180
32703181 - `"direct"`
from line 3200
32893200
32903201 When true, guarantees schema validation on tool names and inputs
32913202
3292 - `BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }`
3203 - `BetaToolTextEditor20250429 object`
32933204
32943205 - `name: "str_replace_based_edit_tool"`
32953206
from line 3208
32973208
32983209 This is how the tool will be called by the model and in `tool_use` blocks.
32993210
3300 - `"str_replace_based_edit_tool"`
3301
33023211 - `type: "text_editor_20250429"`
33033212
3304 - `"text_editor_20250429"`
3305
33063213 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33073214
33083215 - `"direct"`
from line 3234
33273234
33283235 When true, guarantees schema validation on tool names and inputs
33293236
3330 - `BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }`
3237 - `BetaToolTextEditor20250728 object`
33313238
33323239 - `name: "str_replace_based_edit_tool"`
33333240
from line 3242
33353242
33363243 This is how the tool will be called by the model and in `tool_use` blocks.
33373244
3338 - `"str_replace_based_edit_tool"`
3339
33403245 - `type: "text_editor_20250728"`
33413246
3342 - `"text_editor_20250728"`
3343
33443247 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33453248
33463249 - `"direct"`
from line 3268
33653268
33663269 Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.
33673270
3271 minimum: 1
3272
33683273 - `strict: optional boolean`
33693274
33703275 When true, guarantees schema validation on tool names and inputs
33713276
3372 - `BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }`
3277 - `BetaWebSearchTool20250305 object`
33733278
33743279 - `name: "web_search"`
33753280
from line 3282
33773282
33783283 This is how the tool will be called by the model and in `tool_use` blocks.
33793284
3380 - `"web_search"`
3381
33823285 - `type: "web_search_20250305"`
33833286
3384 - `"web_search_20250305"`
3385
33863287 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33873288
33883289 - `"direct"`
from line 3314
34133314
34143315 Maximum number of times the tool can be used in the API request.
34153316
3317 exclusiveMinimum: 0
3318
34163319 - `strict: optional boolean`
34173320
34183321 When true, guarantees schema validation on tool names and inputs
from line 3326
34233326
34243327 - `type: "approximate"`
34253328
3426 - `"approximate"`
3427
34283329 - `city: optional string or null`
34293330
34303331 The city of the user.
34313332
3333 maxLength: 255, minLength: 1
3334
34323335 - `country: optional string or null`
34333336
34343337 The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.
34353338
3339 maxLength: 2, minLength: 2
3340
34363341 - `region: optional string or null`
34373342
34383343 The region of the user.
34393344
3345 maxLength: 255, minLength: 1
3346
34403347 - `timezone: optional string or null`
34413348
34423349 The [IANA timezone](https://nodatime.org/TimeZones) of the user.
34433350
3444 - `BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }`
3351 maxLength: 255, minLength: 1
3352
3353 - `BetaWebFetchTool20250910 object`
34453354
34463355 - `name: "web_fetch"`
34473356
from line 3358
34493358
34503359 This is how the tool will be called by the model and in `tool_use` blocks.
34513360
3452 - `"web_fetch"`
3453
34543361 - `type: "web_fetch_20250910"`
34553362
3456 - `"web_fetch_20250910"`
3457
34583363 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
34593364
34603365 - `"direct"`
from line 3394
34893394
34903395 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
34913396
3397 exclusiveMinimum: 0
3398
34923399 - `max_uses: optional number or null`
34933400
34943401 Maximum number of times the tool can be used in the API request.
34953402
3403 exclusiveMinimum: 0
3404
34963405 - `strict: optional boolean`
34973406
34983407 When true, guarantees schema validation on tool names and inputs
34993408
3500 - `BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }`
3409 - `BetaWebSearchTool20260209 object`
35013410
35023411 - `name: "web_search"`
35033412
from line 3414
35053414
35063415 This is how the tool will be called by the model and in `tool_use` blocks.
35073416
3508 - `"web_search"`
3509
35103417 - `type: "web_search_20260209"`
35113418
3512 - `"web_search_20260209"`
3513
35143419 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
35153420
35163421 - `"direct"`
from line 3446
35413446
35423447 Maximum number of times the tool can be used in the API request.
35433448
3449 exclusiveMinimum: 0
3450
35443451 - `strict: optional boolean`
35453452
35463453 When true, guarantees schema validation on tool names and inputs
from line 3456
35493456
35503457 Parameters for the user's location. Used to provide more relevant search results.
35513458
3552 - `BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }`
3459 - `BetaWebFetchTool20260209 object`
35533460
35543461 - `name: "web_fetch"`
35553462
from line 3464
35573464
35583465 This is how the tool will be called by the model and in `tool_use` blocks.
35593466
3560 - `"web_fetch"`
3561
35623467 - `type: "web_fetch_20260209"`
35633468
3564 - `"web_fetch_20260209"`
3565
35663469 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
35673470
35683471 - `"direct"`
from line 3500
35973500
35983501 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
35993502
3503 exclusiveMinimum: 0
3504
36003505 - `max_uses: optional number or null`
36013506
36023507 Maximum number of times the tool can be used in the API request.
36033508
3509 exclusiveMinimum: 0
3510
36043511 - `strict: optional boolean`
36053512
36063513 When true, guarantees schema validation on tool names and inputs
36073514
3608 - `BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }`
3515 - `BetaWebFetchTool20260309 object`
36093516
36103517 Web fetch tool with use_cache parameter for bypassing cached content.
36113518
from line 3522
36153522
36163523 This is how the tool will be called by the model and in `tool_use` blocks.
36173524
3618 - `"web_fetch"`
3619
36203525 - `type: "web_fetch_20260309"`
36213526
3622 - `"web_fetch_20260309"`
3623
36243527 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
36253528
36263529 - `"direct"`
from line 3558
36553558
36563559 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
36573560
3561 exclusiveMinimum: 0
3562
36583563 - `max_uses: optional number or null`
36593564
36603565 Maximum number of times the tool can be used in the API request.
36613566
3567 exclusiveMinimum: 0
3568
36623569 - `strict: optional boolean`
36633570
36643571 When true, guarantees schema validation on tool names and inputs
from line 3574
36673574
36683575 Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.
36693576
3670 - `BetaWebSearchTool20260318 object { name, type, allowed_callers, 8 more }`
3577 - `BetaWebSearchTool20260318 object`
36713578
36723579 - `name: "web_search"`
36733580
from line 3582
36753582
36763583 This is how the tool will be called by the model and in `tool_use` blocks.
36773584
3678 - `"web_search"`
3679
36803585 - `type: "web_search_20260318"`
36813586
3682 - `"web_search_20260318"`
3683
36843587 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
36853588
36863589 - `"direct"`
from line 3614
37113614
37123615 Maximum number of times the tool can be used in the API request.
37133616
3617 exclusiveMinimum: 0
3618
37143619 - `response_inclusion: optional "full" or "excluded"`
37153620
37163621 How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3632
37273632
37283633 Parameters for the user's location. Used to provide more relevant search results.
37293634
3730 - `BetaWebFetchTool20260318 object { name, type, allowed_callers, 10 more }`
3635 - `BetaWebFetchTool20260318 object`
37313636
37323637 - `name: "web_fetch"`
37333638
from line 3640
37353640
37363641 This is how the tool will be called by the model and in `tool_use` blocks.
37373642
3738 - `"web_fetch"`
3739
37403643 - `type: "web_fetch_20260318"`
37413644
3742 - `"web_fetch_20260318"`
3743
37443645 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
37453646
37463647 - `"direct"`
from line 3676
37753676
37763677 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
37773678
3679 exclusiveMinimum: 0
3680
37783681 - `max_uses: optional number or null`
37793682
37803683 Maximum number of times the tool can be used in the API request.
37813684
3685 exclusiveMinimum: 0
3686
37823687 - `response_inclusion: optional "full" or "excluded"`
37833688
37843689 How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3700
37953700
37963701 Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.
37973702
3798 - `BetaAdvisorTool20260301 object { model, name, type, 7 more }`
3703 - `BetaAdvisorTool20260301 object`
37993704
38003705 - `model: Model`
38013706
from line 3714
38093714
38103715 This is how the tool will be called by the model and in `tool_use` blocks.
38113716
3812 - `"advisor"`
3813
38143717 - `type: "advisor_20260301"`
38153718
3816 - `"advisor_20260301"`
3817
38183719 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
38193720
38203721 - `"direct"`
from line 3742
38413742
38423743 Bounds the advisor's total output (thinking + text) per call. When the advisor hits this cap, the returned advisor_result or advisor_redacted_result block carries stop_reason='max_tokens', and a truncation note is appended to the advice text the worker model sees (inside the encrypted blob in redacted mode). When set, the server also emits a remaining-tokens budget block in the advisor's prompt so the advisor self-shapes toward the cap. When omitted, the advisor model's default output cap applies and no budget block is emitted.
38433744
3745 minimum: 1024
3746
38443747 - `max_uses: optional number or null`
38453748
38463749 Maximum number of times the tool can be used in the API request.
38473750
3751 exclusiveMinimum: 0
3752
38483753 - `strict: optional boolean`
38493754
38503755 When true, guarantees schema validation on tool names and inputs
38513756
3852 - `BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }`
3757 - `BetaToolSearchToolBm25_20251119 object`
38533758
38543759 - `name: "tool_search_tool_bm25"`
38553760
from line 3762
38573762
38583763 This is how the tool will be called by the model and in `tool_use` blocks.
38593764
3765 - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"`
3766
3767 - `"tool_search_tool_bm25_20251119"`
3768
38603769 - `"tool_search_tool_bm25"`
38613770
3862 - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"`
3863
3864 - `"tool_search_tool_bm25_20251119"`
3865
3866 - `"tool_search_tool_bm25"`
3867
38683771 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
38693772
38703773 - `"direct"`
from line 3790
38873790
38883791 When true, guarantees schema validation on tool names and inputs
38893792
3890 - `BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }`
3793 - `BetaToolSearchToolRegex20251119 object`
38913794
38923795 - `name: "tool_search_tool_regex"`
38933796
from line 3798
38953798
38963799 This is how the tool will be called by the model and in `tool_use` blocks.
38973800
3801 - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"`
3802
3803 - `"tool_search_tool_regex_20251119"`
3804
38983805 - `"tool_search_tool_regex"`
38993806
3900 - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"`
3901
3902 - `"tool_search_tool_regex_20251119"`
3903
3904 - `"tool_search_tool_regex"`
3905
39063807 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
39073808
39083809 - `"direct"`
from line 3826
39253826
39263827 When true, guarantees schema validation on tool names and inputs
39273828
3928 - `BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }`
3829 - `BetaMCPToolset object`
39293830
39303831 Configuration for a group of tools from an MCP server.
39313832
from line 3837
39363837
39373838 Name of the MCP server to configure tools for
39383839
3840 maxLength: 255, minLength: 1
3841
39393842 - `type: "mcp_toolset"`
39403843
3941 - `"mcp_toolset"`
3942
39433844 - `cache_control: optional BetaCacheControlEphemeral or null`
39443845
39453846 Create a cache control breakpoint at this content block.
from line 3861
39603861
39613862 - `enabled: optional boolean`
39623863
3864 - `output_format: optional BetaJSONOutputFormat or null`
3865
3866 **Deprecated**
3867
3868 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
3869
3870 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
3871
3872 - `temperature: optional number`
3873
3874 **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not support setting temperature. A value of 1.0 of will be accepted for backwards compatibility, all other values will be rejected with a 400 error.
3875
3876 Amount of randomness injected into the response.
3877
3878 Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.
3879
3880 Note that even with `temperature` of `0.0`, the results will not be fully deterministic.
3881
3882 maximum: 1, minimum: 0
3883
39633884 - `top_k: optional number`
39643885
3886 **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not accept top_k; any value will be rejected with a 400 error.
3887
39653888 Only sample from the top K options for each subsequent token.
39663889
39673890 Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).
39683891
39693892 Recommended for advanced use cases only.
39703893
3894 minimum: 0
3895
39713896 - `top_p: optional number`
39723897
3898 **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not support setting top_p. A value >= 0.99 will be accepted for backwards compatibility, all other values will be rejected with a 400 error.
3899
39733900 Use nucleus sampling.
39743901
39753902 In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`.
39763903
39773904 Recommended for advanced use cases only.
39783905
3906 maximum: 1, minimum: 0
3907
39793908### Returns
39803909
3981- `BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }`
3910- `BetaMessageBatch object`
39823911
39833912 - `id: string`
39843913
from line 3919
39903919
39913920 RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
39923921
3922 format: date-time
3923
39933924 - `cancel_initiated_at: string or null`
39943925
39953926 RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
39963927
3928 format: date-time
3929
39973930 - `created_at: string`
39983931
39993932 RFC 3339 datetime string representing the time at which the Message Batch was created.
40003933
3934 format: date-time
3935
40013936 - `ended_at: string or null`
40023937
40033938 RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
40043939
40053940 Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
40063941
3942 format: date-time
3943
40073944 - `expires_at: string`
40083945
40093946 RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
40103947
3948 format: date-time
3949
40113950 - `processing_status: "in_progress" or "canceling" or "ended"`
40123951
40133952 Processing status of the Message Batch.
from line 3969
40303969
40313970 This is zero until processing of the entire Message Batch has ended.
40323971
3972 default: 0
3973
40333974 - `errored: number`
40343975
40353976 Number of requests in the Message Batch that encountered an error.
40363977
40373978 This is zero until processing of the entire Message Batch has ended.
40383979
3980 default: 0
3981
40393982 - `expired: number`
40403983
40413984 Number of requests in the Message Batch that have expired.
40423985
40433986 This is zero until processing of the entire Message Batch has ended.
40443987
3988 default: 0
3989
40453990 - `processing: number`
40463991
40473992 Number of requests in the Message Batch that are processing.
40483993
3994 default: 0
3995
40493996 - `succeeded: number`
40503997
40513998 Number of requests in the Message Batch that have completed successfully.
40523999
40534000 This is zero until processing of the entire Message Batch has ended.
40544001
4002 default: 0
4003
40554004 - `results_url: string or null`
40564005
40574006 URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
from line 4013
40644013
40654014 For Message Batches, this is always `"message_batch"`.
40664015
4067 - `"message_batch"`
4016 default: message_batch
40684017
40694018### Example
40704019
4071```http
4020```bash
40724021curl https://api.anthropic.com/v1/messages/batches \
40734022 -H 'Content-Type: application/json' \
40744023 -H 'anthropic-version: 2023-06-01' \
from line 4042
40934042 }'
40944043```
40954044
4096#### Response
4045#### Response (200)
40974046
40984047```json
40994048{
from line 4067
41184067
41194068## Retrieve a Message Batch
41204069
4121**get** `/v1/messages/batches/{message_batch_id}`
4070**GET** `/v1/messages/batches/{message_batch_id}`
41224071
41234072This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response.
41244073
41254074Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
41264075
4127### Path Parameters
4076### Path parameters
41284077
41294078- `message_batch_id: string`
41304079
41314080 ID of the Message Batch.
41324081
4133### Header Parameters
4082### Headers
41344083
41354084- `"anthropic-beta": optional array of AnthropicBeta`
41364085
from line 4159
42104159
42114160### Returns
42124161
4213- `BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }`
4162- `BetaMessageBatch object`
42144163
42154164 - `id: string`
42164165
from line 4171
42224171
42234172 RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
42244173
4174 format: date-time
4175
42254176 - `cancel_initiated_at: string or null`
42264177
42274178 RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
42284179
4180 format: date-time
4181
42294182 - `created_at: string`
42304183
42314184 RFC 3339 datetime string representing the time at which the Message Batch was created.
42324185
4186 format: date-time
4187
42334188 - `ended_at: string or null`
42344189
42354190 RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
42364191
42374192 Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
42384193
4194 format: date-time
4195
42394196 - `expires_at: string`
42404197
42414198 RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
42424199
4200 format: date-time
4201
42434202 - `processing_status: "in_progress" or "canceling" or "ended"`
42444203
42454204 Processing status of the Message Batch.
from line 4221
42624221
42634222 This is zero until processing of the entire Message Batch has ended.
42644223
4224 default: 0
4225
42654226 - `errored: number`
42664227
42674228 Number of requests in the Message Batch that encountered an error.
42684229
42694230 This is zero until processing of the entire Message Batch has ended.
42704231
4232 default: 0
4233
42714234 - `expired: number`
42724235
42734236 Number of requests in the Message Batch that have expired.
42744237
42754238 This is zero until processing of the entire Message Batch has ended.
42764239
4240 default: 0
4241
42774242 - `processing: number`
42784243
42794244 Number of requests in the Message Batch that are processing.
42804245
4246 default: 0
4247
42814248 - `succeeded: number`
42824249
42834250 Number of requests in the Message Batch that have completed successfully.
42844251
42854252 This is zero until processing of the entire Message Batch has ended.
42864253
4254 default: 0
4255
42874256 - `results_url: string or null`
42884257
42894258 URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
from line 4265
42964265
42974266 For Message Batches, this is always `"message_batch"`.
42984267
4299 - `"message_batch"`
4268 default: message_batch
43004269
43014270### Example
43024271
4303```http
4272```bash
43044273curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
43054274 -H 'anthropic-version: 2023-06-01' \
43064275 -H 'anthropic-beta: message-batches-2024-09-24' \
43074276 -H "X-Api-Key: $ANTHROPIC_API_KEY"
43084277```
43094278
4310#### Response
4279#### Response (200)
43114280
43124281```json
43134282{
from line 4301
43324301
43334302## List Message Batches
43344303
4335**get** `/v1/messages/batches`
4304**GET** `/v1/messages/batches`
43364305
43374306List all Message Batches within a Workspace. Most recently created batches are returned first.
43384307
43394308Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
43404309
4341### Query Parameters
4310### Query parameters
43424311
43434312- `after_id: optional string`
43444313
from line 4323
43544323
43554324 Defaults to `20`. Ranges from `1` to `1000`.
43564325
4357### Header Parameters
4326 default: 20, maximum: 1000, minimum: 1
4327
4328### Headers
43584329
43594330- `"anthropic-beta": optional array of AnthropicBeta`
43604331
from line 4417
44464417
44474418 RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
44484419
4420 format: date-time
4421
44494422 - `cancel_initiated_at: string or null`
44504423
44514424 RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
44524425
4426 format: date-time
4427
44534428 - `created_at: string`
44544429
44554430 RFC 3339 datetime string representing the time at which the Message Batch was created.
44564431
4432 format: date-time
4433
44574434 - `ended_at: string or null`
44584435
44594436 RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
44604437
44614438 Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
44624439
4440 format: date-time
4441
44634442 - `expires_at: string`
44644443
44654444 RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
44664445
4446 format: date-time
4447
44674448 - `processing_status: "in_progress" or "canceling" or "ended"`
44684449
44694450 Processing status of the Message Batch.
from line 4467
44864467
44874468 This is zero until processing of the entire Message Batch has ended.
44884469
4470 default: 0
4471
44894472 - `errored: number`
44904473
44914474 Number of requests in the Message Batch that encountered an error.
44924475
44934476 This is zero until processing of the entire Message Batch has ended.
44944477
4478 default: 0
4479
44954480 - `expired: number`
44964481
44974482 Number of requests in the Message Batch that have expired.
44984483
44994484 This is zero until processing of the entire Message Batch has ended.
45004485
4486 default: 0
4487
45014488 - `processing: number`
45024489
45034490 Number of requests in the Message Batch that are processing.
45044491
4492 default: 0
4493
45054494 - `succeeded: number`
45064495
45074496 Number of requests in the Message Batch that have completed successfully.
45084497
45094498 This is zero until processing of the entire Message Batch has ended.
45104499
4500 default: 0
4501
45114502 - `results_url: string or null`
45124503
45134504 URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
from line 4511
45204511
45214512 For Message Batches, this is always `"message_batch"`.
45224513
4523 - `"message_batch"`
4514 default: message_batch
45244515
45254516- `first_id: string or null`
45264517
from line 4527
45364527
45374528### Example
45384529
4539```http
4530```bash
45404531curl https://api.anthropic.com/v1/messages/batches \
45414532 -H 'anthropic-version: 2023-06-01' \
45424533 -H 'anthropic-beta: message-batches-2024-09-24' \
45434534 -H "X-Api-Key: $ANTHROPIC_API_KEY"
45444535```
45454536
4546#### Response
4537#### Response (200)
45474538
45484539```json
45494540{
from line 4566
45754566
45764567## Cancel a Message Batch
45774568
4578**post** `/v1/messages/batches/{message_batch_id}/cancel`
4569**POST** `/v1/messages/batches/{message_batch_id}/cancel`
45794570
45804571Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.
45814572
from line 4574
45834574
45844575Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
45854576
4586### Path Parameters
4577### Path parameters
45874578
45884579- `message_batch_id: string`
45894580
45904581 ID of the Message Batch.
45914582
4592### Header Parameters
4583### Headers
45934584
45944585- `"anthropic-beta": optional array of AnthropicBeta`
45954586
from line 4660
46694660
46704661### Returns
46714662
4672- `BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }`
4663- `BetaMessageBatch object`
46734664
46744665 - `id: string`
46754666
from line 4672
46814672
46824673 RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
46834674
4675 format: date-time
4676
46844677 - `cancel_initiated_at: string or null`
46854678
46864679 RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
46874680
4681 format: date-time
4682
46884683 - `created_at: string`
46894684
46904685 RFC 3339 datetime string representing the time at which the Message Batch was created.
46914686
4687 format: date-time
4688
46924689 - `ended_at: string or null`
46934690
46944691 RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
46954692
46964693 Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
46974694
4695 format: date-time
4696
46984697 - `expires_at: string`
46994698
47004699 RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
47014700
4701 format: date-time
4702
47024703 - `processing_status: "in_progress" or "canceling" or "ended"`
47034704
47044705 Processing status of the Message Batch.
from line 4722
47214722
47224723 This is zero until processing of the entire Message Batch has ended.
47234724
4725 default: 0
4726
47244727 - `errored: number`
47254728
47264729 Number of requests in the Message Batch that encountered an error.
47274730
47284731 This is zero until processing of the entire Message Batch has ended.
47294732
4733 default: 0
4734
47304735 - `expired: number`
47314736
47324737 Number of requests in the Message Batch that have expired.
47334738
47344739 This is zero until processing of the entire Message Batch has ended.
47354740
4741 default: 0
4742
47364743 - `processing: number`
47374744
47384745 Number of requests in the Message Batch that are processing.
47394746
4747 default: 0
4748
47404749 - `succeeded: number`
47414750
47424751 Number of requests in the Message Batch that have completed successfully.
47434752
47444753 This is zero until processing of the entire Message Batch has ended.
47454754
4755 default: 0
4756
47464757 - `results_url: string or null`
47474758
47484759 URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
from line 4766
47554766
47564767 For Message Batches, this is always `"message_batch"`.
47574768
4758 - `"message_batch"`
4769 default: message_batch
47594770
47604771### Example
47614772
4762```http
4773```bash
47634774curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
47644775 -X POST \
47654776 -H 'anthropic-version: 2023-06-01' \
from line 4778
47674778 -H "X-Api-Key: $ANTHROPIC_API_KEY"
47684779```
47694780
4770#### Response
4781#### Response (200)
47714782
47724783```json
47734784{
from line 4803
47924803
47934804## Delete a Message Batch
47944805
4795**delete** `/v1/messages/batches/{message_batch_id}`
4806**DELETE** `/v1/messages/batches/{message_batch_id}`
47964807
47974808Delete a Message Batch.
47984809
from line 4811
48004811
48014812Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
48024813
4803### Path Parameters
4814### Path parameters
48044815
48054816- `message_batch_id: string`
48064817
48074818 ID of the Message Batch.
48084819
4809### Header Parameters
4820### Headers
48104821
48114822- `"anthropic-beta": optional array of AnthropicBeta`
48124823
from line 4897
48864897
48874898### Returns
48884899
4889- `BetaDeletedMessageBatch object { id, type }`
4900- `BetaDeletedMessageBatch object`
48904901
48914902 - `id: string`
48924903
from line 4909
48984909
48994910 For Message Batches, this is always `"message_batch_deleted"`.
49004911
4901 - `"message_batch_deleted"`
4912 default: message_batch_deleted
49024913
49034914### Example
49044915
4905```http
4916```bash
49064917curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
49074918 -X DELETE \
49084919 -H 'anthropic-version: 2023-06-01' \
from line 4921
49104921 -H "X-Api-Key: $ANTHROPIC_API_KEY"
49114922```
49124923
4913#### Response
4924#### Response (200)
49144925
49154926```json
49164927{
from line 4932
49214932
49224933## Retrieve Message Batch results
49234934
4924**get** `/v1/messages/batches/{message_batch_id}/results`
4935**GET** `/v1/messages/batches/{message_batch_id}/results`
49254936
49264937Streams the results of a Message Batch as a `.jsonl` file.
49274938
from line 4940
49294940
49304941Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
49314942
4932### Path Parameters
4943### Path parameters
49334944
49344945- `message_batch_id: string`
49354946
49364947 ID of the Message Batch.
49374948
4938### Header Parameters
4949### Headers
49394950
49404951- `"anthropic-beta": optional array of AnthropicBeta`
49414952
from line 5026
50155026
50165027### Returns
50175028
5018- `BetaMessageBatchIndividualResponse object { custom_id, result }`
5029- `BetaMessageBatchIndividualResponse object`
50195030
50205031 This is a single line in the response `.jsonl` file and does not represent the response as a whole.
50215032
from line 5042
50315042
50325043 Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.
50335044
5034 - `BetaMessageBatchSucceededResult object { message, type }`
5045 - `BetaMessageBatchSucceededResult object`
50355046
50365047 - `message: BetaMessage`
50375048
from line 5064
50535064
50545065 The time at which the container will expire.
50555066
5067 format: date-time
5068
50565069 - `skills: array of BetaSkill or null`
50575070
50585071 Skills loaded in the container
from line 5074
50615074
50625075 Skill ID
50635076
5077 maxLength: 64, minLength: 1
5078
50645079 - `type: "anthropic" or "custom"`
50655080
50665081 Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
from line 5087
50725087 - `version: string`
50735088
50745089 The resolved version: a skill version ID for custom skills.
5090
5091 maxLength: 64, minLength: 1
50755092
50765093 - `content: array of BetaContentBlock`
50775094
from line 5119
51025119 [{"type": "text", "text": "B)"}]
51035120 ```
51045121
5105 - `BetaTextBlock object { citations, text, type }`
5122 - `BetaTextBlock object`
51065123
51075124 - `citations: array of BetaTextCitation or null`
51085125
from line 5127
51105127
51115128 The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`.
51125129
5113 - `BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }`
5130 - `BetaCitationCharLocation object`
51145131
51155132 - `cited_text: string`
51165133
51175134 - `document_index: number`
51185135
5136 minimum: 0
5137
51195138 - `document_title: string or null`
51205139
51215140 - `end_char_index: number`
from line 5143
51245143
51255144 - `start_char_index: number`
51265145
5146 minimum: 0
5147
51275148 - `type: "char_location"`
51285149
5129 - `"char_location"`
5130
5131 - `BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }`
5150 default: char_location
5151
5152 - `BetaCitationPageLocation object`
51325153
51335154 - `cited_text: string`
51345155
51355156 - `document_index: number`
51365157
5158 minimum: 0
5159
51375160 - `document_title: string or null`
51385161
51395162 - `end_page_number: number`
from line 5165
51425165
51435166 - `start_page_number: number`
51445167
5168 minimum: 1
5169
51455170 - `type: "page_location"`
51465171
5147 - `"page_location"`
5148
5149 - `BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }`
5172 default: page_location
5173
5174 - `BetaCitationContentBlockLocation object`
51505175
51515176 - `cited_text: string`
51525177
from line 5181
51565181
51575182 - `document_index: number`
51585183
5184 minimum: 0
5185
51595186 - `document_title: string or null`
51605187
51615188 - `end_block_index: number`
from line 5197
51705197
51715198 0-based index of the first cited block in the source's `content` array.
51725199
5200 minimum: 0
5201
51735202 - `type: "content_block_location"`
51745203
5175 - `"content_block_location"`
5176
5177 - `BetaCitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }`
5204 default: content_block_location
5205
5206 - `BetaCitationsWebSearchResultLocation object`
51785207
51795208 - `cited_text: string`
51805209
from line 5211
51825211
51835212 - `title: string or null`
51845213
5214 maxLength: 512
5215
51855216 - `type: "web_search_result_location"`
51865217
5187 - `"web_search_result_location"`
5218 default: web_search_result_location
51885219
51895220 - `url: string`
51905221
5191 - `BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }`
5222 - `BetaCitationSearchResultLocation object`
51925223
51935224 - `cited_text: string`
51945225
from line 5239
52085239
52095240 Counted separately from `document_index`; server-side web search results are not included in this count.
52105241
5242 minimum: 0
5243
52115244 - `source: string`
52125245
52135246 - `start_block_index: number`
52145247
52155248 0-based index of the first cited block in the source's `content` array.
52165249
5250 minimum: 0
5251
52175252 - `title: string or null`
52185253
52195254 - `type: "search_result_location"`
52205255
5221 - `"search_result_location"`
5256 default: search_result_location
52225257
52235258 - `text: string`
52245259
5260 maxLength: 5000000, minLength: 0
5261
52255262 - `type: "text"`
52265263
5227 - `"text"`
5228
5229 - `BetaThinkingBlock object { signature, thinking, type }`
5264 default: text
5265
5266 - `BetaThinkingBlock object`
52305267
52315268 - `signature: string`
52325269
from line 5279
52425279
52435280 - `type: "thinking"`
52445281
5245 - `"thinking"`
5246
5247 - `BetaRedactedThinkingBlock object { data, type }`
5282 default: thinking
5283
5284 - `BetaRedactedThinkingBlock object`
52485285
52495286 - `data: string`
52505287
from line 5293
52565293
52575294 - `type: "redacted_thinking"`
52585295
5259 - `"redacted_thinking"`
5260
5261 - `BetaToolUseBlock object { id, input, name, 3 more }`
5296 default: redacted_thinking
5297
5298 - `BetaToolUseBlock object`
52625299
52635300 - `id: string`
52645301
5302 pattern: ^[a-zA-Z0-9_-]+$
5303
52655304 - `input: map[unknown]`
52665305
52675306 - `name: string`
52685307
5308 minLength: 1
5309
52695310 - `type: "tool_use"`
52705311
5271 - `"tool_use"`
5312 default: tool_use
52725313
52735314 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
52745315
52755316 Tool invocation directly from the model.
52765317
5277 - `BetaDirectCaller object { type }`
5318 - `BetaDirectCaller object`
52785319
52795320 Tool invocation directly from the model.
52805321
52815322 - `type: "direct"`
52825323
5283 - `"direct"`
5284
5285 - `BetaServerToolCaller object { tool_id, type }`
5324 - `BetaServerToolCaller object`
52865325
52875326 Tool invocation generated by a server-side tool.
52885327
52895328 - `tool_id: string`
52905329
5330 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5331
52915332 - `type: "code_execution_20250825"`
52925333
5293 - `"code_execution_20250825"`
5294
5295 - `BetaServerToolCaller20260120 object { tool_id, type }`
5334 - `BetaServerToolCaller20260120 object`
52965335
52975336 - `tool_id: string`
52985337
5338 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5339
52995340 - `type: "code_execution_20260120"`
53005341
5301 - `"code_execution_20260120"`
5302
53035342 - `toolset_name: optional string or null`
53045343
53055344 For a toolset member tool_use, the toolset family.
53065345
5307 - `BetaServerToolUseBlock object { id, input, name, 2 more }`
5346 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
5347
5348 - `BetaServerToolUseBlock object`
53085349
53095350 - `id: string`
53105351
5352 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5353
53115354 - `input: map[unknown]`
53125355
53135356 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 5373
53305373
53315374 - `type: "server_tool_use"`
53325375
5333 - `"server_tool_use"`
5376 default: server_tool_use
53345377
53355378 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
53365379
53375380 Tool invocation directly from the model.
53385381
5339 - `BetaDirectCaller object { type }`
5382 - `BetaDirectCaller object`
53405383
53415384 Tool invocation directly from the model.
53425385
5343 - `BetaServerToolCaller object { tool_id, type }`
5386 - `BetaServerToolCaller object`
53445387
53455388 Tool invocation generated by a server-side tool.
53465389
5347 - `BetaServerToolCaller20260120 object { tool_id, type }`
5348
5349 - `BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }`
5390 - `BetaServerToolCaller20260120 object`
5391
5392 - `BetaWebSearchToolResultBlock object`
53505393
53515394 - `content: BetaWebSearchToolResultBlockContent`
53525395
5353 - `BetaWebSearchToolResultError object { error_code, type }`
5396 - `BetaWebSearchToolResultError object`
53545397
53555398 - `error_code: BetaWebSearchToolResultErrorCode`
53565399
from line 5411
53685411
53695412 - `type: "web_search_tool_result_error"`
53705413
5371 - `"web_search_tool_result_error"`
5414 default: web_search_tool_result_error
53725415
53735416 - `array of BetaWebSearchResultBlock`
53745417
from line 5423
53805423
53815424 - `type: "web_search_result"`
53825425
5383 - `"web_search_result"`
5426 default: web_search_result
53845427
53855428 - `url: string`
53865429
53875430 - `tool_use_id: string`
53885431
5432 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5433
53895434 - `type: "web_search_tool_result"`
53905435
5391 - `"web_search_tool_result"`
5436 default: web_search_tool_result
53925437
53935438 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
53945439
53955440 Tool invocation directly from the model.
53965441
5397 - `BetaDirectCaller object { type }`
5442 - `BetaDirectCaller object`
53985443
53995444 Tool invocation directly from the model.
54005445
5401 - `BetaServerToolCaller object { tool_id, type }`
5446 - `BetaServerToolCaller object`
54025447
54035448 Tool invocation generated by a server-side tool.
54045449
5405 - `BetaServerToolCaller20260120 object { tool_id, type }`
5406
5407 - `BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }`
5450 - `BetaServerToolCaller20260120 object`
5451
5452 - `BetaWebFetchToolResultBlock object`
54085453
54095454 - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock`
54105455
5411 - `BetaWebFetchToolResultErrorBlock object { error_code, type }`
5456 - `BetaWebFetchToolResultErrorBlock object`
54125457
54135458 - `error_code: BetaWebFetchToolResultErrorCode`
54145459
from line 5477
54325477
54335478 - `type: "web_fetch_tool_result_error"`
54345479
5435 - `"web_fetch_tool_result_error"`
5436
5437 - `BetaWebFetchBlock object { content, retrieved_at, type, url }`
5480 default: web_fetch_tool_result_error
5481
5482 - `BetaWebFetchBlock object`
54385483
54395484 - `content: BetaDocumentBlock`
54405485
from line 5489
54445489
54455490 - `enabled: boolean`
54465491
5492 default: false
5493
54475494 - `source: BetaBase64PDFSource or BetaPlainTextSource`
54485495
5449 - `BetaBase64PDFSource object { data, media_type, type }`
5496 - `BetaBase64PDFSource object`
54505497
54515498 - `data: string`
54525499
5500 format: byte
5501
54535502 - `media_type: "application/pdf"`
54545503
5455 - `"application/pdf"`
5456
54575504 - `type: "base64"`
54585505
5459 - `"base64"`
5460
5461 - `BetaPlainTextSource object { data, media_type, type }`
5506 - `BetaPlainTextSource object`
54625507
54635508 - `data: string`
54645509
54655510 - `media_type: "text/plain"`
54665511
5467 - `"text/plain"`
5468
54695512 - `type: "text"`
54705513
5471 - `"text"`
5472
54735514 - `title: string or null`
54745515
54755516 The title of the document
54765517
54775518 - `type: "document"`
54785519
5479 - `"document"`
5520 default: document
54805521
54815522 - `retrieved_at: string or null`
54825523
from line 5525
54845525
54855526 - `type: "web_fetch_result"`
54865527
5487 - `"web_fetch_result"`
5528 default: web_fetch_result
54885529
54895530 - `url: string`
54905531
from line 5533
54925533
54935534 - `tool_use_id: string`
54945535
5536 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5537
54955538 - `type: "web_fetch_tool_result"`
54965539
5497 - `"web_fetch_tool_result"`
5540 default: web_fetch_tool_result
54985541
54995542 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
55005543
55015544 Tool invocation directly from the model.
55025545
5503 - `BetaDirectCaller object { type }`
5546 - `BetaDirectCaller object`
55045547
55055548 Tool invocation directly from the model.
55065549
5507 - `BetaServerToolCaller object { tool_id, type }`
5550 - `BetaServerToolCaller object`
55085551
55095552 Tool invocation generated by a server-side tool.
55105553
5511 - `BetaServerToolCaller20260120 object { tool_id, type }`
5512
5513 - `BetaAdvisorToolResultBlock object { content, tool_use_id, type }`
5554 - `BetaServerToolCaller20260120 object`
5555
5556 - `BetaAdvisorToolResultBlock object`
55145557
55155558 - `content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock`
55165559
5517 - `BetaAdvisorToolResultError object { error_code, type }`
5560 - `BetaAdvisorToolResultError object`
55185561
55195562 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
55205563
from line 5577
55345577
55355578 - `type: "advisor_tool_result_error"`
55365579
5537 - `"advisor_tool_result_error"`
5538
5539 - `BetaAdvisorResultBlock object { stop_reason, text, type }`
5580 default: advisor_tool_result_error
5581
5582 - `BetaAdvisorResultBlock object`
55405583
55415584 - `stop_reason: string or null`
55425585
from line 5589
55465589
55475590 - `type: "advisor_result"`
55485591
5549 - `"advisor_result"`
5550
5551 - `BetaAdvisorRedactedResultBlock object { encrypted_content, stop_reason, type }`
5592 default: advisor_result
5593
5594 - `BetaAdvisorRedactedResultBlock object`
55525595
55535596 - `encrypted_content: string`
55545597
from line 5603
55605603
55615604 - `type: "advisor_redacted_result"`
55625605
5563 - `"advisor_redacted_result"`
5606 default: advisor_redacted_result
55645607
55655608 - `tool_use_id: string`
55665609
5610 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5611
55675612 - `type: "advisor_tool_result"`
55685613
5569 - `"advisor_tool_result"`
5570
5571 - `BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }`
5614 default: advisor_tool_result
5615
5616 - `BetaCodeExecutionToolResultBlock object`
55725617
55735618 - `content: BetaCodeExecutionToolResultBlockContent`
55745619
55755620 Code execution result with encrypted stdout for PFC + web_search results.
55765621
5577 - `BetaCodeExecutionToolResultError object { error_code, type }`
5622 - `BetaCodeExecutionToolResultError object`
55785623
55795624 - `error_code: BetaCodeExecutionToolResultErrorCode`
55805625
from line 5633
55885633
55895634 - `type: "code_execution_tool_result_error"`
55905635
5591 - `"code_execution_tool_result_error"`
5592
5593 - `BetaCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
5636 default: code_execution_tool_result_error
5637
5638 - `BetaCodeExecutionResultBlock object`
55945639
55955640 - `content: array of BetaCodeExecutionOutputBlock`
55965641
from line 5643
55985643
55995644 - `type: "code_execution_output"`
56005645
5601 - `"code_execution_output"`
5646 default: code_execution_output
56025647
56035648 - `return_code: number`
56045649
from line 5653
56085653
56095654 - `type: "code_execution_result"`
56105655
5611 - `"code_execution_result"`
5612
5613 - `BetaEncryptedCodeExecutionResultBlock object { content, encrypted_stdout, return_code, 2 more }`
5656 default: code_execution_result
5657
5658 - `BetaEncryptedCodeExecutionResultBlock object`
56145659
56155660 Code execution result with encrypted stdout for PFC + web_search results.
56165661
from line 5665
56205665
56215666 - `type: "code_execution_output"`
56225667
5668 default: code_execution_output
5669
56235670 - `encrypted_stdout: string`
56245671
56255672 - `return_code: number`
from line 5675
56285675
56295676 - `type: "encrypted_code_execution_result"`
56305677
5631 - `"encrypted_code_execution_result"`
5678 default: encrypted_code_execution_result
56325679
56335680 - `tool_use_id: string`
56345681
5682 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5683
56355684 - `type: "code_execution_tool_result"`
56365685
5637 - `"code_execution_tool_result"`
5638
5639 - `BetaBashCodeExecutionToolResultBlock object { content, tool_use_id, type }`
5686 default: code_execution_tool_result
5687
5688 - `BetaBashCodeExecutionToolResultBlock object`
56405689
56415690 - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock`
56425691
5643 - `BetaBashCodeExecutionToolResultError object { error_code, type }`
5692 - `BetaBashCodeExecutionToolResultError object`
56445693
56455694 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
56465695
from line 5705
56565705
56575706 - `type: "bash_code_execution_tool_result_error"`
56585707
5659 - `"bash_code_execution_tool_result_error"`
5660
5661 - `BetaBashCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
5708 default: bash_code_execution_tool_result_error
5709
5710 - `BetaBashCodeExecutionResultBlock object`
56625711
56635712 - `content: array of BetaBashCodeExecutionOutputBlock`
56645713
from line 5715
56665715
56675716 - `type: "bash_code_execution_output"`
56685717
5669 - `"bash_code_execution_output"`
5718 default: bash_code_execution_output
56705719
56715720 - `return_code: number`
56725721
from line 5725
56765725
56775726 - `type: "bash_code_execution_result"`
56785727
5679 - `"bash_code_execution_result"`
5728 default: bash_code_execution_result
56805729
56815730 - `tool_use_id: string`
56825731
5732 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5733
56835734 - `type: "bash_code_execution_tool_result"`
56845735
5685 - `"bash_code_execution_tool_result"`
5686
5687 - `BetaTextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }`
5736 default: bash_code_execution_tool_result
5737
5738 - `BetaTextEditorCodeExecutionToolResultBlock object`
56885739
56895740 - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock`
56905741
5691 - `BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }`
5742 - `BetaTextEditorCodeExecutionToolResultError object`
56925743
56935744 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
56945745
from line 5757
57065757
57075758 - `type: "text_editor_code_execution_tool_result_error"`
57085759
5709 - `"text_editor_code_execution_tool_result_error"`
5710
5711 - `BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }`
5760 default: text_editor_code_execution_tool_result_error
5761
5762 - `BetaTextEditorCodeExecutionViewResultBlock object`
57125763
57135764 - `content: string`
57145765
from line 5779
57285779
57295780 - `type: "text_editor_code_execution_view_result"`
57305781
5731 - `"text_editor_code_execution_view_result"`
5732
5733 - `BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }`
5782 default: text_editor_code_execution_view_result
5783
5784 - `BetaTextEditorCodeExecutionCreateResultBlock object`
57345785
57355786 - `is_file_update: boolean`
57365787
57375788 - `type: "text_editor_code_execution_create_result"`
57385789
5739 - `"text_editor_code_execution_create_result"`
5740
5741 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }`
5790 default: text_editor_code_execution_create_result
5791
5792 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object`
57425793
57435794 - `lines: array of string or null`
57445795
from line 5803
57525803
57535804 - `type: "text_editor_code_execution_str_replace_result"`
57545805
5755 - `"text_editor_code_execution_str_replace_result"`
5806 default: text_editor_code_execution_str_replace_result
57565807
57575808 - `tool_use_id: string`
57585809
5810 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5811
57595812 - `type: "text_editor_code_execution_tool_result"`
57605813
5761 - `"text_editor_code_execution_tool_result"`
5762
5763 - `BetaToolSearchToolResultBlock object { content, tool_use_id, type }`
5814 default: text_editor_code_execution_tool_result
5815
5816 - `BetaToolSearchToolResultBlock object`
57645817
57655818 - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock`
57665819
5767 - `BetaToolSearchToolResultError object { error_code, error_message, type }`
5820 - `BetaToolSearchToolResultError object`
57685821
57695822 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
57705823
from line 5833
57805833
57815834 - `type: "tool_search_tool_result_error"`
57825835
5783 - `"tool_search_tool_result_error"`
5784
5785 - `BetaToolSearchToolSearchResultBlock object { tool_references, type }`
5836 default: tool_search_tool_result_error
5837
5838 - `BetaToolSearchToolSearchResultBlock object`
57865839
57875840 - `tool_references: array of BetaToolReferenceBlock`
57885841
57895842 - `tool_name: string`
57905843
5844 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
5845
57915846 - `type: "tool_reference"`
57925847
5793 - `"tool_reference"`
5848 default: tool_reference
57945849
57955850 - `type: "tool_search_tool_search_result"`
57965851
5797 - `"tool_search_tool_search_result"`
5852 default: tool_search_tool_search_result
57985853
57995854 - `tool_use_id: string`
58005855
5856 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
5857
58015858 - `type: "tool_search_tool_result"`
58025859
5803 - `"tool_search_tool_result"`
5804
5805 - `BetaMCPToolUseBlock object { id, input, name, 2 more }`
5860 default: tool_search_tool_result
5861
5862 - `BetaMCPToolUseBlock object`
58065863
58075864 - `id: string`
58085865
5866 pattern: ^[a-zA-Z0-9_-]+$
5867
58095868 - `input: map[unknown]`
58105869
58115870 - `name: string`
from line 5877
58185877
58195878 - `type: "mcp_tool_use"`
58205879
5821 - `"mcp_tool_use"`
5822
5823 - `BetaMCPToolResultBlock object { content, is_error, tool_use_id, type }`
5880 default: mcp_tool_use
5881
5882 - `BetaMCPToolResultBlock object`
58245883
58255884 - `content: string or array of BetaTextBlock`
58265885
from line 5895
58365895
58375896 - `text: string`
58385897
5898 maxLength: 5000000, minLength: 0
5899
58395900 - `type: "text"`
58405901
5902 default: text
5903
58415904 - `is_error: boolean`
58425905
5906 default: false
5907
58435908 - `tool_use_id: string`
58445909
5910 pattern: ^[a-zA-Z0-9_-]+$
5911
58455912 - `type: "mcp_tool_result"`
58465913
5847 - `"mcp_tool_result"`
5848
5849 - `BetaContainerUploadBlock object { file_id, type }`
5914 default: mcp_tool_result
5915
5916 - `BetaContainerUploadBlock object`
58505917
58515918 Response model for a file uploaded to the container.
58525919
from line 5921
58545921
58555922 - `type: "container_upload"`
58565923
5857 - `"container_upload"`
5858
5859 - `BetaCompactionBlock object { content, encrypted_content, type }`
5924 default: container_upload
5925
5926 - `BetaCompactionBlock object`
58605927
58615928 A compaction block returned when autocompact is triggered.
58625929
from line 5941
58745941
58755942 - `type: "compaction"`
58765943
5877 - `"compaction"`
5878
5879 - `BetaFallbackBlock object { from, to, trigger, type }`
5944 default: compaction
5945
5946 - `BetaFallbackBlock object`
58805947
58815948 Marks the point in `content` where one model's output gives way to the next.
58825949
from line 6069
60026069
60036070 - `type: "refusal"`
60046071
6005 - `"refusal"`
6072 default: refusal
60066073
60076074 - `type: "fallback"`
60086075
6009 - `"fallback"`
6076 default: fallback
60106077
60116078 - `context_management: BetaContextManagementResponse or null`
60126079
from line 6085
60186085
60196086 List of context management edits that were applied.
60206087
6021 - `BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }`
6088 - `BetaClearToolUses20250919EditResponse object`
60226089
60236090 - `cleared_input_tokens: number`
60246091
60256092 Number of input tokens cleared by this edit.
60266093
6094 minimum: 0
6095
60276096 - `cleared_tool_uses: number`
60286097
60296098 Number of tool uses that were cleared.
60306099
6100 minimum: 0
6101
60316102 - `type: "clear_tool_uses_20250919"`
60326103
60336104 The type of context management edit applied.
60346105
6035 - `"clear_tool_uses_20250919"`
6036
6037 - `BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }`
6106 default: clear_tool_uses_20250919
6107
6108 - `BetaClearThinking20251015EditResponse object`
60386109
60396110 - `cleared_input_tokens: number`
60406111
60416112 Number of input tokens cleared by this edit.
60426113
6114 minimum: 0
6115
60436116 - `cleared_thinking_turns: number`
60446117
60456118 Number of thinking turns that were cleared.
60466119
6120 minimum: 0
6121
60476122 - `type: "clear_thinking_20251015"`
60486123
60496124 The type of context management edit applied.
60506125
6051 - `"clear_thinking_20251015"`
6126 default: clear_thinking_20251015
60526127
60536128 - `diagnostics: BetaDiagnostics or null`
60546129
from line 6134
60596134
60606135 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.
60616136
6062 - `BetaCacheMissModelChanged object { cache_missed_input_tokens, type }`
6137 - `BetaCacheMissModelChanged object`
60636138
60646139 - `cache_missed_input_tokens: number`
60656140
from line 6142
60676142
60686143 - `type: "model_changed"`
60696144
6070 - `"model_changed"`
6071
6072 - `BetaCacheMissSystemChanged object { cache_missed_input_tokens, type }`
6145 default: model_changed
6146
6147 - `BetaCacheMissSystemChanged object`
60736148
60746149 - `cache_missed_input_tokens: number`
60756150
from line 6152
60776152
60786153 - `type: "system_changed"`
60796154
6080 - `"system_changed"`
6081
6082 - `BetaCacheMissToolsChanged object { cache_missed_input_tokens, type }`
6155 default: system_changed
6156
6157 - `BetaCacheMissToolsChanged object`
60836158
60846159 - `cache_missed_input_tokens: number`
60856160
from line 6162
60876162
60886163 - `type: "tools_changed"`
60896164
6090 - `"tools_changed"`
6091
6092 - `BetaCacheMissMessagesChanged object { cache_missed_input_tokens, type }`
6165 default: tools_changed
6166
6167 - `BetaCacheMissMessagesChanged object`
60936168
60946169 - `cache_missed_input_tokens: number`
60956170
from line 6172
60976172
60986173 - `type: "messages_changed"`
60996174
6100 - `"messages_changed"`
6101
6102 - `BetaCacheMissPreviousMessageNotFound object { type }`
6175 default: messages_changed
6176
6177 - `BetaCacheMissPreviousMessageNotFound object`
61036178
61046179 - `type: "previous_message_not_found"`
61056180
6106 - `"previous_message_not_found"`
6107
6108 - `BetaCacheMissUnavailable object { type }`
6181 default: previous_message_not_found
6182
6183 - `BetaCacheMissUnavailable object`
61096184
61106185 - `type: "unavailable"`
61116186
6112 - `"unavailable"`
6187 default: unavailable
61136188
61146189 - `model: Model`
61156190
from line 6198
61236198
61246199 This will always be `"assistant"`.
61256200
6126 - `"assistant"`
6201 default: assistant
61276202
61286203 - `stop_details: BetaRefusalStopDetails or null`
61296204
from line 6285
62106285
62116286 - `type: "refusal"`
62126287
6213 - `"refusal"`
6288 default: refusal
62146289
62156290 - `stop_reason: BetaStopReason or null`
62166291
from line 6331
62566331
62576332 For Messages, this is always `"message"`.
62586333
6259 - `"message"`
6334 default: message
62606335
62616336 - `usage: BetaUsage`
62626337
from line 6353
62786353
62796354 The number of input tokens used to create the 1 hour cache entry.
62806355
6356 default: 0, minimum: 0
6357
62816358 - `ephemeral_5m_input_tokens: number`
62826359
62836360 The number of input tokens used to create the 5 minute cache entry.
62846361
6362 default: 0, minimum: 0
6363
62856364 - `cache_creation_input_tokens: number or null`
62866365
62876366 The number of input tokens used to create the cache entry.
62886367
6368 minimum: 0
6369
62896370 - `cache_read_input_tokens: number or null`
62906371
62916372 The number of input tokens read from the cache.
6373
6374 minimum: 0
62926375
62936376 - `fallback_credit: BetaFallbackCreditUsage or null`
62946377
from line 6386
63036386 resulting shift is zero because there was nothing to move. `not_applied`:
63046387 no reprice was applied; the arm's `reason` says why.
63056388
6306 - `BetaFallbackCreditRedeemed object { type }`
6389 - `BetaFallbackCreditRedeemed object`
63076390
63086391 The reprice was applied: the retry is billed as if the conversation
63096392 had been on the retry model all along.
63106393
63116394 - `type: "redeemed"`
63126395
6313 - `"redeemed"`
6314
6315 - `BetaFallbackCreditNotApplied object { reason, type, remove_to_redeem }`
6396 default: redeemed
6397
6398 - `BetaFallbackCreditNotApplied object`
63166399
63176400 No reprice was applied; `reason` says why.
63186401
from line 6432
63496432
63506433 - `type: "not_applied"`
63516434
6352 - `"not_applied"`
6435 default: not_applied
63536436
63546437 - `remove_to_redeem: optional array of string or null`
63556438
from line 6453
63706453
63716454 The number of input tokens which were used.
63726455
6456 minimum: 0
6457
63736458 - `iterations: BetaIterationsUsage or null`
63746459
63756460 Per-iteration token usage breakdown.
from line 6465
63806465 - Calculate the true context window size from the last iteration
63816466 - Understand token accumulation across server-side tool use loops
63826467
6383 - `BetaMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
6468 - `BetaMessageIterationUsage object`
63846469
63856470 Token usage for a sampling iteration.
63866471
from line 6477
63926477
63936478 The number of input tokens used to create the cache entry.
63946479
6480 default: 0, minimum: 0
6481
63956482 - `cache_read_input_tokens: number`
63966483
63976484 The number of input tokens read from the cache.
63986485
6486 default: 0, minimum: 0
6487
63996488 - `input_tokens: number`
64006489
64016490 The number of input tokens which were used.
64026491
6492 minimum: 0
6493
64036494 - `model: Model`
64046495
64056496 The model that will complete your prompt.
from line 6501
64106501
64116502 The number of output tokens which were used.
64126503
6504 minimum: 0
6505
64136506 - `type: "message"`
64146507
64156508 Usage for a sampling iteration
64166509
6417 - `"message"`
6418
6419 - `BetaCompactionIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }`
6510 default: message
6511
6512 - `BetaCompactionIterationUsage object`
64206513
64216514 Token usage for a compaction iteration.
64226515
from line 6521
64286521
64296522 The number of input tokens used to create the cache entry.
64306523
6524 default: 0, minimum: 0
6525
64316526 - `cache_read_input_tokens: number`
64326527
64336528 The number of input tokens read from the cache.
64346529
6530 default: 0, minimum: 0
6531
64356532 - `input_tokens: number`
64366533
64376534 The number of input tokens which were used.
64386535
6536 minimum: 0
6537
64396538 - `output_tokens: number`
64406539
64416540 The number of output tokens which were used.
64426541
6542 minimum: 0
6543
64436544 - `type: "compaction"`
64446545
64456546 Usage for a compaction iteration
64466547
6447 - `"compaction"`
6448
6449 - `BetaAdvisorMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
6548 default: compaction
6549
6550 - `BetaAdvisorMessageIterationUsage object`
64506551
64516552 Token usage for an advisor sub-inference iteration.
64526553
from line 6559
64586559
64596560 The number of input tokens used to create the cache entry.
64606561
6562 default: 0, minimum: 0
6563
64616564 - `cache_read_input_tokens: number`
64626565
64636566 The number of input tokens read from the cache.
64646567
6568 default: 0, minimum: 0
6569
64656570 - `input_tokens: number`
64666571
64676572 The number of input tokens which were used.
64686573
6574 minimum: 0
6575
64696576 - `model: Model`
64706577
64716578 The model that will complete your prompt.
from line 6583
64766583
64776584 The number of output tokens which were used.
64786585
6586 minimum: 0
6587
64796588 - `type: "advisor_message"`
64806589
64816590 Usage for an advisor sub-inference iteration
64826591
6483 - `"advisor_message"`
6484
6485 - `BetaFallbackMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
6592 default: advisor_message
6593
6594 - `BetaFallbackMessageIterationUsage object`
64866595
64876596 Token usage for the fallback-model attempt of a server-side fallback request.
64886597
from line 6608
64996608
65006609 The number of input tokens used to create the cache entry.
65016610
6611 default: 0, minimum: 0
6612
65026613 - `cache_read_input_tokens: number`
65036614
65046615 The number of input tokens read from the cache.
65056616
6617 default: 0, minimum: 0
6618
65066619 - `input_tokens: number`
65076620
65086621 The number of input tokens which were used.
65096622
6623 minimum: 0
6624
65106625 - `model: Model`
65116626
65126627 The model that will complete your prompt.
from line 6632
65176632
65186633 The number of output tokens which were used.
65196634
6635 minimum: 0
6636
65206637 - `type: "fallback_message"`
65216638
65226639 Usage for the fallback-model attempt that served the response
65236640
6524 - `"fallback_message"`
6641 default: fallback_message
65256642
65266643 - `output_tokens: number`
65276644
65286645 The number of output tokens which were used.
6646
6647 minimum: 0
65296648
65306649 - `output_tokens_details: BetaOutputTokensDetails or null`
65316650
from line 6666
65476666 generation count by a small number of tokens. Always ≤ `output_tokens`;
65486667 `output_tokens - thinking_tokens` approximates the non-reasoning output.
65496668
6669 default: 0, minimum: 0
6670
65506671 - `server_tool_use: BetaServerToolUsage or null`
65516672
65526673 The number of server tool requests.
from line 6676
65556676
65566677 The number of web fetch tool requests.
65576678
6679 default: 0, minimum: 0
6680
65586681 - `web_search_requests: number`
65596682
65606683 The number of web search tool requests.
65616684
6685 default: 0, minimum: 0
6686
65626687 - `service_tier: "standard" or "priority" or "batch" or null`
65636688
65646689 If the request used the priority, standard, or batch tier.
from line 6704
65796704
65806705 - `type: "succeeded"`
65816706
6582 - `"succeeded"`
6583
6584 - `BetaMessageBatchErroredResult object { error, type }`
6707 default: succeeded
6708
6709 - `BetaMessageBatchErroredResult object`
65856710
65866711 - `error: BetaErrorResponse`
65876712
65886713 - `error: BetaError`
65896714
6590 - `BetaInvalidRequestError object { message, type }`
6715 - `BetaInvalidRequestError object`
65916716
65926717 - `message: string`
65936718
6719 default: Invalid request
6720
65946721 - `type: "invalid_request_error"`
65956722
6596 - `"invalid_request_error"`
6597
6598 - `BetaAuthenticationError object { message, type }`
6723 default: invalid_request_error
6724
6725 - `BetaAuthenticationError object`
65996726
66006727 - `message: string`
66016728
6729 default: Authentication error
6730
66026731 - `type: "authentication_error"`
66036732
6604 - `"authentication_error"`
6605
6606 - `BetaBillingError object { message, type }`
6733 default: authentication_error
6734
6735 - `BetaBillingError object`
66076736
66086737 - `message: string`
66096738
6739 default: Billing error
6740
66106741 - `type: "billing_error"`
66116742
6612 - `"billing_error"`
6613
6614 - `BetaPermissionError object { message, type }`
6743 default: billing_error
6744
6745 - `BetaPermissionError object`
66156746
66166747 - `message: string`
66176748
6749 default: Permission denied
6750
66186751 - `type: "permission_error"`
66196752
6620 - `"permission_error"`
6621
6622 - `BetaNotFoundError object { message, type }`
6753 default: permission_error
6754
6755 - `BetaNotFoundError object`
66236756
66246757 - `message: string`
66256758
6759 default: Not found
6760
66266761 - `type: "not_found_error"`
66276762
6628 - `"not_found_error"`
6629
6630 - `BetaRateLimitError object { message, type }`
6763 default: not_found_error
6764
6765 - `BetaRateLimitError object`
66316766
66326767 - `message: string`
66336768
6769 default: Rate limited
6770
66346771 - `type: "rate_limit_error"`
66356772
6636 - `"rate_limit_error"`
6637
6638 - `BetaGatewayTimeoutError object { message, type }`
6773 default: rate_limit_error
6774
6775 - `BetaGatewayTimeoutError object`
66396776
66406777 - `message: string`
66416778
6779 default: Request timeout
6780
66426781 - `type: "timeout_error"`
66436782
6644 - `"timeout_error"`
6645
6646 - `BetaAPIError object { message, type }`
6783 default: timeout_error
6784
6785 - `BetaAPIError object`
66476786
66486787 - `message: string`
66496788
6789 default: Internal server error
6790
66506791 - `type: "api_error"`
66516792
6652 - `"api_error"`
6653
6654 - `BetaOverloadedError object { message, type }`
6793 default: api_error
6794
6795 - `BetaOverloadedError object`
66556796
66566797 - `message: string`
66576798
6799 default: Overloaded
6800
66586801 - `type: "overloaded_error"`
66596802
6660 - `"overloaded_error"`
6803 default: overloaded_error
66616804
66626805 - `request_id: string or null`
66636806
66646807 - `type: "error"`
66656808
6666 - `"error"`
6809 default: error
66676810
66686811 - `type: "errored"`
66696812
6670 - `"errored"`
6671
6672 - `BetaMessageBatchCanceledResult object { type }`
6813 default: errored
6814
6815 - `BetaMessageBatchCanceledResult object`
66736816
66746817 - `type: "canceled"`
66756818
6676 - `"canceled"`
6677
6678 - `BetaMessageBatchExpiredResult object { type }`
6819 default: canceled
6820
6821 - `BetaMessageBatchExpiredResult object`
66796822
66806823 - `type: "expired"`
66816824
6682 - `"expired"`
6825 default: expired
66836826
66846827### Example
66856828
6686```http
6829```bash
66876830curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \
66886831 -H 'anthropic-version: 2023-06-01' \
66896832 -H 'anthropic-beta: message-batches-2024-09-24' \
66906833 -H "X-Api-Key: $ANTHROPIC_API_KEY"
66916834```
66926835
6693## Domain Types
6836## Domain types
66946837
66956838### Beta Deleted Message Batch
66966839
6697- `BetaDeletedMessageBatch object { id, type }`
6840- `BetaDeletedMessageBatch object`
66986841
66996842 - `id: string`
67006843
from line 6849
67066849
67076850 For Message Batches, this is always `"message_batch_deleted"`.
67086851
6709 - `"message_batch_deleted"`
6852 default: message_batch_deleted
67106853
67116854### Beta Message Batch
67126855
6713- `BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }`
6856- `BetaMessageBatch object`
67146857
67156858 - `id: string`
67166859
from line 6865
67226865
67236866 RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
67246867
6868 format: date-time
6869
67256870 - `cancel_initiated_at: string or null`
67266871
67276872 RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
67286873
6874 format: date-time
6875
67296876 - `created_at: string`
67306877
67316878 RFC 3339 datetime string representing the time at which the Message Batch was created.
67326879
6880 format: date-time
6881
67336882 - `ended_at: string or null`
67346883
67356884 RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
67366885
67376886 Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
67386887
6888 format: date-time
6889
67396890 - `expires_at: string`
67406891
67416892 RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
67426893
6894 format: date-time
6895
67436896 - `processing_status: "in_progress" or "canceling" or "ended"`
67446897
67456898 Processing status of the Message Batch.
from line 6915
67626915
67636916 This is zero until processing of the entire Message Batch has ended.
67646917
6918 default: 0
6919
67656920 - `errored: number`
67666921
67676922 Number of requests in the Message Batch that encountered an error.
67686923
67696924 This is zero until processing of the entire Message Batch has ended.
67706925
6926 default: 0
6927
67716928 - `expired: number`
67726929
67736930 Number of requests in the Message Batch that have expired.
67746931
67756932 This is zero until processing of the entire Message Batch has ended.
67766933
6934 default: 0
6935
67776936 - `processing: number`
67786937
67796938 Number of requests in the Message Batch that are processing.
67806939
6940 default: 0
6941
67816942 - `succeeded: number`
67826943
67836944 Number of requests in the Message Batch that have completed successfully.
67846945
67856946 This is zero until processing of the entire Message Batch has ended.
67866947
6948 default: 0
6949
67876950 - `results_url: string or null`
67886951
67896952 URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
from line 6959
67966959
67976960 For Message Batches, this is always `"message_batch"`.
67986961
6799 - `"message_batch"`
6962 default: message_batch
68006963
68016964### Beta Message Batch Canceled Result
68026965
6803- `BetaMessageBatchCanceledResult object { type }`
6966- `BetaMessageBatchCanceledResult object`
68046967
68056968 - `type: "canceled"`
68066969
6807 - `"canceled"`
6970 default: canceled
68086971
68096972### Beta Message Batch Errored Result
68106973
6811- `BetaMessageBatchErroredResult object { error, type }`
6974- `BetaMessageBatchErroredResult object`
68126975
68136976 - `error: BetaErrorResponse`
68146977
68156978 - `error: BetaError`
68166979
6817 - `BetaInvalidRequestError object { message, type }`
6980 - `BetaInvalidRequestError object`
68186981
68196982 - `message: string`
68206983
6984 default: Invalid request
6985
68216986 - `type: "invalid_request_error"`
68226987
6823 - `"invalid_request_error"`
6824
6825 - `BetaAuthenticationError object { message, type }`
6988 default: invalid_request_error
6989
6990 - `BetaAuthenticationError object`
68266991
68276992 - `message: string`
68286993
6994 default: Authentication error
6995
68296996 - `type: "authentication_error"`
68306997
6831 - `"authentication_error"`
6832
6833 - `BetaBillingError object { message, type }`
6998 default: authentication_error
6999
7000 - `BetaBillingError object`
68347001
68357002 - `message: string`
68367003
7004 default: Billing error
7005
68377006 - `type: "billing_error"`
68387007
6839 - `"billing_error"`
6840
6841 - `BetaPermissionError object { message, type }`
7008 default: billing_error
7009
7010 - `BetaPermissionError object`
68427011
68437012 - `message: string`
68447013
7014 default: Permission denied
7015
68457016 - `type: "permission_error"`
68467017
6847 - `"permission_error"`
6848
6849 - `BetaNotFoundError object { message, type }`
7018 default: permission_error
7019
7020 - `BetaNotFoundError object`
68507021
68517022 - `message: string`
68527023
7024 default: Not found
7025
68537026 - `type: "not_found_error"`
68547027
6855 - `"not_found_error"`
6856
6857 - `BetaRateLimitError object { message, type }`
7028 default: not_found_error
7029
7030 - `BetaRateLimitError object`
68587031
68597032 - `message: string`
68607033
7034 default: Rate limited
7035
68617036 - `type: "rate_limit_error"`
68627037
6863 - `"rate_limit_error"`
6864
6865 - `BetaGatewayTimeoutError object { message, type }`
7038 default: rate_limit_error
7039
7040 - `BetaGatewayTimeoutError object`
68667041
68677042 - `message: string`
68687043
7044 default: Request timeout
7045
68697046 - `type: "timeout_error"`
68707047
6871 - `"timeout_error"`
6872
6873 - `BetaAPIError object { message, type }`
7048 default: timeout_error
7049
7050 - `BetaAPIError object`
68747051
68757052 - `message: string`
68767053
7054 default: Internal server error
7055
68777056 - `type: "api_error"`
68787057
6879 - `"api_error"`
6880
6881 - `BetaOverloadedError object { message, type }`
7058 default: api_error
7059
7060 - `BetaOverloadedError object`
68827061
68837062 - `message: string`
68847063
7064 default: Overloaded
7065
68857066 - `type: "overloaded_error"`
68867067
6887 - `"overloaded_error"`
7068 default: overloaded_error
68887069
68897070 - `request_id: string or null`
68907071
68917072 - `type: "error"`
68927073
6893 - `"error"`
7074 default: error
68947075
68957076 - `type: "errored"`
68967077
6897 - `"errored"`
7078 default: errored
68987079
68997080### Beta Message Batch Expired Result
69007081
6901- `BetaMessageBatchExpiredResult object { type }`
7082- `BetaMessageBatchExpiredResult object`
69027083
69037084 - `type: "expired"`
69047085
6905 - `"expired"`
7086 default: expired
69067087
69077088### Beta Message Batch Individual Response
69087089
6909- `BetaMessageBatchIndividualResponse object { custom_id, result }`
7090- `BetaMessageBatchIndividualResponse object`
69107091
69117092 This is a single line in the response `.jsonl` file and does not represent the response as a whole.
69127093
from line 7103
69227103
69237104 Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.
69247105
6925 - `BetaMessageBatchSucceededResult object { message, type }`
7106 - `BetaMessageBatchSucceededResult object`
69267107
69277108 - `message: BetaMessage`
69287109
from line 7125
69447125
69457126 The time at which the container will expire.
69467127
7128 format: date-time
7129
69477130 - `skills: array of BetaSkill or null`
69487131
69497132 Skills loaded in the container
from line 7135
69527135
69537136 Skill ID
69547137
7138 maxLength: 64, minLength: 1
7139
69557140 - `type: "anthropic" or "custom"`
69567141
69577142 Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
from line 7148
69637148 - `version: string`
69647149
69657150 The resolved version: a skill version ID for custom skills.
7151
7152 maxLength: 64, minLength: 1
69667153
69677154 - `content: array of BetaContentBlock`
69687155
from line 7180
69937180 [{"type": "text", "text": "B)"}]
69947181 ```
69957182
6996 - `BetaTextBlock object { citations, text, type }`
7183 - `BetaTextBlock object`
69977184
69987185 - `citations: array of BetaTextCitation or null`
69997186
from line 7188
70017188
70027189 The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`.
70037190
7004 - `BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }`
7191 - `BetaCitationCharLocation object`
70057192
70067193 - `cited_text: string`
70077194
70087195 - `document_index: number`
70097196
7197 minimum: 0
7198
70107199 - `document_title: string or null`
70117200
70127201 - `end_char_index: number`
from line 7204
70157204
70167205 - `start_char_index: number`
70177206
7207 minimum: 0
7208
70187209 - `type: "char_location"`
70197210
7020 - `"char_location"`
7021
7022 - `BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }`
7211 default: char_location
7212
7213 - `BetaCitationPageLocation object`
70237214
70247215 - `cited_text: string`
70257216
70267217 - `document_index: number`
70277218
7219 minimum: 0
7220
70287221 - `document_title: string or null`
70297222
70307223 - `end_page_number: number`
from line 7226
70337226
70347227 - `start_page_number: number`
70357228
7229 minimum: 1
7230
70367231 - `type: "page_location"`
70377232
7038 - `"page_location"`
7039
7040 - `BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }`
7233 default: page_location
7234
7235 - `BetaCitationContentBlockLocation object`
70417236
70427237 - `cited_text: string`
70437238
from line 7242
70477242
70487243 - `document_index: number`
70497244
7245 minimum: 0
7246
70507247 - `document_title: string or null`
70517248
70527249 - `end_block_index: number`
from line 7258
70617258
70627259 0-based index of the first cited block in the source's `content` array.
70637260
7261 minimum: 0
7262
70647263 - `type: "content_block_location"`
70657264
7066 - `"content_block_location"`
7067
7068 - `BetaCitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }`
7265 default: content_block_location
7266
7267 - `BetaCitationsWebSearchResultLocation object`
70697268
70707269 - `cited_text: string`
70717270
from line 7272
70737272
70747273 - `title: string or null`
70757274
7275 maxLength: 512
7276
70767277 - `type: "web_search_result_location"`
70777278
7078 - `"web_search_result_location"`
7279 default: web_search_result_location
70797280
70807281 - `url: string`
70817282
7082 - `BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }`
7283 - `BetaCitationSearchResultLocation object`
70837284
70847285 - `cited_text: string`
70857286
from line 7300
70997300
71007301 Counted separately from `document_index`; server-side web search results are not included in this count.
71017302
7303 minimum: 0
7304
71027305 - `source: string`
71037306
71047307 - `start_block_index: number`
71057308
71067309 0-based index of the first cited block in the source's `content` array.
71077310
7311 minimum: 0
7312
71087313 - `title: string or null`
71097314
71107315 - `type: "search_result_location"`
71117316
7112 - `"search_result_location"`
7317 default: search_result_location
71137318
71147319 - `text: string`
71157320
7321 maxLength: 5000000, minLength: 0
7322
71167323 - `type: "text"`
71177324
7118 - `"text"`
7119
7120 - `BetaThinkingBlock object { signature, thinking, type }`
7325 default: text
7326
7327 - `BetaThinkingBlock object`
71217328
71227329 - `signature: string`
71237330
from line 7340
71337340
71347341 - `type: "thinking"`
71357342
7136 - `"thinking"`
7137
7138 - `BetaRedactedThinkingBlock object { data, type }`
7343 default: thinking
7344
7345 - `BetaRedactedThinkingBlock object`
71397346
71407347 - `data: string`
71417348
from line 7354
71477354
71487355 - `type: "redacted_thinking"`
71497356
7150 - `"redacted_thinking"`
7151
7152 - `BetaToolUseBlock object { id, input, name, 3 more }`
7357 default: redacted_thinking
7358
7359 - `BetaToolUseBlock object`
71537360
71547361 - `id: string`
71557362
7363 pattern: ^[a-zA-Z0-9_-]+$
7364
71567365 - `input: map[unknown]`
71577366
71587367 - `name: string`
71597368
7369 minLength: 1
7370
71607371 - `type: "tool_use"`
71617372
7162 - `"tool_use"`
7373 default: tool_use
71637374
71647375 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
71657376
71667377 Tool invocation directly from the model.
71677378
7168 - `BetaDirectCaller object { type }`
7379 - `BetaDirectCaller object`
71697380
71707381 Tool invocation directly from the model.
71717382
71727383 - `type: "direct"`
71737384
7174 - `"direct"`
7175
7176 - `BetaServerToolCaller object { tool_id, type }`
7385 - `BetaServerToolCaller object`
71777386
71787387 Tool invocation generated by a server-side tool.
71797388
71807389 - `tool_id: string`
71817390
7391 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7392
71827393 - `type: "code_execution_20250825"`
71837394
7184 - `"code_execution_20250825"`
7185
7186 - `BetaServerToolCaller20260120 object { tool_id, type }`
7395 - `BetaServerToolCaller20260120 object`
71877396
71887397 - `tool_id: string`
71897398
7399 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7400
71907401 - `type: "code_execution_20260120"`
71917402
7192 - `"code_execution_20260120"`
7193
71947403 - `toolset_name: optional string or null`
71957404
71967405 For a toolset member tool_use, the toolset family.
71977406
7198 - `BetaServerToolUseBlock object { id, input, name, 2 more }`
7407 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
7408
7409 - `BetaServerToolUseBlock object`
71997410
72007411 - `id: string`
72017412
7413 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7414
72027415 - `input: map[unknown]`
72037416
72047417 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 7434
72217434
72227435 - `type: "server_tool_use"`
72237436
7224 - `"server_tool_use"`
7437 default: server_tool_use
72257438
72267439 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
72277440
72287441 Tool invocation directly from the model.
72297442
7230 - `BetaDirectCaller object { type }`
7443 - `BetaDirectCaller object`
72317444
72327445 Tool invocation directly from the model.
72337446
7234 - `BetaServerToolCaller object { tool_id, type }`
7447 - `BetaServerToolCaller object`
72357448
72367449 Tool invocation generated by a server-side tool.
72377450
7238 - `BetaServerToolCaller20260120 object { tool_id, type }`
7239
7240 - `BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }`
7451 - `BetaServerToolCaller20260120 object`
7452
7453 - `BetaWebSearchToolResultBlock object`
72417454
72427455 - `content: BetaWebSearchToolResultBlockContent`
72437456
7244 - `BetaWebSearchToolResultError object { error_code, type }`
7457 - `BetaWebSearchToolResultError object`
72457458
72467459 - `error_code: BetaWebSearchToolResultErrorCode`
72477460
from line 7472
72597472
72607473 - `type: "web_search_tool_result_error"`
72617474
7262 - `"web_search_tool_result_error"`
7475 default: web_search_tool_result_error
72637476
72647477 - `array of BetaWebSearchResultBlock`
72657478
from line 7484
72717484
72727485 - `type: "web_search_result"`
72737486
7274 - `"web_search_result"`
7487 default: web_search_result
72757488
72767489 - `url: string`
72777490
72787491 - `tool_use_id: string`
72797492
7493 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7494
72807495 - `type: "web_search_tool_result"`
72817496
7282 - `"web_search_tool_result"`
7497 default: web_search_tool_result
72837498
72847499 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
72857500
72867501 Tool invocation directly from the model.
72877502
7288 - `BetaDirectCaller object { type }`
7503 - `BetaDirectCaller object`
72897504
72907505 Tool invocation directly from the model.
72917506
7292 - `BetaServerToolCaller object { tool_id, type }`
7507 - `BetaServerToolCaller object`
72937508
72947509 Tool invocation generated by a server-side tool.
72957510
7296 - `BetaServerToolCaller20260120 object { tool_id, type }`
7297
7298 - `BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }`
7511 - `BetaServerToolCaller20260120 object`
7512
7513 - `BetaWebFetchToolResultBlock object`
72997514
73007515 - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock`
73017516
7302 - `BetaWebFetchToolResultErrorBlock object { error_code, type }`
7517 - `BetaWebFetchToolResultErrorBlock object`
73037518
73047519 - `error_code: BetaWebFetchToolResultErrorCode`
73057520
from line 7538
73237538
73247539 - `type: "web_fetch_tool_result_error"`
73257540
7326 - `"web_fetch_tool_result_error"`
7327
7328 - `BetaWebFetchBlock object { content, retrieved_at, type, url }`
7541 default: web_fetch_tool_result_error
7542
7543 - `BetaWebFetchBlock object`
73297544
73307545 - `content: BetaDocumentBlock`
73317546
from line 7550
73357550
73367551 - `enabled: boolean`
73377552
7553 default: false
7554
73387555 - `source: BetaBase64PDFSource or BetaPlainTextSource`
73397556
7340 - `BetaBase64PDFSource object { data, media_type, type }`
7557 - `BetaBase64PDFSource object`
73417558
73427559 - `data: string`
73437560
7561 format: byte
7562
73447563 - `media_type: "application/pdf"`
73457564
7346 - `"application/pdf"`
7347
73487565 - `type: "base64"`
73497566
7350 - `"base64"`
7351
7352 - `BetaPlainTextSource object { data, media_type, type }`
7567 - `BetaPlainTextSource object`
73537568
73547569 - `data: string`
73557570
73567571 - `media_type: "text/plain"`
73577572
7358 - `"text/plain"`
7359
73607573 - `type: "text"`
73617574
7362 - `"text"`
7363
73647575 - `title: string or null`
73657576
73667577 The title of the document
73677578
73687579 - `type: "document"`
73697580
7370 - `"document"`
7581 default: document
73717582
73727583 - `retrieved_at: string or null`
73737584
from line 7586
73757586
73767587 - `type: "web_fetch_result"`
73777588
7378 - `"web_fetch_result"`
7589 default: web_fetch_result
73797590
73807591 - `url: string`
73817592
from line 7594
73837594
73847595 - `tool_use_id: string`
73857596
7597 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7598
73867599 - `type: "web_fetch_tool_result"`
73877600
7388 - `"web_fetch_tool_result"`
7601 default: web_fetch_tool_result
73897602
73907603 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
73917604
73927605 Tool invocation directly from the model.
73937606
7394 - `BetaDirectCaller object { type }`
7607 - `BetaDirectCaller object`
73957608
73967609 Tool invocation directly from the model.
73977610
7398 - `BetaServerToolCaller object { tool_id, type }`
7611 - `BetaServerToolCaller object`
73997612
74007613 Tool invocation generated by a server-side tool.
74017614
7402 - `BetaServerToolCaller20260120 object { tool_id, type }`
7403
7404 - `BetaAdvisorToolResultBlock object { content, tool_use_id, type }`
7615 - `BetaServerToolCaller20260120 object`
7616
7617 - `BetaAdvisorToolResultBlock object`
74057618
74067619 - `content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock`
74077620
7408 - `BetaAdvisorToolResultError object { error_code, type }`
7621 - `BetaAdvisorToolResultError object`
74097622
74107623 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
74117624
from line 7638
74257638
74267639 - `type: "advisor_tool_result_error"`
74277640
7428 - `"advisor_tool_result_error"`
7429
7430 - `BetaAdvisorResultBlock object { stop_reason, text, type }`
7641 default: advisor_tool_result_error
7642
7643 - `BetaAdvisorResultBlock object`
74317644
74327645 - `stop_reason: string or null`
74337646
from line 7650
74377650
74387651 - `type: "advisor_result"`
74397652
7440 - `"advisor_result"`
7441
7442 - `BetaAdvisorRedactedResultBlock object { encrypted_content, stop_reason, type }`
7653 default: advisor_result
7654
7655 - `BetaAdvisorRedactedResultBlock object`
74437656
74447657 - `encrypted_content: string`
74457658
from line 7664
74517664
74527665 - `type: "advisor_redacted_result"`
74537666
7454 - `"advisor_redacted_result"`
7667 default: advisor_redacted_result
74557668
74567669 - `tool_use_id: string`
74577670
7671 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7672
74587673 - `type: "advisor_tool_result"`
74597674
7460 - `"advisor_tool_result"`
7461
7462 - `BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }`
7675 default: advisor_tool_result
7676
7677 - `BetaCodeExecutionToolResultBlock object`
74637678
74647679 - `content: BetaCodeExecutionToolResultBlockContent`
74657680
74667681 Code execution result with encrypted stdout for PFC + web_search results.
74677682
7468 - `BetaCodeExecutionToolResultError object { error_code, type }`
7683 - `BetaCodeExecutionToolResultError object`
74697684
74707685 - `error_code: BetaCodeExecutionToolResultErrorCode`
74717686
from line 7694
74797694
74807695 - `type: "code_execution_tool_result_error"`
74817696
7482 - `"code_execution_tool_result_error"`
7483
7484 - `BetaCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
7697 default: code_execution_tool_result_error
7698
7699 - `BetaCodeExecutionResultBlock object`
74857700
74867701 - `content: array of BetaCodeExecutionOutputBlock`
74877702
from line 7704
74897704
74907705 - `type: "code_execution_output"`
74917706
7492 - `"code_execution_output"`
7707 default: code_execution_output
74937708
74947709 - `return_code: number`
74957710
from line 7714
74997714
75007715 - `type: "code_execution_result"`
75017716
7502 - `"code_execution_result"`
7503
7504 - `BetaEncryptedCodeExecutionResultBlock object { content, encrypted_stdout, return_code, 2 more }`
7717 default: code_execution_result
7718
7719 - `BetaEncryptedCodeExecutionResultBlock object`
75057720
75067721 Code execution result with encrypted stdout for PFC + web_search results.
75077722
from line 7726
75117726
75127727 - `type: "code_execution_output"`
75137728
7729 default: code_execution_output
7730
75147731 - `encrypted_stdout: string`
75157732
75167733 - `return_code: number`
from line 7736
75197736
75207737 - `type: "encrypted_code_execution_result"`
75217738
7522 - `"encrypted_code_execution_result"`
7739 default: encrypted_code_execution_result
75237740
75247741 - `tool_use_id: string`
75257742
7743 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7744
75267745 - `type: "code_execution_tool_result"`
75277746
7528 - `"code_execution_tool_result"`
7529
7530 - `BetaBashCodeExecutionToolResultBlock object { content, tool_use_id, type }`
7747 default: code_execution_tool_result
7748
7749 - `BetaBashCodeExecutionToolResultBlock object`
75317750
75327751 - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock`
75337752
7534 - `BetaBashCodeExecutionToolResultError object { error_code, type }`
7753 - `BetaBashCodeExecutionToolResultError object`
75357754
75367755 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
75377756
from line 7766
75477766
75487767 - `type: "bash_code_execution_tool_result_error"`
75497768
7550 - `"bash_code_execution_tool_result_error"`
7551
7552 - `BetaBashCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
7769 default: bash_code_execution_tool_result_error
7770
7771 - `BetaBashCodeExecutionResultBlock object`
75537772
75547773 - `content: array of BetaBashCodeExecutionOutputBlock`
75557774
from line 7776
75577776
75587777 - `type: "bash_code_execution_output"`
75597778
7560 - `"bash_code_execution_output"`
7779 default: bash_code_execution_output
75617780
75627781 - `return_code: number`
75637782
from line 7786
75677786
75687787 - `type: "bash_code_execution_result"`
75697788
7570 - `"bash_code_execution_result"`
7789 default: bash_code_execution_result
75717790
75727791 - `tool_use_id: string`
75737792
7793 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7794
75747795 - `type: "bash_code_execution_tool_result"`
75757796
7576 - `"bash_code_execution_tool_result"`
7577
7578 - `BetaTextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }`
7797 default: bash_code_execution_tool_result
7798
7799 - `BetaTextEditorCodeExecutionToolResultBlock object`
75797800
75807801 - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock`
75817802
7582 - `BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }`
7803 - `BetaTextEditorCodeExecutionToolResultError object`
75837804
75847805 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
75857806
from line 7818
75977818
75987819 - `type: "text_editor_code_execution_tool_result_error"`
75997820
7600 - `"text_editor_code_execution_tool_result_error"`
7601
7602 - `BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }`
7821 default: text_editor_code_execution_tool_result_error
7822
7823 - `BetaTextEditorCodeExecutionViewResultBlock object`
76037824
76047825 - `content: string`
76057826
from line 7840
76197840
76207841 - `type: "text_editor_code_execution_view_result"`
76217842
7622 - `"text_editor_code_execution_view_result"`
7623
7624 - `BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }`
7843 default: text_editor_code_execution_view_result
7844
7845 - `BetaTextEditorCodeExecutionCreateResultBlock object`
76257846
76267847 - `is_file_update: boolean`
76277848
76287849 - `type: "text_editor_code_execution_create_result"`
76297850
7630 - `"text_editor_code_execution_create_result"`
7631
7632 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }`
7851 default: text_editor_code_execution_create_result
7852
7853 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object`
76337854
76347855 - `lines: array of string or null`
76357856
from line 7864
76437864
76447865 - `type: "text_editor_code_execution_str_replace_result"`
76457866
7646 - `"text_editor_code_execution_str_replace_result"`
7867 default: text_editor_code_execution_str_replace_result
76477868
76487869 - `tool_use_id: string`
76497870
7871 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7872
76507873 - `type: "text_editor_code_execution_tool_result"`
76517874
7652 - `"text_editor_code_execution_tool_result"`
7653
7654 - `BetaToolSearchToolResultBlock object { content, tool_use_id, type }`
7875 default: text_editor_code_execution_tool_result
7876
7877 - `BetaToolSearchToolResultBlock object`
76557878
76567879 - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock`
76577880
7658 - `BetaToolSearchToolResultError object { error_code, error_message, type }`
7881 - `BetaToolSearchToolResultError object`
76597882
76607883 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
76617884
from line 7894
76717894
76727895 - `type: "tool_search_tool_result_error"`
76737896
7674 - `"tool_search_tool_result_error"`
7675
7676 - `BetaToolSearchToolSearchResultBlock object { tool_references, type }`
7897 default: tool_search_tool_result_error
7898
7899 - `BetaToolSearchToolSearchResultBlock object`
76777900
76787901 - `tool_references: array of BetaToolReferenceBlock`
76797902
76807903 - `tool_name: string`
76817904
7905 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
7906
76827907 - `type: "tool_reference"`
76837908
7684 - `"tool_reference"`
7909 default: tool_reference
76857910
76867911 - `type: "tool_search_tool_search_result"`
76877912
7688 - `"tool_search_tool_search_result"`
7913 default: tool_search_tool_search_result
76897914
76907915 - `tool_use_id: string`
76917916
7917 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
7918
76927919 - `type: "tool_search_tool_result"`
76937920
7694 - `"tool_search_tool_result"`
7695
7696 - `BetaMCPToolUseBlock object { id, input, name, 2 more }`
7921 default: tool_search_tool_result
7922
7923 - `BetaMCPToolUseBlock object`
76977924
76987925 - `id: string`
76997926
7927 pattern: ^[a-zA-Z0-9_-]+$
7928
77007929 - `input: map[unknown]`
77017930
77027931 - `name: string`
from line 7938
77097938
77107939 - `type: "mcp_tool_use"`
77117940
7712 - `"mcp_tool_use"`
7713
7714 - `BetaMCPToolResultBlock object { content, is_error, tool_use_id, type }`
7941 default: mcp_tool_use
7942
7943 - `BetaMCPToolResultBlock object`
77157944
77167945 - `content: string or array of BetaTextBlock`
77177946
from line 7956
77277956
77287957 - `text: string`
77297958
7959 maxLength: 5000000, minLength: 0
7960
77307961 - `type: "text"`
77317962
7963 default: text
7964
77327965 - `is_error: boolean`
77337966
7967 default: false
7968
77347969 - `tool_use_id: string`
77357970
7971 pattern: ^[a-zA-Z0-9_-]+$
7972
77367973 - `type: "mcp_tool_result"`
77377974
7738 - `"mcp_tool_result"`
7739
7740 - `BetaContainerUploadBlock object { file_id, type }`
7975 default: mcp_tool_result
7976
7977 - `BetaContainerUploadBlock object`
77417978
77427979 Response model for a file uploaded to the container.
77437980
from line 7982
77457982
77467983 - `type: "container_upload"`
77477984
7748 - `"container_upload"`
7749
7750 - `BetaCompactionBlock object { content, encrypted_content, type }`
7985 default: container_upload
7986
7987 - `BetaCompactionBlock object`
77517988
77527989 A compaction block returned when autocompact is triggered.
77537990
from line 8002
77658002
77668003 - `type: "compaction"`
77678004
7768 - `"compaction"`
7769
7770 - `BetaFallbackBlock object { from, to, trigger, type }`
8005 default: compaction
8006
8007 - `BetaFallbackBlock object`
77718008
77728009 Marks the point in `content` where one model's output gives way to the next.
77738010
from line 8130
78938130
78948131 - `type: "refusal"`
78958132
7896 - `"refusal"`
8133 default: refusal
78978134
78988135 - `type: "fallback"`
78998136
7900 - `"fallback"`
8137 default: fallback
79018138
79028139 - `context_management: BetaContextManagementResponse or null`
79038140
from line 8146
79098146
79108147 List of context management edits that were applied.
79118148
7912 - `BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }`
8149 - `BetaClearToolUses20250919EditResponse object`
79138150
79148151 - `cleared_input_tokens: number`
79158152
79168153 Number of input tokens cleared by this edit.
79178154
8155 minimum: 0
8156
79188157 - `cleared_tool_uses: number`
79198158
79208159 Number of tool uses that were cleared.
79218160
8161 minimum: 0
8162
79228163 - `type: "clear_tool_uses_20250919"`
79238164
79248165 The type of context management edit applied.
79258166
7926 - `"clear_tool_uses_20250919"`
7927
7928 - `BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }`
8167 default: clear_tool_uses_20250919
8168
8169 - `BetaClearThinking20251015EditResponse object`
79298170
79308171 - `cleared_input_tokens: number`
79318172
79328173 Number of input tokens cleared by this edit.
79338174
8175 minimum: 0
8176
79348177 - `cleared_thinking_turns: number`
79358178
79368179 Number of thinking turns that were cleared.
79378180
8181 minimum: 0
8182
79388183 - `type: "clear_thinking_20251015"`
79398184
79408185 The type of context management edit applied.
79418186
7942 - `"clear_thinking_20251015"`
8187 default: clear_thinking_20251015
79438188
79448189 - `diagnostics: BetaDiagnostics or null`
79458190
from line 8195
79508195
79518196 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.
79528197
7953 - `BetaCacheMissModelChanged object { cache_missed_input_tokens, type }`
8198 - `BetaCacheMissModelChanged object`
79548199
79558200 - `cache_missed_input_tokens: number`
79568201
from line 8203
79588203
79598204 - `type: "model_changed"`
79608205
7961 - `"model_changed"`
7962
7963 - `BetaCacheMissSystemChanged object { cache_missed_input_tokens, type }`
8206 default: model_changed
8207
8208 - `BetaCacheMissSystemChanged object`
79648209
79658210 - `cache_missed_input_tokens: number`
79668211
from line 8213
79688213
79698214 - `type: "system_changed"`
79708215
7971 - `"system_changed"`
7972
7973 - `BetaCacheMissToolsChanged object { cache_missed_input_tokens, type }`
8216 default: system_changed
8217
8218 - `BetaCacheMissToolsChanged object`
79748219
79758220 - `cache_missed_input_tokens: number`
79768221
from line 8223
79788223
79798224 - `type: "tools_changed"`
79808225
7981 - `"tools_changed"`
7982
7983 - `BetaCacheMissMessagesChanged object { cache_missed_input_tokens, type }`
8226 default: tools_changed
8227
8228 - `BetaCacheMissMessagesChanged object`
79848229
79858230 - `cache_missed_input_tokens: number`
79868231
from line 8233
79888233
79898234 - `type: "messages_changed"`
79908235
7991 - `"messages_changed"`
7992
7993 - `BetaCacheMissPreviousMessageNotFound object { type }`
8236 default: messages_changed
8237
8238 - `BetaCacheMissPreviousMessageNotFound object`
79948239
79958240 - `type: "previous_message_not_found"`
79968241
7997 - `"previous_message_not_found"`
7998
7999 - `BetaCacheMissUnavailable object { type }`
8242 default: previous_message_not_found
8243
8244 - `BetaCacheMissUnavailable object`
80008245
80018246 - `type: "unavailable"`
80028247
8003 - `"unavailable"`
8248 default: unavailable
80048249
80058250 - `model: Model`
80068251
from line 8259
80148259
80158260 This will always be `"assistant"`.
80168261
8017 - `"assistant"`
8262 default: assistant
80188263
80198264 - `stop_details: BetaRefusalStopDetails or null`
80208265
from line 8346
81018346
81028347 - `type: "refusal"`
81038348
8104 - `"refusal"`
8349 default: refusal
81058350
81068351 - `stop_reason: BetaStopReason or null`
81078352
from line 8392
81478392
81488393 For Messages, this is always `"message"`.
81498394
8150 - `"message"`
8395 default: message
81518396
81528397 - `usage: BetaUsage`
81538398
from line 8414
81698414
81708415 The number of input tokens used to create the 1 hour cache entry.
81718416
8417 default: 0, minimum: 0
8418
81728419 - `ephemeral_5m_input_tokens: number`
81738420
81748421 The number of input tokens used to create the 5 minute cache entry.
81758422
8423 default: 0, minimum: 0
8424
81768425 - `cache_creation_input_tokens: number or null`
81778426
81788427 The number of input tokens used to create the cache entry.
81798428
8429 minimum: 0
8430
81808431 - `cache_read_input_tokens: number or null`
81818432
81828433 The number of input tokens read from the cache.
8434
8435 minimum: 0
81838436
81848437 - `fallback_credit: BetaFallbackCreditUsage or null`
81858438
from line 8447
81948447 resulting shift is zero because there was nothing to move. `not_applied`:
81958448 no reprice was applied; the arm's `reason` says why.
81968449
8197 - `BetaFallbackCreditRedeemed object { type }`
8450 - `BetaFallbackCreditRedeemed object`
81988451
81998452 The reprice was applied: the retry is billed as if the conversation
82008453 had been on the retry model all along.
82018454
82028455 - `type: "redeemed"`
82038456
8204 - `"redeemed"`
8205
8206 - `BetaFallbackCreditNotApplied object { reason, type, remove_to_redeem }`
8457 default: redeemed
8458
8459 - `BetaFallbackCreditNotApplied object`
82078460
82088461 No reprice was applied; `reason` says why.
82098462
from line 8493
82408493
82418494 - `type: "not_applied"`
82428495
8243 - `"not_applied"`
8496 default: not_applied
82448497
82458498 - `remove_to_redeem: optional array of string or null`
82468499
from line 8514
82618514
82628515 The number of input tokens which were used.
82638516
8517 minimum: 0
8518
82648519 - `iterations: BetaIterationsUsage or null`
82658520
82668521 Per-iteration token usage breakdown.
from line 8526
82718526 - Calculate the true context window size from the last iteration
82728527 - Understand token accumulation across server-side tool use loops
82738528
8274 - `BetaMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
8529 - `BetaMessageIterationUsage object`
82758530
82768531 Token usage for a sampling iteration.
82778532
from line 8538
82838538
82848539 The number of input tokens used to create the cache entry.
82858540
8541 default: 0, minimum: 0
8542
82868543 - `cache_read_input_tokens: number`
82878544
82888545 The number of input tokens read from the cache.
82898546
8547 default: 0, minimum: 0
8548
82908549 - `input_tokens: number`
82918550
82928551 The number of input tokens which were used.
82938552
8553 minimum: 0
8554
82948555 - `model: Model`
82958556
82968557 The model that will complete your prompt.
from line 8562
83018562
83028563 The number of output tokens which were used.
83038564
8565 minimum: 0
8566
83048567 - `type: "message"`
83058568
83068569 Usage for a sampling iteration
83078570
8308 - `"message"`
8309
8310 - `BetaCompactionIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }`
8571 default: message
8572
8573 - `BetaCompactionIterationUsage object`
83118574
83128575 Token usage for a compaction iteration.
83138576
from line 8582
83198582
83208583 The number of input tokens used to create the cache entry.
83218584
8585 default: 0, minimum: 0
8586
83228587 - `cache_read_input_tokens: number`
83238588
83248589 The number of input tokens read from the cache.
83258590
8591 default: 0, minimum: 0
8592
83268593 - `input_tokens: number`
83278594
83288595 The number of input tokens which were used.
83298596
8597 minimum: 0
8598
83308599 - `output_tokens: number`
83318600
83328601 The number of output tokens which were used.
83338602
8603 minimum: 0
8604
83348605 - `type: "compaction"`
83358606
83368607 Usage for a compaction iteration
83378608
8338 - `"compaction"`
8339
8340 - `BetaAdvisorMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
8609 default: compaction
8610
8611 - `BetaAdvisorMessageIterationUsage object`
83418612
83428613 Token usage for an advisor sub-inference iteration.
83438614
from line 8620
83498620
83508621 The number of input tokens used to create the cache entry.
83518622
8623 default: 0, minimum: 0
8624
83528625 - `cache_read_input_tokens: number`
83538626
83548627 The number of input tokens read from the cache.
83558628
8629 default: 0, minimum: 0
8630
83568631 - `input_tokens: number`
83578632
83588633 The number of input tokens which were used.
83598634
8635 minimum: 0
8636
83608637 - `model: Model`
83618638
83628639 The model that will complete your prompt.
from line 8644
83678644
83688645 The number of output tokens which were used.
83698646
8647 minimum: 0
8648
83708649 - `type: "advisor_message"`
83718650
83728651 Usage for an advisor sub-inference iteration
83738652
8374 - `"advisor_message"`
8375
8376 - `BetaFallbackMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
8653 default: advisor_message
8654
8655 - `BetaFallbackMessageIterationUsage object`
83778656
83788657 Token usage for the fallback-model attempt of a server-side fallback request.
83798658
from line 8669
83908669
83918670 The number of input tokens used to create the cache entry.
83928671
8672 default: 0, minimum: 0
8673
83938674 - `cache_read_input_tokens: number`
83948675
83958676 The number of input tokens read from the cache.
83968677
8678 default: 0, minimum: 0
8679
83978680 - `input_tokens: number`
83988681
83998682 The number of input tokens which were used.
84008683
8684 minimum: 0
8685
84018686 - `model: Model`
84028687
84038688 The model that will complete your prompt.
from line 8693
84088693
84098694 The number of output tokens which were used.
84108695
8696 minimum: 0
8697
84118698 - `type: "fallback_message"`
84128699
84138700 Usage for the fallback-model attempt that served the response
84148701
8415 - `"fallback_message"`
8702 default: fallback_message
84168703
84178704 - `output_tokens: number`
84188705
84198706 The number of output tokens which were used.
8707
8708 minimum: 0
84208709
84218710 - `output_tokens_details: BetaOutputTokensDetails or null`
84228711
from line 8727
84388727 generation count by a small number of tokens. Always ≤ `output_tokens`;
84398728 `output_tokens - thinking_tokens` approximates the non-reasoning output.
84408729
8730 default: 0, minimum: 0
8731
84418732 - `server_tool_use: BetaServerToolUsage or null`
84428733
84438734 The number of server tool requests.
from line 8737
84468737
84478738 The number of web fetch tool requests.
84488739
8740 default: 0, minimum: 0
8741
84498742 - `web_search_requests: number`
84508743
84518744 The number of web search tool requests.
84528745
8746 default: 0, minimum: 0
8747
84538748 - `service_tier: "standard" or "priority" or "batch" or null`
84548749
84558750 If the request used the priority, standard, or batch tier.
from line 8765
84708765
84718766 - `type: "succeeded"`
84728767
8473 - `"succeeded"`
8474
8475 - `BetaMessageBatchErroredResult object { error, type }`
8768 default: succeeded
8769
8770 - `BetaMessageBatchErroredResult object`
84768771
84778772 - `error: BetaErrorResponse`
84788773
84798774 - `error: BetaError`
84808775
8481 - `BetaInvalidRequestError object { message, type }`
8776 - `BetaInvalidRequestError object`
84828777
84838778 - `message: string`
84848779
8780 default: Invalid request
8781
84858782 - `type: "invalid_request_error"`
84868783
8487 - `"invalid_request_error"`
8488
8489 - `BetaAuthenticationError object { message, type }`
8784 default: invalid_request_error
8785
8786 - `BetaAuthenticationError object`
84908787
84918788 - `message: string`
84928789
8790 default: Authentication error
8791
84938792 - `type: "authentication_error"`
84948793
8495 - `"authentication_error"`
8496
8497 - `BetaBillingError object { message, type }`
8794 default: authentication_error
8795
8796 - `BetaBillingError object`
84988797
84998798 - `message: string`
85008799
8800 default: Billing error
8801
85018802 - `type: "billing_error"`
85028803
8503 - `"billing_error"`
8504
8505 - `BetaPermissionError object { message, type }`
8804 default: billing_error
8805
8806 - `BetaPermissionError object`
85068807
85078808 - `message: string`
85088809
8810 default: Permission denied
8811
85098812 - `type: "permission_error"`
85108813
8511 - `"permission_error"`
8512
8513 - `BetaNotFoundError object { message, type }`
8814 default: permission_error
8815
8816 - `BetaNotFoundError object`
85148817
85158818 - `message: string`
85168819
8820 default: Not found
8821
85178822 - `type: "not_found_error"`
85188823
8519 - `"not_found_error"`
8520
8521 - `BetaRateLimitError object { message, type }`
8824 default: not_found_error
8825
8826 - `BetaRateLimitError object`
85228827
85238828 - `message: string`
85248829
8830 default: Rate limited
8831
85258832 - `type: "rate_limit_error"`
85268833
8527 - `"rate_limit_error"`
8528
8529 - `BetaGatewayTimeoutError object { message, type }`
8834 default: rate_limit_error
8835
8836 - `BetaGatewayTimeoutError object`
85308837
85318838 - `message: string`
85328839
8840 default: Request timeout
8841
85338842 - `type: "timeout_error"`
85348843
8535 - `"timeout_error"`
8536
8537 - `BetaAPIError object { message, type }`
8844 default: timeout_error
8845
8846 - `BetaAPIError object`
85388847
85398848 - `message: string`
85408849
8850 default: Internal server error
8851
85418852 - `type: "api_error"`
85428853
8543 - `"api_error"`
8544
8545 - `BetaOverloadedError object { message, type }`
8854 default: api_error
8855
8856 - `BetaOverloadedError object`
85468857
85478858 - `message: string`
85488859
8860 default: Overloaded
8861
85498862 - `type: "overloaded_error"`
85508863
8551 - `"overloaded_error"`
8864 default: overloaded_error
85528865
85538866 - `request_id: string or null`
85548867
85558868 - `type: "error"`
85568869
8557 - `"error"`
8870 default: error
85588871
85598872 - `type: "errored"`
85608873
8561 - `"errored"`
8562
8563 - `BetaMessageBatchCanceledResult object { type }`
8874 default: errored
8875
8876 - `BetaMessageBatchCanceledResult object`
85648877
85658878 - `type: "canceled"`
85668879
8567 - `"canceled"`
8568
8569 - `BetaMessageBatchExpiredResult object { type }`
8880 default: canceled
8881
8882 - `BetaMessageBatchExpiredResult object`
85708883
85718884 - `type: "expired"`
85728885
8573 - `"expired"`
8886 default: expired
85748887
85758888### Beta Message Batch Request Counts
85768889
8577- `BetaMessageBatchRequestCounts object { canceled, errored, expired, 2 more }`
8890- `BetaMessageBatchRequestCounts object`
85788891
85798892 - `canceled: number`
85808893
from line 8895
85828895
85838896 This is zero until processing of the entire Message Batch has ended.
85848897
8898 default: 0
8899
85858900 - `errored: number`
85868901
85878902 Number of requests in the Message Batch that encountered an error.
85888903
85898904 This is zero until processing of the entire Message Batch has ended.
85908905
8906 default: 0
8907
85918908 - `expired: number`
85928909
85938910 Number of requests in the Message Batch that have expired.
85948911
85958912 This is zero until processing of the entire Message Batch has ended.
85968913
8914 default: 0
8915
85978916 - `processing: number`
85988917
85998918 Number of requests in the Message Batch that are processing.
86008919
8920 default: 0
8921
86018922 - `succeeded: number`
86028923
86038924 Number of requests in the Message Batch that have completed successfully.
86048925
86058926 This is zero until processing of the entire Message Batch has ended.
86068927
8928 default: 0
8929
86078930### Beta Message Batch Result
86088931
86098932- `BetaMessageBatchResult = BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult`
from line 8935
86128935
86138936 Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.
86148937
8615 - `BetaMessageBatchSucceededResult object { message, type }`
8938 - `BetaMessageBatchSucceededResult object`
86168939
86178940 - `message: BetaMessage`
86188941
from line 8957
86348957
86358958 The time at which the container will expire.
86368959
8960 format: date-time
8961
86378962 - `skills: array of BetaSkill or null`
86388963
86398964 Skills loaded in the container
from line 8967
86428967
86438968 Skill ID
86448969
8970 maxLength: 64, minLength: 1
8971
86458972 - `type: "anthropic" or "custom"`
86468973
86478974 Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
from line 8980
86538980 - `version: string`
86548981
86558982 The resolved version: a skill version ID for custom skills.
8983
8984 maxLength: 64, minLength: 1
86568985
86578986 - `content: array of BetaContentBlock`
86588987
from line 9012
86839012 [{"type": "text", "text": "B)"}]
86849013 ```
86859014
8686 - `BetaTextBlock object { citations, text, type }`
9015 - `BetaTextBlock object`
86879016
86889017 - `citations: array of BetaTextCitation or null`
86899018
from line 9020
86919020
86929021 The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`.
86939022
8694 - `BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }`
9023 - `BetaCitationCharLocation object`
86959024
86969025 - `cited_text: string`
86979026
86989027 - `document_index: number`
86999028
9029 minimum: 0
9030
87009031 - `document_title: string or null`
87019032
87029033 - `end_char_index: number`
from line 9036
87059036
87069037 - `start_char_index: number`
87079038
9039 minimum: 0
9040
87089041 - `type: "char_location"`
87099042
8710 - `"char_location"`
8711
8712 - `BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }`
9043 default: char_location
9044
9045 - `BetaCitationPageLocation object`
87139046
87149047 - `cited_text: string`
87159048
87169049 - `document_index: number`
87179050
9051 minimum: 0
9052
87189053 - `document_title: string or null`
87199054
87209055 - `end_page_number: number`
from line 9058
87239058
87249059 - `start_page_number: number`
87259060
9061 minimum: 1
9062
87269063 - `type: "page_location"`
87279064
8728 - `"page_location"`
8729
8730 - `BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }`
9065 default: page_location
9066
9067 - `BetaCitationContentBlockLocation object`
87319068
87329069 - `cited_text: string`
87339070
from line 9074
87379074
87389075 - `document_index: number`
87399076
9077 minimum: 0
9078
87409079 - `document_title: string or null`
87419080
87429081 - `end_block_index: number`
from line 9090
87519090
87529091 0-based index of the first cited block in the source's `content` array.
87539092
9093 minimum: 0
9094
87549095 - `type: "content_block_location"`
87559096
8756 - `"content_block_location"`
8757
8758 - `BetaCitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }`
9097 default: content_block_location
9098
9099 - `BetaCitationsWebSearchResultLocation object`
87599100
87609101 - `cited_text: string`
87619102
from line 9104
87639104
87649105 - `title: string or null`
87659106
9107 maxLength: 512
9108
87669109 - `type: "web_search_result_location"`
87679110
8768 - `"web_search_result_location"`
9111 default: web_search_result_location
87699112
87709113 - `url: string`
87719114
8772 - `BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }`
9115 - `BetaCitationSearchResultLocation object`
87739116
87749117 - `cited_text: string`
87759118
from line 9132
87899132
87909133 Counted separately from `document_index`; server-side web search results are not included in this count.
87919134
9135 minimum: 0
9136
87929137 - `source: string`
87939138
87949139 - `start_block_index: number`
87959140
87969141 0-based index of the first cited block in the source's `content` array.
87979142
9143 minimum: 0
9144
87989145 - `title: string or null`
87999146
88009147 - `type: "search_result_location"`
88019148
8802 - `"search_result_location"`
9149 default: search_result_location
88039150
88049151 - `text: string`
88059152
9153 maxLength: 5000000, minLength: 0
9154
88069155 - `type: "text"`
88079156
8808 - `"text"`
8809
8810 - `BetaThinkingBlock object { signature, thinking, type }`
9157 default: text
9158
9159 - `BetaThinkingBlock object`
88119160
88129161 - `signature: string`
88139162
from line 9172
88239172
88249173 - `type: "thinking"`
88259174
8826 - `"thinking"`
8827
8828 - `BetaRedactedThinkingBlock object { data, type }`
9175 default: thinking
9176
9177 - `BetaRedactedThinkingBlock object`
88299178
88309179 - `data: string`
88319180
from line 9186
88379186
88389187 - `type: "redacted_thinking"`
88399188
8840 - `"redacted_thinking"`
8841
8842 - `BetaToolUseBlock object { id, input, name, 3 more }`
9189 default: redacted_thinking
9190
9191 - `BetaToolUseBlock object`
88439192
88449193 - `id: string`
88459194
9195 pattern: ^[a-zA-Z0-9_-]+$
9196
88469197 - `input: map[unknown]`
88479198
88489199 - `name: string`
88499200
9201 minLength: 1
9202
88509203 - `type: "tool_use"`
88519204
8852 - `"tool_use"`
9205 default: tool_use
88539206
88549207 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
88559208
88569209 Tool invocation directly from the model.
88579210
8858 - `BetaDirectCaller object { type }`
9211 - `BetaDirectCaller object`
88599212
88609213 Tool invocation directly from the model.
88619214
88629215 - `type: "direct"`
88639216
8864 - `"direct"`
8865
8866 - `BetaServerToolCaller object { tool_id, type }`
9217 - `BetaServerToolCaller object`
88679218
88689219 Tool invocation generated by a server-side tool.
88699220
88709221 - `tool_id: string`
88719222
9223 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9224
88729225 - `type: "code_execution_20250825"`
88739226
8874 - `"code_execution_20250825"`
8875
8876 - `BetaServerToolCaller20260120 object { tool_id, type }`
9227 - `BetaServerToolCaller20260120 object`
88779228
88789229 - `tool_id: string`
88799230
9231 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9232
88809233 - `type: "code_execution_20260120"`
88819234
8882 - `"code_execution_20260120"`
8883
88849235 - `toolset_name: optional string or null`
88859236
88869237 For a toolset member tool_use, the toolset family.
88879238
8888 - `BetaServerToolUseBlock object { id, input, name, 2 more }`
9239 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
9240
9241 - `BetaServerToolUseBlock object`
88899242
88909243 - `id: string`
88919244
9245 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9246
88929247 - `input: map[unknown]`
88939248
88949249 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 9266
89119266
89129267 - `type: "server_tool_use"`
89139268
8914 - `"server_tool_use"`
9269 default: server_tool_use
89159270
89169271 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
89179272
89189273 Tool invocation directly from the model.
89199274
8920 - `BetaDirectCaller object { type }`
9275 - `BetaDirectCaller object`
89219276
89229277 Tool invocation directly from the model.
89239278
8924 - `BetaServerToolCaller object { tool_id, type }`
9279 - `BetaServerToolCaller object`
89259280
89269281 Tool invocation generated by a server-side tool.
89279282
8928 - `BetaServerToolCaller20260120 object { tool_id, type }`
8929
8930 - `BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }`
9283 - `BetaServerToolCaller20260120 object`
9284
9285 - `BetaWebSearchToolResultBlock object`
89319286
89329287 - `content: BetaWebSearchToolResultBlockContent`
89339288
8934 - `BetaWebSearchToolResultError object { error_code, type }`
9289 - `BetaWebSearchToolResultError object`
89359290
89369291 - `error_code: BetaWebSearchToolResultErrorCode`
89379292
from line 9304
89499304
89509305 - `type: "web_search_tool_result_error"`
89519306
8952 - `"web_search_tool_result_error"`
9307 default: web_search_tool_result_error
89539308
89549309 - `array of BetaWebSearchResultBlock`
89559310
from line 9316
89619316
89629317 - `type: "web_search_result"`
89639318
8964 - `"web_search_result"`
9319 default: web_search_result
89659320
89669321 - `url: string`
89679322
89689323 - `tool_use_id: string`
89699324
9325 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9326
89709327 - `type: "web_search_tool_result"`
89719328
8972 - `"web_search_tool_result"`
9329 default: web_search_tool_result
89739330
89749331 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
89759332
89769333 Tool invocation directly from the model.
89779334
8978 - `BetaDirectCaller object { type }`
9335 - `BetaDirectCaller object`
89799336
89809337 Tool invocation directly from the model.
89819338
8982 - `BetaServerToolCaller object { tool_id, type }`
9339 - `BetaServerToolCaller object`
89839340
89849341 Tool invocation generated by a server-side tool.
89859342
8986 - `BetaServerToolCaller20260120 object { tool_id, type }`
8987
8988 - `BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }`
9343 - `BetaServerToolCaller20260120 object`
9344
9345 - `BetaWebFetchToolResultBlock object`
89899346
89909347 - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock`
89919348
8992 - `BetaWebFetchToolResultErrorBlock object { error_code, type }`
9349 - `BetaWebFetchToolResultErrorBlock object`
89939350
89949351 - `error_code: BetaWebFetchToolResultErrorCode`
89959352
from line 9370
90139370
90149371 - `type: "web_fetch_tool_result_error"`
90159372
9016 - `"web_fetch_tool_result_error"`
9017
9018 - `BetaWebFetchBlock object { content, retrieved_at, type, url }`
9373 default: web_fetch_tool_result_error
9374
9375 - `BetaWebFetchBlock object`
90199376
90209377 - `content: BetaDocumentBlock`
90219378
from line 9382
90259382
90269383 - `enabled: boolean`
90279384
9385 default: false
9386
90289387 - `source: BetaBase64PDFSource or BetaPlainTextSource`
90299388
9030 - `BetaBase64PDFSource object { data, media_type, type }`
9389 - `BetaBase64PDFSource object`
90319390
90329391 - `data: string`
90339392
9393 format: byte
9394
90349395 - `media_type: "application/pdf"`
90359396
9036 - `"application/pdf"`
9037
90389397 - `type: "base64"`
90399398
9040 - `"base64"`
9041
9042 - `BetaPlainTextSource object { data, media_type, type }`
9399 - `BetaPlainTextSource object`
90439400
90449401 - `data: string`
90459402
90469403 - `media_type: "text/plain"`
90479404
9048 - `"text/plain"`
9049
90509405 - `type: "text"`
90519406
9052 - `"text"`
9053
90549407 - `title: string or null`
90559408
90569409 The title of the document
90579410
90589411 - `type: "document"`
90599412
9060 - `"document"`
9413 default: document
90619414
90629415 - `retrieved_at: string or null`
90639416
from line 9418
90659418
90669419 - `type: "web_fetch_result"`
90679420
9068 - `"web_fetch_result"`
9421 default: web_fetch_result
90699422
90709423 - `url: string`
90719424
from line 9426
90739426
90749427 - `tool_use_id: string`
90759428
9429 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9430
90769431 - `type: "web_fetch_tool_result"`
90779432
9078 - `"web_fetch_tool_result"`
9433 default: web_fetch_tool_result
90799434
90809435 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
90819436
90829437 Tool invocation directly from the model.
90839438
9084 - `BetaDirectCaller object { type }`
9439 - `BetaDirectCaller object`
90859440
90869441 Tool invocation directly from the model.
90879442
9088 - `BetaServerToolCaller object { tool_id, type }`
9443 - `BetaServerToolCaller object`
90899444
90909445 Tool invocation generated by a server-side tool.
90919446
9092 - `BetaServerToolCaller20260120 object { tool_id, type }`
9093
9094 - `BetaAdvisorToolResultBlock object { content, tool_use_id, type }`
9447 - `BetaServerToolCaller20260120 object`
9448
9449 - `BetaAdvisorToolResultBlock object`
90959450
90969451 - `content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock`
90979452
9098 - `BetaAdvisorToolResultError object { error_code, type }`
9453 - `BetaAdvisorToolResultError object`
90999454
91009455 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
91019456
from line 9470
91159470
91169471 - `type: "advisor_tool_result_error"`
91179472
9118 - `"advisor_tool_result_error"`
9119
9120 - `BetaAdvisorResultBlock object { stop_reason, text, type }`
9473 default: advisor_tool_result_error
9474
9475 - `BetaAdvisorResultBlock object`
91219476
91229477 - `stop_reason: string or null`
91239478
from line 9482
91279482
91289483 - `type: "advisor_result"`
91299484
9130 - `"advisor_result"`
9131
9132 - `BetaAdvisorRedactedResultBlock object { encrypted_content, stop_reason, type }`
9485 default: advisor_result
9486
9487 - `BetaAdvisorRedactedResultBlock object`
91339488
91349489 - `encrypted_content: string`
91359490
from line 9496
91419496
91429497 - `type: "advisor_redacted_result"`
91439498
9144 - `"advisor_redacted_result"`
9499 default: advisor_redacted_result
91459500
91469501 - `tool_use_id: string`
91479502
9503 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9504
91489505 - `type: "advisor_tool_result"`
91499506
9150 - `"advisor_tool_result"`
9151
9152 - `BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }`
9507 default: advisor_tool_result
9508
9509 - `BetaCodeExecutionToolResultBlock object`
91539510
91549511 - `content: BetaCodeExecutionToolResultBlockContent`
91559512
91569513 Code execution result with encrypted stdout for PFC + web_search results.
91579514
9158 - `BetaCodeExecutionToolResultError object { error_code, type }`
9515 - `BetaCodeExecutionToolResultError object`
91599516
91609517 - `error_code: BetaCodeExecutionToolResultErrorCode`
91619518
from line 9526
91699526
91709527 - `type: "code_execution_tool_result_error"`
91719528
9172 - `"code_execution_tool_result_error"`
9173
9174 - `BetaCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
9529 default: code_execution_tool_result_error
9530
9531 - `BetaCodeExecutionResultBlock object`
91759532
91769533 - `content: array of BetaCodeExecutionOutputBlock`
91779534
from line 9536
91799536
91809537 - `type: "code_execution_output"`
91819538
9182 - `"code_execution_output"`
9539 default: code_execution_output
91839540
91849541 - `return_code: number`
91859542
from line 9546
91899546
91909547 - `type: "code_execution_result"`
91919548
9192 - `"code_execution_result"`
9193
9194 - `BetaEncryptedCodeExecutionResultBlock object { content, encrypted_stdout, return_code, 2 more }`
9549 default: code_execution_result
9550
9551 - `BetaEncryptedCodeExecutionResultBlock object`
91959552
91969553 Code execution result with encrypted stdout for PFC + web_search results.
91979554
from line 9558
92019558
92029559 - `type: "code_execution_output"`
92039560
9561 default: code_execution_output
9562
92049563 - `encrypted_stdout: string`
92059564
92069565 - `return_code: number`
from line 9568
92099568
92109569 - `type: "encrypted_code_execution_result"`
92119570
9212 - `"encrypted_code_execution_result"`
9571 default: encrypted_code_execution_result
92139572
92149573 - `tool_use_id: string`
92159574
9575 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9576
92169577 - `type: "code_execution_tool_result"`
92179578
9218 - `"code_execution_tool_result"`
9219
9220 - `BetaBashCodeExecutionToolResultBlock object { content, tool_use_id, type }`
9579 default: code_execution_tool_result
9580
9581 - `BetaBashCodeExecutionToolResultBlock object`
92219582
92229583 - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock`
92239584
9224 - `BetaBashCodeExecutionToolResultError object { error_code, type }`
9585 - `BetaBashCodeExecutionToolResultError object`
92259586
92269587 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
92279588
from line 9598
92379598
92389599 - `type: "bash_code_execution_tool_result_error"`
92399600
9240 - `"bash_code_execution_tool_result_error"`
9241
9242 - `BetaBashCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
9601 default: bash_code_execution_tool_result_error
9602
9603 - `BetaBashCodeExecutionResultBlock object`
92439604
92449605 - `content: array of BetaBashCodeExecutionOutputBlock`
92459606
from line 9608
92479608
92489609 - `type: "bash_code_execution_output"`
92499610
9250 - `"bash_code_execution_output"`
9611 default: bash_code_execution_output
92519612
92529613 - `return_code: number`
92539614
from line 9618
92579618
92589619 - `type: "bash_code_execution_result"`
92599620
9260 - `"bash_code_execution_result"`
9621 default: bash_code_execution_result
92619622
92629623 - `tool_use_id: string`
92639624
9625 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9626
92649627 - `type: "bash_code_execution_tool_result"`
92659628
9266 - `"bash_code_execution_tool_result"`
9267
9268 - `BetaTextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }`
9629 default: bash_code_execution_tool_result
9630
9631 - `BetaTextEditorCodeExecutionToolResultBlock object`
92699632
92709633 - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock`
92719634
9272 - `BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }`
9635 - `BetaTextEditorCodeExecutionToolResultError object`
92739636
92749637 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
92759638
from line 9650
92879650
92889651 - `type: "text_editor_code_execution_tool_result_error"`
92899652
9290 - `"text_editor_code_execution_tool_result_error"`
9291
9292 - `BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }`
9653 default: text_editor_code_execution_tool_result_error
9654
9655 - `BetaTextEditorCodeExecutionViewResultBlock object`
92939656
92949657 - `content: string`
92959658
from line 9672
93099672
93109673 - `type: "text_editor_code_execution_view_result"`
93119674
9312 - `"text_editor_code_execution_view_result"`
9313
9314 - `BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }`
9675 default: text_editor_code_execution_view_result
9676
9677 - `BetaTextEditorCodeExecutionCreateResultBlock object`
93159678
93169679 - `is_file_update: boolean`
93179680
93189681 - `type: "text_editor_code_execution_create_result"`
93199682
9320 - `"text_editor_code_execution_create_result"`
9321
9322 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }`
9683 default: text_editor_code_execution_create_result
9684
9685 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object`
93239686
93249687 - `lines: array of string or null`
93259688
from line 9696
93339696
93349697 - `type: "text_editor_code_execution_str_replace_result"`
93359698
9336 - `"text_editor_code_execution_str_replace_result"`
9699 default: text_editor_code_execution_str_replace_result
93379700
93389701 - `tool_use_id: string`
93399702
9703 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9704
93409705 - `type: "text_editor_code_execution_tool_result"`
93419706
9342 - `"text_editor_code_execution_tool_result"`
9343
9344 - `BetaToolSearchToolResultBlock object { content, tool_use_id, type }`
9707 default: text_editor_code_execution_tool_result
9708
9709 - `BetaToolSearchToolResultBlock object`
93459710
93469711 - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock`
93479712
9348 - `BetaToolSearchToolResultError object { error_code, error_message, type }`
9713 - `BetaToolSearchToolResultError object`
93499714
93509715 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
93519716
from line 9726
93619726
93629727 - `type: "tool_search_tool_result_error"`
93639728
9364 - `"tool_search_tool_result_error"`
9365
9366 - `BetaToolSearchToolSearchResultBlock object { tool_references, type }`
9729 default: tool_search_tool_result_error
9730
9731 - `BetaToolSearchToolSearchResultBlock object`
93679732
93689733 - `tool_references: array of BetaToolReferenceBlock`
93699734
93709735 - `tool_name: string`
93719736
9737 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
9738
93729739 - `type: "tool_reference"`
93739740
9374 - `"tool_reference"`
9741 default: tool_reference
93759742
93769743 - `type: "tool_search_tool_search_result"`
93779744
9378 - `"tool_search_tool_search_result"`
9745 default: tool_search_tool_search_result
93799746
93809747 - `tool_use_id: string`
93819748
9749 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
9750
93829751 - `type: "tool_search_tool_result"`
93839752
9384 - `"tool_search_tool_result"`
9385
9386 - `BetaMCPToolUseBlock object { id, input, name, 2 more }`
9753 default: tool_search_tool_result
9754
9755 - `BetaMCPToolUseBlock object`
93879756
93889757 - `id: string`
93899758
9759 pattern: ^[a-zA-Z0-9_-]+$
9760
93909761 - `input: map[unknown]`
93919762
93929763 - `name: string`
from line 9770
93999770
94009771 - `type: "mcp_tool_use"`
94019772
9402 - `"mcp_tool_use"`
9403
9404 - `BetaMCPToolResultBlock object { content, is_error, tool_use_id, type }`
9773 default: mcp_tool_use
9774
9775 - `BetaMCPToolResultBlock object`
94059776
94069777 - `content: string or array of BetaTextBlock`
94079778
from line 9788
94179788
94189789 - `text: string`
94199790
9791 maxLength: 5000000, minLength: 0
9792
94209793 - `type: "text"`
94219794
9795 default: text
9796
94229797 - `is_error: boolean`
94239798
9799 default: false
9800
94249801 - `tool_use_id: string`
94259802
9803 pattern: ^[a-zA-Z0-9_-]+$
9804
94269805 - `type: "mcp_tool_result"`
94279806
9428 - `"mcp_tool_result"`
9429
9430 - `BetaContainerUploadBlock object { file_id, type }`
9807 default: mcp_tool_result
9808
9809 - `BetaContainerUploadBlock object`
94319810
94329811 Response model for a file uploaded to the container.
94339812
from line 9814
94359814
94369815 - `type: "container_upload"`
94379816
9438 - `"container_upload"`
9439
9440 - `BetaCompactionBlock object { content, encrypted_content, type }`
9817 default: container_upload
9818
9819 - `BetaCompactionBlock object`
94419820
94429821 A compaction block returned when autocompact is triggered.
94439822
from line 9834
94559834
94569835 - `type: "compaction"`
94579836
9458 - `"compaction"`
9459
9460 - `BetaFallbackBlock object { from, to, trigger, type }`
9837 default: compaction
9838
9839 - `BetaFallbackBlock object`
94619840
94629841 Marks the point in `content` where one model's output gives way to the next.
94639842
from line 9962
95839962
95849963 - `type: "refusal"`
95859964
9586 - `"refusal"`
9965 default: refusal
95879966
95889967 - `type: "fallback"`
95899968
9590 - `"fallback"`
9969 default: fallback
95919970
95929971 - `context_management: BetaContextManagementResponse or null`
95939972
from line 9978
95999978
96009979 List of context management edits that were applied.
96019980
9602 - `BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }`
9981 - `BetaClearToolUses20250919EditResponse object`
96039982
96049983 - `cleared_input_tokens: number`
96059984
96069985 Number of input tokens cleared by this edit.
96079986
9987 minimum: 0
9988
96089989 - `cleared_tool_uses: number`
96099990
96109991 Number of tool uses that were cleared.
96119992
9993 minimum: 0
9994
96129995 - `type: "clear_tool_uses_20250919"`
96139996
96149997 The type of context management edit applied.
96159998
9616 - `"clear_tool_uses_20250919"`
9617
9618 - `BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }`
9999 default: clear_tool_uses_20250919
10000
10001 - `BetaClearThinking20251015EditResponse object`
961910002
962010003 - `cleared_input_tokens: number`
962110004
962210005 Number of input tokens cleared by this edit.
962310006
10007 minimum: 0
10008
962410009 - `cleared_thinking_turns: number`
962510010
962610011 Number of thinking turns that were cleared.
962710012
10013 minimum: 0
10014
962810015 - `type: "clear_thinking_20251015"`
962910016
963010017 The type of context management edit applied.
963110018
9632 - `"clear_thinking_20251015"`
10019 default: clear_thinking_20251015
963310020
963410021 - `diagnostics: BetaDiagnostics or null`
963510022
from line 10027
964010027
964110028 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.
964210029
9643 - `BetaCacheMissModelChanged object { cache_missed_input_tokens, type }`
10030 - `BetaCacheMissModelChanged object`
964410031
964510032 - `cache_missed_input_tokens: number`
964610033
from line 10035
964810035
964910036 - `type: "model_changed"`
965010037
9651 - `"model_changed"`
9652
9653 - `BetaCacheMissSystemChanged object { cache_missed_input_tokens, type }`
10038 default: model_changed
10039
10040 - `BetaCacheMissSystemChanged object`
965410041
965510042 - `cache_missed_input_tokens: number`
965610043
from line 10045
965810045
965910046 - `type: "system_changed"`
966010047
9661 - `"system_changed"`
9662
9663 - `BetaCacheMissToolsChanged object { cache_missed_input_tokens, type }`
10048 default: system_changed
10049
10050 - `BetaCacheMissToolsChanged object`
966410051
966510052 - `cache_missed_input_tokens: number`
966610053
from line 10055
966810055
966910056 - `type: "tools_changed"`
967010057
9671 - `"tools_changed"`
9672
9673 - `BetaCacheMissMessagesChanged object { cache_missed_input_tokens, type }`
10058 default: tools_changed
10059
10060 - `BetaCacheMissMessagesChanged object`
967410061
967510062 - `cache_missed_input_tokens: number`
967610063
from line 10065
967810065
967910066 - `type: "messages_changed"`
968010067
9681 - `"messages_changed"`
9682
9683 - `BetaCacheMissPreviousMessageNotFound object { type }`
10068 default: messages_changed
10069
10070 - `BetaCacheMissPreviousMessageNotFound object`
968410071
968510072 - `type: "previous_message_not_found"`
968610073
9687 - `"previous_message_not_found"`
9688
9689 - `BetaCacheMissUnavailable object { type }`
10074 default: previous_message_not_found
10075
10076 - `BetaCacheMissUnavailable object`
969010077
969110078 - `type: "unavailable"`
969210079
9693 - `"unavailable"`
10080 default: unavailable
969410081
969510082 - `model: Model`
969610083
from line 10091
970410091
970510092 This will always be `"assistant"`.
970610093
9707 - `"assistant"`
10094 default: assistant
970810095
970910096 - `stop_details: BetaRefusalStopDetails or null`
971010097
from line 10178
979110178
979210179 - `type: "refusal"`
979310180
9794 - `"refusal"`
10181 default: refusal
979510182
979610183 - `stop_reason: BetaStopReason or null`
979710184
from line 10224
983710224
983810225 For Messages, this is always `"message"`.
983910226
9840 - `"message"`
10227 default: message
984110228
984210229 - `usage: BetaUsage`
984310230
from line 10246
985910246
986010247 The number of input tokens used to create the 1 hour cache entry.
986110248
10249 default: 0, minimum: 0
10250
986210251 - `ephemeral_5m_input_tokens: number`
986310252
986410253 The number of input tokens used to create the 5 minute cache entry.
986510254
10255 default: 0, minimum: 0
10256
986610257 - `cache_creation_input_tokens: number or null`
986710258
986810259 The number of input tokens used to create the cache entry.
986910260
10261 minimum: 0
10262
987010263 - `cache_read_input_tokens: number or null`
987110264
987210265 The number of input tokens read from the cache.
10266
10267 minimum: 0
987310268
987410269 - `fallback_credit: BetaFallbackCreditUsage or null`
987510270
from line 10279
988410279 resulting shift is zero because there was nothing to move. `not_applied`:
988510280 no reprice was applied; the arm's `reason` says why.
988610281
9887 - `BetaFallbackCreditRedeemed object { type }`
10282 - `BetaFallbackCreditRedeemed object`
988810283
988910284 The reprice was applied: the retry is billed as if the conversation
989010285 had been on the retry model all along.
989110286
989210287 - `type: "redeemed"`
989310288
9894 - `"redeemed"`
9895
9896 - `BetaFallbackCreditNotApplied object { reason, type, remove_to_redeem }`
10289 default: redeemed
10290
10291 - `BetaFallbackCreditNotApplied object`
989710292
989810293 No reprice was applied; `reason` says why.
989910294
from line 10325
993010325
993110326 - `type: "not_applied"`
993210327
9933 - `"not_applied"`
10328 default: not_applied
993410329
993510330 - `remove_to_redeem: optional array of string or null`
993610331
from line 10346
995110346
995210347 The number of input tokens which were used.
995310348
10349 minimum: 0
10350
995410351 - `iterations: BetaIterationsUsage or null`
995510352
995610353 Per-iteration token usage breakdown.
from line 10358
996110358 - Calculate the true context window size from the last iteration
996210359 - Understand token accumulation across server-side tool use loops
996310360
9964 - `BetaMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
10361 - `BetaMessageIterationUsage object`
996510362
996610363 Token usage for a sampling iteration.
996710364
from line 10370
997310370
997410371 The number of input tokens used to create the cache entry.
997510372
10373 default: 0, minimum: 0
10374
997610375 - `cache_read_input_tokens: number`
997710376
997810377 The number of input tokens read from the cache.
997910378
10379 default: 0, minimum: 0
10380
998010381 - `input_tokens: number`
998110382
998210383 The number of input tokens which were used.
998310384
10385 minimum: 0
10386
998410387 - `model: Model`
998510388
998610389 The model that will complete your prompt.
from line 10394
999110394
999210395 The number of output tokens which were used.
999310396
10397 minimum: 0
10398
999410399 - `type: "message"`
999510400
999610401 Usage for a sampling iteration
999710402
9998 - `"message"`
9999
10000 - `BetaCompactionIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }`
10403 default: message
10404
10405 - `BetaCompactionIterationUsage object`
1000110406
1000210407 Token usage for a compaction iteration.
1000310408
from line 10414
1000910414
1001010415 The number of input tokens used to create the cache entry.
1001110416
10417 default: 0, minimum: 0
10418
1001210419 - `cache_read_input_tokens: number`
1001310420
1001410421 The number of input tokens read from the cache.
1001510422
10423 default: 0, minimum: 0
10424
1001610425 - `input_tokens: number`
1001710426
1001810427 The number of input tokens which were used.
1001910428
10429 minimum: 0
10430
1002010431 - `output_tokens: number`
1002110432
1002210433 The number of output tokens which were used.
1002310434
10435 minimum: 0
10436
1002410437 - `type: "compaction"`
1002510438
1002610439 Usage for a compaction iteration
1002710440
10028 - `"compaction"`
10029
10030 - `BetaAdvisorMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
10441 default: compaction
10442
10443 - `BetaAdvisorMessageIterationUsage object`
1003110444
1003210445 Token usage for an advisor sub-inference iteration.
1003310446
from line 10452
1003910452
1004010453 The number of input tokens used to create the cache entry.
1004110454
10455 default: 0, minimum: 0
10456
1004210457 - `cache_read_input_tokens: number`
1004310458
1004410459 The number of input tokens read from the cache.
1004510460
10461 default: 0, minimum: 0
10462
1004610463 - `input_tokens: number`
1004710464
1004810465 The number of input tokens which were used.
1004910466
10467 minimum: 0
10468
1005010469 - `model: Model`
1005110470
1005210471 The model that will complete your prompt.
from line 10476
1005710476
1005810477 The number of output tokens which were used.
1005910478
10479 minimum: 0
10480
1006010481 - `type: "advisor_message"`
1006110482
1006210483 Usage for an advisor sub-inference iteration
1006310484
10064 - `"advisor_message"`
10065
10066 - `BetaFallbackMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
10485 default: advisor_message
10486
10487 - `BetaFallbackMessageIterationUsage object`
1006710488
1006810489 Token usage for the fallback-model attempt of a server-side fallback request.
1006910490
from line 10501
1008010501
1008110502 The number of input tokens used to create the cache entry.
1008210503
10504 default: 0, minimum: 0
10505
1008310506 - `cache_read_input_tokens: number`
1008410507
1008510508 The number of input tokens read from the cache.
1008610509
10510 default: 0, minimum: 0
10511
1008710512 - `input_tokens: number`
1008810513
1008910514 The number of input tokens which were used.
1009010515
10516 minimum: 0
10517
1009110518 - `model: Model`
1009210519
1009310520 The model that will complete your prompt.
from line 10525
1009810525
1009910526 The number of output tokens which were used.
1010010527
10528 minimum: 0
10529
1010110530 - `type: "fallback_message"`
1010210531
1010310532 Usage for the fallback-model attempt that served the response
1010410533
10105 - `"fallback_message"`
10534 default: fallback_message
1010610535
1010710536 - `output_tokens: number`
1010810537
1010910538 The number of output tokens which were used.
10539
10540 minimum: 0
1011010541
1011110542 - `output_tokens_details: BetaOutputTokensDetails or null`
1011210543
from line 10559
1012810559 generation count by a small number of tokens. Always ≤ `output_tokens`;
1012910560 `output_tokens - thinking_tokens` approximates the non-reasoning output.
1013010561
10562 default: 0, minimum: 0
10563
1013110564 - `server_tool_use: BetaServerToolUsage or null`
1013210565
1013310566 The number of server tool requests.
from line 10569
1013610569
1013710570 The number of web fetch tool requests.
1013810571
10572 default: 0, minimum: 0
10573
1013910574 - `web_search_requests: number`
1014010575
1014110576 The number of web search tool requests.
1014210577
10578 default: 0, minimum: 0
10579
1014310580 - `service_tier: "standard" or "priority" or "batch" or null`
1014410581
1014510582 If the request used the priority, standard, or batch tier.
from line 10597
1016010597
1016110598 - `type: "succeeded"`
1016210599
10163 - `"succeeded"`
10164
10165 - `BetaMessageBatchErroredResult object { error, type }`
10600 default: succeeded
10601
10602 - `BetaMessageBatchErroredResult object`
1016610603
1016710604 - `error: BetaErrorResponse`
1016810605
1016910606 - `error: BetaError`
1017010607
10171 - `BetaInvalidRequestError object { message, type }`
10608 - `BetaInvalidRequestError object`
1017210609
1017310610 - `message: string`
1017410611
10612 default: Invalid request
10613
1017510614 - `type: "invalid_request_error"`
1017610615
10177 - `"invalid_request_error"`
10178
10179 - `BetaAuthenticationError object { message, type }`
10616 default: invalid_request_error
10617
10618 - `BetaAuthenticationError object`
1018010619
1018110620 - `message: string`
1018210621
10622 default: Authentication error
10623
1018310624 - `type: "authentication_error"`
1018410625
10185 - `"authentication_error"`
10186
10187 - `BetaBillingError object { message, type }`
10626 default: authentication_error
10627
10628 - `BetaBillingError object`
1018810629
1018910630 - `message: string`
1019010631
10632 default: Billing error
10633
1019110634 - `type: "billing_error"`
1019210635
10193 - `"billing_error"`
10194
10195 - `BetaPermissionError object { message, type }`
10636 default: billing_error
10637
10638 - `BetaPermissionError object`
1019610639
1019710640 - `message: string`
1019810641
10642 default: Permission denied
10643
1019910644 - `type: "permission_error"`
1020010645
10201 - `"permission_error"`
10202
10203 - `BetaNotFoundError object { message, type }`
10646 default: permission_error
10647
10648 - `BetaNotFoundError object`
1020410649
1020510650 - `message: string`
1020610651
10652 default: Not found
10653
1020710654 - `type: "not_found_error"`
1020810655
10209 - `"not_found_error"`
10210
10211 - `BetaRateLimitError object { message, type }`
10656 default: not_found_error
10657
10658 - `BetaRateLimitError object`
1021210659
1021310660 - `message: string`
1021410661
10662 default: Rate limited
10663
1021510664 - `type: "rate_limit_error"`
1021610665
10217 - `"rate_limit_error"`
10218
10219 - `BetaGatewayTimeoutError object { message, type }`
10666 default: rate_limit_error
10667
10668 - `BetaGatewayTimeoutError object`
1022010669
1022110670 - `message: string`
1022210671
10672 default: Request timeout
10673
1022310674 - `type: "timeout_error"`
1022410675
10225 - `"timeout_error"`
10226
10227 - `BetaAPIError object { message, type }`
10676 default: timeout_error
10677
10678 - `BetaAPIError object`
1022810679
1022910680 - `message: string`
1023010681
10682 default: Internal server error
10683
1023110684 - `type: "api_error"`
1023210685
10233 - `"api_error"`
10234
10235 - `BetaOverloadedError object { message, type }`
10686 default: api_error
10687
10688 - `BetaOverloadedError object`
1023610689
1023710690 - `message: string`
1023810691
10692 default: Overloaded
10693
1023910694 - `type: "overloaded_error"`
1024010695
10241 - `"overloaded_error"`
10696 default: overloaded_error
1024210697
1024310698 - `request_id: string or null`
1024410699
1024510700 - `type: "error"`
1024610701
10247 - `"error"`
10702 default: error
1024810703
1024910704 - `type: "errored"`
1025010705
10251 - `"errored"`
10252
10253 - `BetaMessageBatchCanceledResult object { type }`
10706 default: errored
10707
10708 - `BetaMessageBatchCanceledResult object`
1025410709
1025510710 - `type: "canceled"`
1025610711
10257 - `"canceled"`
10258
10259 - `BetaMessageBatchExpiredResult object { type }`
10712 default: canceled
10713
10714 - `BetaMessageBatchExpiredResult object`
1026010715
1026110716 - `type: "expired"`
1026210717
10263 - `"expired"`
10718 default: expired
1026410719
1026510720### Beta Message Batch Succeeded Result
1026610721
10267- `BetaMessageBatchSucceededResult object { message, type }`
10722- `BetaMessageBatchSucceededResult object`
1026810723
1026910724 - `message: BetaMessage`
1027010725
from line 10741
1028610741
1028710742 The time at which the container will expire.
1028810743
10744 format: date-time
10745
1028910746 - `skills: array of BetaSkill or null`
1029010747
1029110748 Skills loaded in the container
from line 10751
1029410751
1029510752 Skill ID
1029610753
10754 maxLength: 64, minLength: 1
10755
1029710756 - `type: "anthropic" or "custom"`
1029810757
1029910758 Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
from line 10764
1030510764 - `version: string`
1030610765
1030710766 The resolved version: a skill version ID for custom skills.
10767
10768 maxLength: 64, minLength: 1
1030810769
1030910770 - `content: array of BetaContentBlock`
1031010771
from line 10796
1033510796 [{"type": "text", "text": "B)"}]
1033610797 ```
1033710798
10338 - `BetaTextBlock object { citations, text, type }`
10799 - `BetaTextBlock object`
1033910800
1034010801 - `citations: array of BetaTextCitation or null`
1034110802
from line 10804
1034310804
1034410805 The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`.
1034510806
10346 - `BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }`
10807 - `BetaCitationCharLocation object`
1034710808
1034810809 - `cited_text: string`
1034910810
1035010811 - `document_index: number`
1035110812
10813 minimum: 0
10814
1035210815 - `document_title: string or null`
1035310816
1035410817 - `end_char_index: number`
from line 10820
1035710820
1035810821 - `start_char_index: number`
1035910822
10823 minimum: 0
10824
1036010825 - `type: "char_location"`
1036110826
10362 - `"char_location"`
10363
10364 - `BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }`
10827 default: char_location
10828
10829 - `BetaCitationPageLocation object`
1036510830
1036610831 - `cited_text: string`
1036710832
1036810833 - `document_index: number`
1036910834
10835 minimum: 0
10836
1037010837 - `document_title: string or null`
1037110838
1037210839 - `end_page_number: number`
from line 10842
1037510842
1037610843 - `start_page_number: number`
1037710844
10845 minimum: 1
10846
1037810847 - `type: "page_location"`
1037910848
10380 - `"page_location"`
10381
10382 - `BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }`
10849 default: page_location
10850
10851 - `BetaCitationContentBlockLocation object`
1038310852
1038410853 - `cited_text: string`
1038510854
from line 10858
1038910858
1039010859 - `document_index: number`
1039110860
10861 minimum: 0
10862
1039210863 - `document_title: string or null`
1039310864
1039410865 - `end_block_index: number`
from line 10874
1040310874
1040410875 0-based index of the first cited block in the source's `content` array.
1040510876
10877 minimum: 0
10878
1040610879 - `type: "content_block_location"`
1040710880
10408 - `"content_block_location"`
10409
10410 - `BetaCitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }`
10881 default: content_block_location
10882
10883 - `BetaCitationsWebSearchResultLocation object`
1041110884
1041210885 - `cited_text: string`
1041310886
from line 10888
1041510888
1041610889 - `title: string or null`
1041710890
10891 maxLength: 512
10892
1041810893 - `type: "web_search_result_location"`
1041910894
10420 - `"web_search_result_location"`
10895 default: web_search_result_location
1042110896
1042210897 - `url: string`
1042310898
10424 - `BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }`
10899 - `BetaCitationSearchResultLocation object`
1042510900
1042610901 - `cited_text: string`
1042710902
from line 10916
1044110916
1044210917 Counted separately from `document_index`; server-side web search results are not included in this count.
1044310918
10919 minimum: 0
10920
1044410921 - `source: string`
1044510922
1044610923 - `start_block_index: number`
1044710924
1044810925 0-based index of the first cited block in the source's `content` array.
1044910926
10927 minimum: 0
10928
1045010929 - `title: string or null`
1045110930
1045210931 - `type: "search_result_location"`
1045310932
10454 - `"search_result_location"`
10933 default: search_result_location
1045510934
1045610935 - `text: string`
1045710936
10937 maxLength: 5000000, minLength: 0
10938
1045810939 - `type: "text"`
1045910940
10460 - `"text"`
10461
10462 - `BetaThinkingBlock object { signature, thinking, type }`
10941 default: text
10942
10943 - `BetaThinkingBlock object`
1046310944
1046410945 - `signature: string`
1046510946
from line 10956
1047510956
1047610957 - `type: "thinking"`
1047710958
10478 - `"thinking"`
10479
10480 - `BetaRedactedThinkingBlock object { data, type }`
10959 default: thinking
10960
10961 - `BetaRedactedThinkingBlock object`
1048110962
1048210963 - `data: string`
1048310964
from line 10970
1048910970
1049010971 - `type: "redacted_thinking"`
1049110972
10492 - `"redacted_thinking"`
10493
10494 - `BetaToolUseBlock object { id, input, name, 3 more }`
10973 default: redacted_thinking
10974
10975 - `BetaToolUseBlock object`
1049510976
1049610977 - `id: string`
1049710978
10979 pattern: ^[a-zA-Z0-9_-]+$
10980
1049810981 - `input: map[unknown]`
1049910982
1050010983 - `name: string`
1050110984
10985 minLength: 1
10986
1050210987 - `type: "tool_use"`
1050310988
10504 - `"tool_use"`
10989 default: tool_use
1050510990
1050610991 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
1050710992
1050810993 Tool invocation directly from the model.
1050910994
10510 - `BetaDirectCaller object { type }`
10995 - `BetaDirectCaller object`
1051110996
1051210997 Tool invocation directly from the model.
1051310998
1051410999 - `type: "direct"`
1051511000
10516 - `"direct"`
10517
10518 - `BetaServerToolCaller object { tool_id, type }`
11001 - `BetaServerToolCaller object`
1051911002
1052011003 Tool invocation generated by a server-side tool.
1052111004
1052211005 - `tool_id: string`
1052311006
11007 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11008
1052411009 - `type: "code_execution_20250825"`
1052511010
10526 - `"code_execution_20250825"`
10527
10528 - `BetaServerToolCaller20260120 object { tool_id, type }`
11011 - `BetaServerToolCaller20260120 object`
1052911012
1053011013 - `tool_id: string`
1053111014
11015 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11016
1053211017 - `type: "code_execution_20260120"`
1053311018
10534 - `"code_execution_20260120"`
10535
1053611019 - `toolset_name: optional string or null`
1053711020
1053811021 For a toolset member tool_use, the toolset family.
1053911022
10540 - `BetaServerToolUseBlock object { id, input, name, 2 more }`
11023 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
11024
11025 - `BetaServerToolUseBlock object`
1054111026
1054211027 - `id: string`
1054311028
11029 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11030
1054411031 - `input: map[unknown]`
1054511032
1054611033 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 11050
1056311050
1056411051 - `type: "server_tool_use"`
1056511052
10566 - `"server_tool_use"`
11053 default: server_tool_use
1056711054
1056811055 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
1056911056
1057011057 Tool invocation directly from the model.
1057111058
10572 - `BetaDirectCaller object { type }`
11059 - `BetaDirectCaller object`
1057311060
1057411061 Tool invocation directly from the model.
1057511062
10576 - `BetaServerToolCaller object { tool_id, type }`
11063 - `BetaServerToolCaller object`
1057711064
1057811065 Tool invocation generated by a server-side tool.
1057911066
10580 - `BetaServerToolCaller20260120 object { tool_id, type }`
10581
10582 - `BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }`
11067 - `BetaServerToolCaller20260120 object`
11068
11069 - `BetaWebSearchToolResultBlock object`
1058311070
1058411071 - `content: BetaWebSearchToolResultBlockContent`
1058511072
10586 - `BetaWebSearchToolResultError object { error_code, type }`
11073 - `BetaWebSearchToolResultError object`
1058711074
1058811075 - `error_code: BetaWebSearchToolResultErrorCode`
1058911076
from line 11088
1060111088
1060211089 - `type: "web_search_tool_result_error"`
1060311090
10604 - `"web_search_tool_result_error"`
11091 default: web_search_tool_result_error
1060511092
1060611093 - `array of BetaWebSearchResultBlock`
1060711094
from line 11100
1061311100
1061411101 - `type: "web_search_result"`
1061511102
10616 - `"web_search_result"`
11103 default: web_search_result
1061711104
1061811105 - `url: string`
1061911106
1062011107 - `tool_use_id: string`
1062111108
11109 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11110
1062211111 - `type: "web_search_tool_result"`
1062311112
10624 - `"web_search_tool_result"`
11113 default: web_search_tool_result
1062511114
1062611115 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
1062711116
1062811117 Tool invocation directly from the model.
1062911118
10630 - `BetaDirectCaller object { type }`
11119 - `BetaDirectCaller object`
1063111120
1063211121 Tool invocation directly from the model.
1063311122
10634 - `BetaServerToolCaller object { tool_id, type }`
11123 - `BetaServerToolCaller object`
1063511124
1063611125 Tool invocation generated by a server-side tool.
1063711126
10638 - `BetaServerToolCaller20260120 object { tool_id, type }`
10639
10640 - `BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }`
11127 - `BetaServerToolCaller20260120 object`
11128
11129 - `BetaWebFetchToolResultBlock object`
1064111130
1064211131 - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock`
1064311132
10644 - `BetaWebFetchToolResultErrorBlock object { error_code, type }`
11133 - `BetaWebFetchToolResultErrorBlock object`
1064511134
1064611135 - `error_code: BetaWebFetchToolResultErrorCode`
1064711136
from line 11154
1066511154
1066611155 - `type: "web_fetch_tool_result_error"`
1066711156
10668 - `"web_fetch_tool_result_error"`
10669
10670 - `BetaWebFetchBlock object { content, retrieved_at, type, url }`
11157 default: web_fetch_tool_result_error
11158
11159 - `BetaWebFetchBlock object`
1067111160
1067211161 - `content: BetaDocumentBlock`
1067311162
from line 11166
1067711166
1067811167 - `enabled: boolean`
1067911168
11169 default: false
11170
1068011171 - `source: BetaBase64PDFSource or BetaPlainTextSource`
1068111172
10682 - `BetaBase64PDFSource object { data, media_type, type }`
11173 - `BetaBase64PDFSource object`
1068311174
1068411175 - `data: string`
1068511176
11177 format: byte
11178
1068611179 - `media_type: "application/pdf"`
1068711180
10688 - `"application/pdf"`
10689
1069011181 - `type: "base64"`
1069111182
10692 - `"base64"`
10693
10694 - `BetaPlainTextSource object { data, media_type, type }`
11183 - `BetaPlainTextSource object`
1069511184
1069611185 - `data: string`
1069711186
1069811187 - `media_type: "text/plain"`
1069911188
10700 - `"text/plain"`
10701
1070211189 - `type: "text"`
1070311190
10704 - `"text"`
10705
1070611191 - `title: string or null`
1070711192
1070811193 The title of the document
1070911194
1071011195 - `type: "document"`
1071111196
10712 - `"document"`
11197 default: document
1071311198
1071411199 - `retrieved_at: string or null`
1071511200
from line 11202
1071711202
1071811203 - `type: "web_fetch_result"`
1071911204
10720 - `"web_fetch_result"`
11205 default: web_fetch_result
1072111206
1072211207 - `url: string`
1072311208
from line 11210
1072511210
1072611211 - `tool_use_id: string`
1072711212
11213 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11214
1072811215 - `type: "web_fetch_tool_result"`
1072911216
10730 - `"web_fetch_tool_result"`
11217 default: web_fetch_tool_result
1073111218
1073211219 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
1073311220
1073411221 Tool invocation directly from the model.
1073511222
10736 - `BetaDirectCaller object { type }`
11223 - `BetaDirectCaller object`
1073711224
1073811225 Tool invocation directly from the model.
1073911226
10740 - `BetaServerToolCaller object { tool_id, type }`
11227 - `BetaServerToolCaller object`
1074111228
1074211229 Tool invocation generated by a server-side tool.
1074311230
10744 - `BetaServerToolCaller20260120 object { tool_id, type }`
10745
10746 - `BetaAdvisorToolResultBlock object { content, tool_use_id, type }`
11231 - `BetaServerToolCaller20260120 object`
11232
11233 - `BetaAdvisorToolResultBlock object`
1074711234
1074811235 - `content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock`
1074911236
10750 - `BetaAdvisorToolResultError object { error_code, type }`
11237 - `BetaAdvisorToolResultError object`
1075111238
1075211239 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
1075311240
from line 11254
1076711254
1076811255 - `type: "advisor_tool_result_error"`
1076911256
10770 - `"advisor_tool_result_error"`
10771
10772 - `BetaAdvisorResultBlock object { stop_reason, text, type }`
11257 default: advisor_tool_result_error
11258
11259 - `BetaAdvisorResultBlock object`
1077311260
1077411261 - `stop_reason: string or null`
1077511262
from line 11266
1077911266
1078011267 - `type: "advisor_result"`
1078111268
10782 - `"advisor_result"`
10783
10784 - `BetaAdvisorRedactedResultBlock object { encrypted_content, stop_reason, type }`
11269 default: advisor_result
11270
11271 - `BetaAdvisorRedactedResultBlock object`
1078511272
1078611273 - `encrypted_content: string`
1078711274
from line 11280
1079311280
1079411281 - `type: "advisor_redacted_result"`
1079511282
10796 - `"advisor_redacted_result"`
11283 default: advisor_redacted_result
1079711284
1079811285 - `tool_use_id: string`
1079911286
11287 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11288
1080011289 - `type: "advisor_tool_result"`
1080111290
10802 - `"advisor_tool_result"`
10803
10804 - `BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }`
11291 default: advisor_tool_result
11292
11293 - `BetaCodeExecutionToolResultBlock object`
1080511294
1080611295 - `content: BetaCodeExecutionToolResultBlockContent`
1080711296
1080811297 Code execution result with encrypted stdout for PFC + web_search results.
1080911298
10810 - `BetaCodeExecutionToolResultError object { error_code, type }`
11299 - `BetaCodeExecutionToolResultError object`
1081111300
1081211301 - `error_code: BetaCodeExecutionToolResultErrorCode`
1081311302
from line 11310
1082111310
1082211311 - `type: "code_execution_tool_result_error"`
1082311312
10824 - `"code_execution_tool_result_error"`
10825
10826 - `BetaCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
11313 default: code_execution_tool_result_error
11314
11315 - `BetaCodeExecutionResultBlock object`
1082711316
1082811317 - `content: array of BetaCodeExecutionOutputBlock`
1082911318
from line 11320
1083111320
1083211321 - `type: "code_execution_output"`
1083311322
10834 - `"code_execution_output"`
11323 default: code_execution_output
1083511324
1083611325 - `return_code: number`
1083711326
from line 11330
1084111330
1084211331 - `type: "code_execution_result"`
1084311332
10844 - `"code_execution_result"`
10845
10846 - `BetaEncryptedCodeExecutionResultBlock object { content, encrypted_stdout, return_code, 2 more }`
11333 default: code_execution_result
11334
11335 - `BetaEncryptedCodeExecutionResultBlock object`
1084711336
1084811337 Code execution result with encrypted stdout for PFC + web_search results.
1084911338
from line 11342
1085311342
1085411343 - `type: "code_execution_output"`
1085511344
11345 default: code_execution_output
11346
1085611347 - `encrypted_stdout: string`
1085711348
1085811349 - `return_code: number`
from line 11352
1086111352
1086211353 - `type: "encrypted_code_execution_result"`
1086311354
10864 - `"encrypted_code_execution_result"`
11355 default: encrypted_code_execution_result
1086511356
1086611357 - `tool_use_id: string`
1086711358
11359 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11360
1086811361 - `type: "code_execution_tool_result"`
1086911362
10870 - `"code_execution_tool_result"`
10871
10872 - `BetaBashCodeExecutionToolResultBlock object { content, tool_use_id, type }`
11363 default: code_execution_tool_result
11364
11365 - `BetaBashCodeExecutionToolResultBlock object`
1087311366
1087411367 - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock`
1087511368
10876 - `BetaBashCodeExecutionToolResultError object { error_code, type }`
11369 - `BetaBashCodeExecutionToolResultError object`
1087711370
1087811371 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
1087911372
from line 11382
1088911382
1089011383 - `type: "bash_code_execution_tool_result_error"`
1089111384
10892 - `"bash_code_execution_tool_result_error"`
10893
10894 - `BetaBashCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
11385 default: bash_code_execution_tool_result_error
11386
11387 - `BetaBashCodeExecutionResultBlock object`
1089511388
1089611389 - `content: array of BetaBashCodeExecutionOutputBlock`
1089711390
from line 11392
1089911392
1090011393 - `type: "bash_code_execution_output"`
1090111394
10902 - `"bash_code_execution_output"`
11395 default: bash_code_execution_output
1090311396
1090411397 - `return_code: number`
1090511398
from line 11402
1090911402
1091011403 - `type: "bash_code_execution_result"`
1091111404
10912 - `"bash_code_execution_result"`
11405 default: bash_code_execution_result
1091311406
1091411407 - `tool_use_id: string`
1091511408
11409 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11410
1091611411 - `type: "bash_code_execution_tool_result"`
1091711412
10918 - `"bash_code_execution_tool_result"`
10919
10920 - `BetaTextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }`
11413 default: bash_code_execution_tool_result
11414
11415 - `BetaTextEditorCodeExecutionToolResultBlock object`
1092111416
1092211417 - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock`
1092311418
10924 - `BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }`
11419 - `BetaTextEditorCodeExecutionToolResultError object`
1092511420
1092611421 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
1092711422
from line 11434
1093911434
1094011435 - `type: "text_editor_code_execution_tool_result_error"`
1094111436
10942 - `"text_editor_code_execution_tool_result_error"`
10943
10944 - `BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }`
11437 default: text_editor_code_execution_tool_result_error
11438
11439 - `BetaTextEditorCodeExecutionViewResultBlock object`
1094511440
1094611441 - `content: string`
1094711442
from line 11456
1096111456
1096211457 - `type: "text_editor_code_execution_view_result"`
1096311458
10964 - `"text_editor_code_execution_view_result"`
10965
10966 - `BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }`
11459 default: text_editor_code_execution_view_result
11460
11461 - `BetaTextEditorCodeExecutionCreateResultBlock object`
1096711462
1096811463 - `is_file_update: boolean`
1096911464
1097011465 - `type: "text_editor_code_execution_create_result"`
1097111466
10972 - `"text_editor_code_execution_create_result"`
10973
10974 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }`
11467 default: text_editor_code_execution_create_result
11468
11469 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object`
1097511470
1097611471 - `lines: array of string or null`
1097711472
from line 11480
1098511480
1098611481 - `type: "text_editor_code_execution_str_replace_result"`
1098711482
10988 - `"text_editor_code_execution_str_replace_result"`
11483 default: text_editor_code_execution_str_replace_result
1098911484
1099011485 - `tool_use_id: string`
1099111486
11487 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11488
1099211489 - `type: "text_editor_code_execution_tool_result"`
1099311490
10994 - `"text_editor_code_execution_tool_result"`
10995
10996 - `BetaToolSearchToolResultBlock object { content, tool_use_id, type }`
11491 default: text_editor_code_execution_tool_result
11492
11493 - `BetaToolSearchToolResultBlock object`
1099711494
1099811495 - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock`
1099911496
11000 - `BetaToolSearchToolResultError object { error_code, error_message, type }`
11497 - `BetaToolSearchToolResultError object`
1100111498
1100211499 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
1100311500
from line 11510
1101311510
1101411511 - `type: "tool_search_tool_result_error"`
1101511512
11016 - `"tool_search_tool_result_error"`
11017
11018 - `BetaToolSearchToolSearchResultBlock object { tool_references, type }`
11513 default: tool_search_tool_result_error
11514
11515 - `BetaToolSearchToolSearchResultBlock object`
1101911516
1102011517 - `tool_references: array of BetaToolReferenceBlock`
1102111518
1102211519 - `tool_name: string`
1102311520
11521 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
11522
1102411523 - `type: "tool_reference"`
1102511524
11026 - `"tool_reference"`
11525 default: tool_reference
1102711526
1102811527 - `type: "tool_search_tool_search_result"`
1102911528
11030 - `"tool_search_tool_search_result"`
11529 default: tool_search_tool_search_result
1103111530
1103211531 - `tool_use_id: string`
1103311532
11533 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
11534
1103411535 - `type: "tool_search_tool_result"`
1103511536
11036 - `"tool_search_tool_result"`
11037
11038 - `BetaMCPToolUseBlock object { id, input, name, 2 more }`
11537 default: tool_search_tool_result
11538
11539 - `BetaMCPToolUseBlock object`
1103911540
1104011541 - `id: string`
1104111542
11543 pattern: ^[a-zA-Z0-9_-]+$
11544
1104211545 - `input: map[unknown]`
1104311546
1104411547 - `name: string`
from line 11554
1105111554
1105211555 - `type: "mcp_tool_use"`
1105311556
11054 - `"mcp_tool_use"`
11055
11056 - `BetaMCPToolResultBlock object { content, is_error, tool_use_id, type }`
11557 default: mcp_tool_use
11558
11559 - `BetaMCPToolResultBlock object`
1105711560
1105811561 - `content: string or array of BetaTextBlock`
1105911562
from line 11572
1106911572
1107011573 - `text: string`
1107111574
11575 maxLength: 5000000, minLength: 0
11576
1107211577 - `type: "text"`
1107311578
11579 default: text
11580
1107411581 - `is_error: boolean`
1107511582
11583 default: false
11584
1107611585 - `tool_use_id: string`
1107711586
11587 pattern: ^[a-zA-Z0-9_-]+$
11588
1107811589 - `type: "mcp_tool_result"`
1107911590
11080 - `"mcp_tool_result"`
11081
11082 - `BetaContainerUploadBlock object { file_id, type }`
11591 default: mcp_tool_result
11592
11593 - `BetaContainerUploadBlock object`
1108311594
1108411595 Response model for a file uploaded to the container.
1108511596
from line 11598
1108711598
1108811599 - `type: "container_upload"`
1108911600
11090 - `"container_upload"`
11091
11092 - `BetaCompactionBlock object { content, encrypted_content, type }`
11601 default: container_upload
11602
11603 - `BetaCompactionBlock object`
1109311604
1109411605 A compaction block returned when autocompact is triggered.
1109511606
from line 11618
1110711618
1110811619 - `type: "compaction"`
1110911620
11110 - `"compaction"`
11111
11112 - `BetaFallbackBlock object { from, to, trigger, type }`
11621 default: compaction
11622
11623 - `BetaFallbackBlock object`
1111311624
1111411625 Marks the point in `content` where one model's output gives way to the next.
1111511626
from line 11746
1123511746
1123611747 - `type: "refusal"`
1123711748
11238 - `"refusal"`
11749 default: refusal
1123911750
1124011751 - `type: "fallback"`
1124111752
11242 - `"fallback"`
11753 default: fallback
1124311754
1124411755 - `context_management: BetaContextManagementResponse or null`
1124511756
from line 11762
1125111762
1125211763 List of context management edits that were applied.
1125311764
11254 - `BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }`
11765 - `BetaClearToolUses20250919EditResponse object`
1125511766
1125611767 - `cleared_input_tokens: number`
1125711768
1125811769 Number of input tokens cleared by this edit.
1125911770
11771 minimum: 0
11772
1126011773 - `cleared_tool_uses: number`
1126111774
1126211775 Number of tool uses that were cleared.
1126311776
11777 minimum: 0
11778
1126411779 - `type: "clear_tool_uses_20250919"`
1126511780
1126611781 The type of context management edit applied.
1126711782
11268 - `"clear_tool_uses_20250919"`
11269
11270 - `BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }`
11783 default: clear_tool_uses_20250919
11784
11785 - `BetaClearThinking20251015EditResponse object`
1127111786
1127211787 - `cleared_input_tokens: number`
1127311788
1127411789 Number of input tokens cleared by this edit.
1127511790
11791 minimum: 0
11792
1127611793 - `cleared_thinking_turns: number`
1127711794
1127811795 Number of thinking turns that were cleared.
1127911796
11797 minimum: 0
11798
1128011799 - `type: "clear_thinking_20251015"`
1128111800
1128211801 The type of context management edit applied.
1128311802
11284 - `"clear_thinking_20251015"`
11803 default: clear_thinking_20251015
1128511804
1128611805 - `diagnostics: BetaDiagnostics or null`
1128711806
from line 11811
1129211811
1129311812 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.
1129411813
11295 - `BetaCacheMissModelChanged object { cache_missed_input_tokens, type }`
11814 - `BetaCacheMissModelChanged object`
1129611815
1129711816 - `cache_missed_input_tokens: number`
1129811817
from line 11819
1130011819
1130111820 - `type: "model_changed"`
1130211821
11303 - `"model_changed"`
11304
11305 - `BetaCacheMissSystemChanged object { cache_missed_input_tokens, type }`
11822 default: model_changed
11823
11824 - `BetaCacheMissSystemChanged object`
1130611825
1130711826 - `cache_missed_input_tokens: number`
1130811827
from line 11829
1131011829
1131111830 - `type: "system_changed"`
1131211831
11313 - `"system_changed"`
11314
11315 - `BetaCacheMissToolsChanged object { cache_missed_input_tokens, type }`
11832 default: system_changed
11833
11834 - `BetaCacheMissToolsChanged object`
1131611835
1131711836 - `cache_missed_input_tokens: number`
1131811837
from line 11839
1132011839
1132111840 - `type: "tools_changed"`
1132211841
11323 - `"tools_changed"`
11324
11325 - `BetaCacheMissMessagesChanged object { cache_missed_input_tokens, type }`
11842 default: tools_changed
11843
11844 - `BetaCacheMissMessagesChanged object`
1132611845
1132711846 - `cache_missed_input_tokens: number`
1132811847
from line 11849
1133011849
1133111850 - `type: "messages_changed"`
1133211851
11333 - `"messages_changed"`
11334
11335 - `BetaCacheMissPreviousMessageNotFound object { type }`
11852 default: messages_changed
11853
11854 - `BetaCacheMissPreviousMessageNotFound object`
1133611855
1133711856 - `type: "previous_message_not_found"`
1133811857
11339 - `"previous_message_not_found"`
11340
11341 - `BetaCacheMissUnavailable object { type }`
11858 default: previous_message_not_found
11859
11860 - `BetaCacheMissUnavailable object`
1134211861
1134311862 - `type: "unavailable"`
1134411863
11345 - `"unavailable"`
11864 default: unavailable
1134611865
1134711866 - `model: Model`
1134811867
from line 11875
1135611875
1135711876 This will always be `"assistant"`.
1135811877
11359 - `"assistant"`
11878 default: assistant
1136011879
1136111880 - `stop_details: BetaRefusalStopDetails or null`
1136211881
from line 11962
1144311962
1144411963 - `type: "refusal"`
1144511964
11446 - `"refusal"`
11965 default: refusal
1144711966
1144811967 - `stop_reason: BetaStopReason or null`
1144911968
from line 12008
1148912008
1149012009 For Messages, this is always `"message"`.
1149112010
11492 - `"message"`
12011 default: message
1149312012
1149412013 - `usage: BetaUsage`
1149512014
from line 12030
1151112030
1151212031 The number of input tokens used to create the 1 hour cache entry.
1151312032
12033 default: 0, minimum: 0
12034
1151412035 - `ephemeral_5m_input_tokens: number`
1151512036
1151612037 The number of input tokens used to create the 5 minute cache entry.
1151712038
12039 default: 0, minimum: 0
12040
1151812041 - `cache_creation_input_tokens: number or null`
1151912042
1152012043 The number of input tokens used to create the cache entry.
1152112044
12045 minimum: 0
12046
1152212047 - `cache_read_input_tokens: number or null`
1152312048
1152412049 The number of input tokens read from the cache.
12050
12051 minimum: 0
1152512052
1152612053 - `fallback_credit: BetaFallbackCreditUsage or null`
1152712054
from line 12063
1153612063 resulting shift is zero because there was nothing to move. `not_applied`:
1153712064 no reprice was applied; the arm's `reason` says why.
1153812065
11539 - `BetaFallbackCreditRedeemed object { type }`
12066 - `BetaFallbackCreditRedeemed object`
1154012067
1154112068 The reprice was applied: the retry is billed as if the conversation
1154212069 had been on the retry model all along.
1154312070
1154412071 - `type: "redeemed"`
1154512072
11546 - `"redeemed"`
11547
11548 - `BetaFallbackCreditNotApplied object { reason, type, remove_to_redeem }`
12073 default: redeemed
12074
12075 - `BetaFallbackCreditNotApplied object`
1154912076
1155012077 No reprice was applied; `reason` says why.
1155112078
from line 12109
1158212109
1158312110 - `type: "not_applied"`
1158412111
11585 - `"not_applied"`
12112 default: not_applied
1158612113
1158712114 - `remove_to_redeem: optional array of string or null`
1158812115
from line 12130
1160312130
1160412131 The number of input tokens which were used.
1160512132
12133 minimum: 0
12134
1160612135 - `iterations: BetaIterationsUsage or null`
1160712136
1160812137 Per-iteration token usage breakdown.
from line 12142
1161312142 - Calculate the true context window size from the last iteration
1161412143 - Understand token accumulation across server-side tool use loops
1161512144
11616 - `BetaMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
12145 - `BetaMessageIterationUsage object`
1161712146
1161812147 Token usage for a sampling iteration.
1161912148
from line 12154
1162512154
1162612155 The number of input tokens used to create the cache entry.
1162712156
12157 default: 0, minimum: 0
12158
1162812159 - `cache_read_input_tokens: number`
1162912160
1163012161 The number of input tokens read from the cache.
1163112162
12163 default: 0, minimum: 0
12164
1163212165 - `input_tokens: number`
1163312166
1163412167 The number of input tokens which were used.
1163512168
12169 minimum: 0
12170
1163612171 - `model: Model`
1163712172
1163812173 The model that will complete your prompt.
from line 12178
1164312178
1164412179 The number of output tokens which were used.
1164512180
12181 minimum: 0
12182
1164612183 - `type: "message"`
1164712184
1164812185 Usage for a sampling iteration
1164912186
11650 - `"message"`
11651
11652 - `BetaCompactionIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }`
12187 default: message
12188
12189 - `BetaCompactionIterationUsage object`
1165312190
1165412191 Token usage for a compaction iteration.
1165512192
from line 12198
1166112198
1166212199 The number of input tokens used to create the cache entry.
1166312200
12201 default: 0, minimum: 0
12202
1166412203 - `cache_read_input_tokens: number`
1166512204
1166612205 The number of input tokens read from the cache.
1166712206
12207 default: 0, minimum: 0
12208
1166812209 - `input_tokens: number`
1166912210
1167012211 The number of input tokens which were used.
1167112212
12213 minimum: 0
12214
1167212215 - `output_tokens: number`
1167312216
1167412217 The number of output tokens which were used.
1167512218
12219 minimum: 0
12220
1167612221 - `type: "compaction"`
1167712222
1167812223 Usage for a compaction iteration
1167912224
11680 - `"compaction"`
11681
11682 - `BetaAdvisorMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
12225 default: compaction
12226
12227 - `BetaAdvisorMessageIterationUsage object`
1168312228
1168412229 Token usage for an advisor sub-inference iteration.
1168512230
from line 12236
1169112236
1169212237 The number of input tokens used to create the cache entry.
1169312238
12239 default: 0, minimum: 0
12240
1169412241 - `cache_read_input_tokens: number`
1169512242
1169612243 The number of input tokens read from the cache.
1169712244
12245 default: 0, minimum: 0
12246
1169812247 - `input_tokens: number`
1169912248
1170012249 The number of input tokens which were used.
1170112250
12251 minimum: 0
12252
1170212253 - `model: Model`
1170312254
1170412255 The model that will complete your prompt.
from line 12260
1170912260
1171012261 The number of output tokens which were used.
1171112262
12263 minimum: 0
12264
1171212265 - `type: "advisor_message"`
1171312266
1171412267 Usage for an advisor sub-inference iteration
1171512268
11716 - `"advisor_message"`
11717
11718 - `BetaFallbackMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
12269 default: advisor_message
12270
12271 - `BetaFallbackMessageIterationUsage object`
1171912272
1172012273 Token usage for the fallback-model attempt of a server-side fallback request.
1172112274
from line 12285
1173212285
1173312286 The number of input tokens used to create the cache entry.
1173412287
12288 default: 0, minimum: 0
12289
1173512290 - `cache_read_input_tokens: number`
1173612291
1173712292 The number of input tokens read from the cache.
1173812293
12294 default: 0, minimum: 0
12295
1173912296 - `input_tokens: number`
1174012297
1174112298 The number of input tokens which were used.
1174212299
12300 minimum: 0
12301
1174312302 - `model: Model`
1174412303
1174512304 The model that will complete your prompt.
from line 12309
1175012309
1175112310 The number of output tokens which were used.
1175212311
12312 minimum: 0
12313
1175312314 - `type: "fallback_message"`
1175412315
1175512316 Usage for the fallback-model attempt that served the response
1175612317
11757 - `"fallback_message"`
12318 default: fallback_message
1175812319
1175912320 - `output_tokens: number`
1176012321
1176112322 The number of output tokens which were used.
12323
12324 minimum: 0
1176212325
1176312326 - `output_tokens_details: BetaOutputTokensDetails or null`
1176412327
from line 12343
1178012343 generation count by a small number of tokens. Always ≤ `output_tokens`;
1178112344 `output_tokens - thinking_tokens` approximates the non-reasoning output.
1178212345
12346 default: 0, minimum: 0
12347
1178312348 - `server_tool_use: BetaServerToolUsage or null`
1178412349
1178512350 The number of server tool requests.
from line 12353
1178812353
1178912354 The number of web fetch tool requests.
1179012355
12356 default: 0, minimum: 0
12357
1179112358 - `web_search_requests: number`
1179212359
1179312360 The number of web search tool requests.
1179412361
12362 default: 0, minimum: 0
12363
1179512364 - `service_tier: "standard" or "priority" or "batch" or null`
1179612365
1179712366 If the request used the priority, standard, or batch tier.
from line 12381
1181212381
1181312382 - `type: "succeeded"`
1181412383
11815 - `"succeeded"`
12384 default: succeeded
1181612385
api/beta/messages/batches/cancel Changed · +34 / -19 lines
# Cancel a Message Batch ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Cancel a Message Batch ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Cancel a Message Batch
3url: https://platform.claude.com/docs/en/api/beta/messages/batches/cancel
4---
1# Cancel a Message Batch
52
6## Cancel a Message Batch
3**POST** `/v1/messages/batches/{message_batch_id}/cancel`
74
8**post** `/v1/messages/batches/{message_batch_id}/cancel`
9
105Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.
116
127The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible.
from line 8
138
149Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
1510
16### Path Parameters
11## Path parameters
1712
1813- `message_batch_id: string`
1914
2015 ID of the Message Batch.
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
100### Returns
95## Returns
10196
102- `BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }`
97- `BetaMessageBatch object`
10398
10499 - `id: string`
105100
from line 106
111106
112107 RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
113108
109 format: date-time
110
114111 - `cancel_initiated_at: string or null`
115112
116113 RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
117114
115 format: date-time
116
118117 - `created_at: string`
119118
120119 RFC 3339 datetime string representing the time at which the Message Batch was created.
121120
121 format: date-time
122
122123 - `ended_at: string or null`
123124
124125 RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
from line 126
125126
126127 Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
127128
129 format: date-time
130
128131 - `expires_at: string`
129132
130133 RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
131134
135 format: date-time
136
132137 - `processing_status: "in_progress" or "canceling" or "ended"`
133138
134139 Processing status of the Message Batch.
from line 156
151156
152157 This is zero until processing of the entire Message Batch has ended.
153158
159 default: 0
160
154161 - `errored: number`
155162
156163 Number of requests in the Message Batch that encountered an error.
from line 164
157164
158165 This is zero until processing of the entire Message Batch has ended.
159166
167 default: 0
168
160169 - `expired: number`
161170
162171 Number of requests in the Message Batch that have expired.
from line 172
163172
164173 This is zero until processing of the entire Message Batch has ended.
165174
175 default: 0
176
166177 - `processing: number`
167178
168179 Number of requests in the Message Batch that are processing.
169180
181 default: 0
182
170183 - `succeeded: number`
171184
172185 Number of requests in the Message Batch that have completed successfully.
from line 186
173186
174187 This is zero until processing of the entire Message Batch has ended.
175188
189 default: 0
190
176191 - `results_url: string or null`
177192
178193 URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
from line 200
185200
186201 For Message Batches, this is always `"message_batch"`.
187202
188 - `"message_batch"`
203 default: message_batch
189204
190### Example
205## Example
191206
192```http
207```bash
193208curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
194209 -X POST \
195210 -H 'anthropic-version: 2023-06-01' \
from line 212
197212 -H "X-Api-Key: $ANTHROPIC_API_KEY"
198213```
199214
200#### Response
215### Response (200)
201216
202217```json
203218{
api/beta/messages/batches/create Changed · +463 / -514 lines
# Create a Message Batch ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create a Message Batch ### 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: Create a Message Batch
3url: https://platform.claude.com/docs/en/api/beta/messages/batches/create
4---
5
6## Create a Message Batch
7
8**post** `/v1/messages/batches`
1# Create a Message Batch
2
3**POST** `/v1/messages/batches`
94
105Send a batch of Message creation requests.
116
from line 8
138
149Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 90
9590
9691 The user profile ID to attribute the requests in this batch to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header. Applies to every request in the batch; an individual request whose `user_profile_id` body field conflicts with this header is errored.
9792
98### Body Parameters
99
100- `requests: array of object { custom_id, params }`
93## Body parameters
94
95- `requests: array of object`
10196
10297 List of requests for prompt completion. Each is an individual request to create a Message.
10398
99 maxItems: 100000, minItems: 1
100
104101 - `custom_id: string`
105102
106103 Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.
107104
108105 Must be unique for each request within the Message Batch.
109106
110 - `params: object { max_tokens, messages, model, 22 more }`
107 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,64}$
108
109 - `params: object`
111110
112111 Messages API creation parameters for the individual request.
113112
from line 121
122121 Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.
123122
124123 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
124
125 minimum: 0
125126
126127 - `messages: array of BetaMessageParam`
127128
from line 181
180181
181182 - `array of BetaContentBlockParam`
182183
183 - `BetaTextBlockParam object { text, type, cache_control, citations }`
184 - `BetaTextBlockParam object`
184185
185186 - `text: string`
186187
188 minLength: 1
189
187190 - `type: "text"`
188191
189 - `"text"`
190
191192 - `cache_control: optional BetaCacheControlEphemeral or null`
192193
193194 Create a cache control breakpoint at this content block.
194195
195196 - `type: "ephemeral"`
196
197 - `"ephemeral"`
198197
199198 - `ttl: optional "5m" or "1h"`
200199
from line 212
213212
214213 - `citations: optional array of BetaTextCitationParam or null`
215214
216 - `BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
215 - `BetaCitationCharLocationParam object`
217216
218217 - `cited_text: string`
219218
220219 - `document_index: number`
221220
221 minimum: 0
222
222223 - `document_title: string or null`
223224
225 maxLength: 500, minLength: 1
226
224227 - `end_char_index: number`
225228
226229 - `start_char_index: number`
227230
231 minimum: 0
232
228233 - `type: "char_location"`
229234
230 - `"char_location"`
231
232 - `BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
235 - `BetaCitationPageLocationParam object`
233236
234237 - `cited_text: string`
235238
236239 - `document_index: number`
237240
241 minimum: 0
242
238243 - `document_title: string or null`
239244
245 maxLength: 500, minLength: 1
246
240247 - `end_page_number: number`
241248
242249 - `start_page_number: number`
243250
251 minimum: 1
252
244253 - `type: "page_location"`
245254
246 - `"page_location"`
247
248 - `BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
255 - `BetaCitationContentBlockLocationParam object`
249256
250257 - `cited_text: string`
251258
from line 262
255262
256263 - `document_index: number`
257264
265 minimum: 0
266
258267 - `document_title: string or null`
259268
269 maxLength: 500, minLength: 1
270
260271 - `end_block_index: number`
261272
262273 Exclusive 0-based end index of the cited block range in the source's `content` array.
from line 278
267278
268279 0-based index of the first cited block in the source's `content` array.
269280
281 minimum: 0
282
270283 - `type: "content_block_location"`
271284
272 - `"content_block_location"`
273
274 - `BetaCitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
285 - `BetaCitationWebSearchResultLocationParam object`
275286
276287 - `cited_text: string`
277288
from line 290
279290
280291 - `title: string or null`
281292
293 maxLength: 512, minLength: 1
294
282295 - `type: "web_search_result_location"`
283296
284 - `"web_search_result_location"`
285
286297 - `url: string`
287298
288 - `BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
299 minLength: 1
300
301 - `BetaCitationSearchResultLocationParam object`
289302
290303 - `cited_text: string`
291304
from line 318
305318
306319 Counted separately from `document_index`; server-side web search results are not included in this count.
307320
321 minimum: 0
322
308323 - `source: string`
309324
310325 - `start_block_index: number`
311326
312327 0-based index of the first cited block in the source's `content` array.
313328
329 minimum: 0
330
314331 - `title: string or null`
315332
316333 - `type: "search_result_location"`
317334
318 - `"search_result_location"`
319
320 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
335 - `BetaImageBlockParam object`
321336
322337 - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource`
323338
324 - `BetaBase64ImageSource object { data, media_type, type }`
339 - `BetaBase64ImageSource object`
325340
326341 - `data: string`
327342
343 format: byte
344
328345 - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
329346
330347 - `"image/jpeg"`
from line 354
337354
338355 - `type: "base64"`
339356
340 - `"base64"`
341
342 - `BetaURLImageSource object { type, url }`
357 - `BetaURLImageSource object`
343358
344359 - `type: "url"`
345360
346 - `"url"`
347
348361 - `url: string`
349362
350 - `BetaFileImageSource object { file_id, type }`
363 - `BetaFileImageSource object`
351364
352365 - `file_id: string`
353366
354367 - `type: "file"`
355368
356 - `"file"`
357
358369 - `type: "image"`
359370
360 - `"image"`
361
362371 - `cache_control: optional BetaCacheControlEphemeral or null`
363372
364373 Create a cache control breakpoint at this content block.
from line 384
375384
376385 - `"error"`
377386
378 - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }`
387 - `BetaRequestDocumentBlock object`
379388
380389 - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more`
381390
382 - `BetaBase64PDFSource object { data, media_type, type }`
391 - `BetaBase64PDFSource object`
383392
384393 - `data: string`
385394
395 format: byte
396
386397 - `media_type: "application/pdf"`
387398
388 - `"application/pdf"`
389
390399 - `type: "base64"`
391400
392 - `"base64"`
393
394 - `BetaPlainTextSource object { data, media_type, type }`
401 - `BetaPlainTextSource object`
395402
396403 - `data: string`
397404
398405 - `media_type: "text/plain"`
399406
400 - `"text/plain"`
401
402407 - `type: "text"`
403408
404 - `"text"`
405
406 - `BetaContentBlockSource object { content, type }`
409 - `BetaContentBlockSource object`
407410
408411 - `content: string or array of BetaContentBlockSourceContent`
409412
from line 414
411414
412415 - `BetaContentBlockSourceContent = array of BetaContentBlockSourceContent`
413416
414 - `BetaTextBlockParam object { text, type, cache_control, citations }`
415
416 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
417 - `BetaTextBlockParam object`
418
419 - `BetaImageBlockParam object`
417420
418421 - `type: "content"`
419422
420 - `"content"`
421
422 - `BetaURLPDFSource object { type, url }`
423 - `BetaURLPDFSource object`
423424
424425 - `type: "url"`
425426
426 - `"url"`
427
428427 - `url: string`
429428
430 - `BetaFileDocumentSource object { file_id, type }`
429 - `BetaFileDocumentSource object`
431430
432431 - `file_id: string`
433432
434433 - `type: "file"`
435434
436 - `"file"`
437
438435 - `type: "document"`
439436
440 - `"document"`
441
442437 - `cache_control: optional BetaCacheControlEphemeral or null`
443438
444439 Create a cache control breakpoint at this content block.
from line 444
449444
450445 - `context: optional string or null`
451446
447 minLength: 1
448
452449 - `title: optional string or null`
453450
454 - `BetaSearchResultBlockParam object { content, source, title, 3 more }`
451 maxLength: 500, minLength: 1
452
453 - `BetaSearchResultBlockParam object`
455454
456455 - `content: array of BetaTextBlockParam`
457456
458457 - `text: string`
459458
459 minLength: 1
460
460461 - `type: "text"`
461462
462463 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 472
471472
472473 - `type: "search_result"`
473474
474 - `"search_result"`
475
476475 - `cache_control: optional BetaCacheControlEphemeral or null`
477476
478477 Create a cache control breakpoint at this content block.
479478
480479 - `citations: optional BetaCitationsConfigParam`
481480
482 - `BetaThinkingBlockParam object { signature, thinking, type }`
481 - `BetaThinkingBlockParam object`
483482
484483 - `signature: string`
485484
from line 492
493492
494493 - `type: "thinking"`
495494
496 - `"thinking"`
497
498 - `BetaRedactedThinkingBlockParam object { data, type }`
495 - `BetaRedactedThinkingBlockParam object`
499496
500497 - `data: string`
501498
from line 500
503500
504501 - `type: "redacted_thinking"`
505502
506 - `"redacted_thinking"`
507
508 - `BetaToolUseBlockParam object { id, input, name, 4 more }`
503 - `BetaToolUseBlockParam object`
509504
510505 - `id: string`
511506
507 pattern: ^[a-zA-Z0-9_-]+$
508
512509 - `input: map[unknown]`
513510
514511 - `name: string`
515512
513 maxLength: 200, minLength: 1
514
516515 - `type: "tool_use"`
517516
518 - `"tool_use"`
519
520517 - `cache_control: optional BetaCacheControlEphemeral or null`
521518
522519 Create a cache control breakpoint at this content block.
from line 522
525522
526523 Tool invocation directly from the model.
527524
528 - `BetaDirectCaller object { type }`
525 - `BetaDirectCaller object`
529526
530527 Tool invocation directly from the model.
531528
532529 - `type: "direct"`
533530
534 - `"direct"`
535
536 - `BetaServerToolCaller object { tool_id, type }`
531 - `BetaServerToolCaller object`
537532
538533 Tool invocation generated by a server-side tool.
539534
540535 - `tool_id: string`
541536
537 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
538
542539 - `type: "code_execution_20250825"`
543540
544 - `"code_execution_20250825"`
545
546 - `BetaServerToolCaller20260120 object { tool_id, type }`
541 - `BetaServerToolCaller20260120 object`
547542
548543 - `tool_id: string`
549544
545 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
546
550547 - `type: "code_execution_20260120"`
551548
552 - `"code_execution_20260120"`
553
554549 - `toolset_name: optional string or null`
555550
556551 For a toolset member tool_use, the toolset family this member belongs to.
557552
558 - `BetaToolResultBlockParam object { tool_use_id, type, cache_control, 3 more }`
553 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
554
555 - `BetaToolResultBlockParam object`
559556
560557 - `tool_use_id: string`
561558
559 pattern: ^[a-zA-Z0-9_-]+$
560
562561 - `type: "tool_result"`
563562
564 - `"tool_result"`
565
566563 - `cache_control: optional BetaCacheControlEphemeral or null`
567564
568565 Create a cache control breakpoint at this content block.
from line 570
573570
574571 - `array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 3 more`
575572
576 - `BetaTextBlockParam object { text, type, cache_control, citations }`
577
578 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
579
580 - `BetaSearchResultBlockParam object { content, source, title, 3 more }`
581
582 - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }`
583
584 - `BetaToolReferenceBlockParam object { tool_name, type, cache_control }`
573 - `BetaTextBlockParam object`
574
575 - `BetaImageBlockParam object`
576
577 - `BetaSearchResultBlockParam object`
578
579 - `BetaRequestDocumentBlock object`
580
581 - `BetaToolReferenceBlockParam object`
585582
586583 Tool reference block that can be included in tool_result content.
587584
588585 - `tool_name: string`
589586
587 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
588
590589 - `type: "tool_reference"`
591590
592 - `"tool_reference"`
593
594591 - `cache_control: optional BetaCacheControlEphemeral or null`
595592
596593 Create a cache control breakpoint at this content block.
597594
598 - `BetaBrowserStateBlockParam object { tabs, type, cache_control, state_changes }`
595 - `BetaBrowserStateBlockParam object`
599596
600597 The caller's browser state after a browser toolset member call —
601598 the full inventory of open tabs, which tab is active, and any side
from line 606
609606
610607 All tabs open in the browser after this call — the full inventory, not a delta. May be empty. Whenever non-empty, exactly one entry carries `active: true`.
611608
609 maxItems: 100
610
612611 - `tab_id: string`
613612
614613 The caller-assigned identifier for this tab, unique within the inventory.
615614
615 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
616
616617 - `title: string`
617618
618619 The title of the page the tab is showing. May be empty.
619620
621 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
622
620623 - `url: string`
621624
622625 The URL of the page the tab is showing. May be empty.
623626
627 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
628
624629 - `active: optional boolean`
625630
626631 Whether this tab is the active tab after this call. Whenever `tabs` is non-empty, exactly one entry is marked `active: true`.
627632
628633 - `type: "browser_state"`
629634
630 - `"browser_state"`
631
632635 - `cache_control: optional BetaCacheControlEphemeral or null`
633636
634637 Create a cache control breakpoint at this content block.
from line 640
637640
638641 Tabs opened and download state changes during this call. "Nothing to report" is expressed by omitting the field, never by an empty list.
639642
640 - `BetaBrowserStateChangeTabOpened object { tab_id, type }`
643 maxItems: 200, minItems: 1
644
645 - `BetaBrowserStateChangeTabOpened object`
641646
642647 A tab this call's execution opened that remains open at its end —
643648 the creation delta of the `tabs` inventory, not an event log.
from line 656
651656
652657 The `tab_id` of the opened tab, present in `tabs`.
653658
659 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
660
654661 - `type: "tab_opened"`
655662
656 - `"tab_opened"`
657
658 - `BetaBrowserStateChangeDownloadStarted object { download_id, type, url }`
663 - `BetaBrowserStateChangeDownloadStarted object`
659664
660665 A file download that started during this call.
661666
from line 668
663668
664669 The caller-assigned identifier for this download, stable across the state changes reporting it.
665670
671 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
672
666673 - `type: "download_started"`
667674
668 - `"download_started"`
669
670675 - `url: string`
671676
672677 The final post-redirect URL the download was served from.
673678
674 - `BetaBrowserStateChangeDownloadCompleted object { download_id, type, url, 2 more }`
679 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
680
681 - `BetaBrowserStateChangeDownloadCompleted object`
675682
676683 A file download that finished during this call, reported with the
677684 same `download_id` as its `download_started` — or without a prior
from line 689
682689
683690 The caller-assigned identifier for this download, stable across the state changes reporting it.
684691
692 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
693
685694 - `type: "download_completed"`
686695
687 - `"download_completed"`
688
689696 - `url: string`
690697
691698 The final post-redirect URL the download was served from.
692699
700 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
701
693702 - `path: optional string or null`
694703
695704 Where the executor saved the file, on the executor's filesystem. Only included when another tool in the same environment can read the file at that path.
696705
706 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096
707
697708 - `size_bytes: optional number or null`
698709
699710 The completed download's size.
700711
701 - `BetaBrowserStateChangeDownloadFailed object { download_id, type, url, error }`
712 minimum: 0
713
714 - `BetaBrowserStateChangeDownloadFailed object`
702715
703716 A file download that failed — or was cancelled — during this call.
704717
from line 719
706719
707720 The caller-assigned identifier for this download, stable across the state changes reporting it.
708721
722 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
723
709724 - `type: "download_failed"`
710725
711 - `"download_failed"`
712
713726 - `url: string`
714727
715728 The final post-redirect URL the download was served from.
716729
730 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
731
717732 - `error: optional string or null`
718733
719734 The failure or cancellation detail, when known.
720735
736 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096
737
721738 - `is_error: optional boolean`
722739
723740 - `toolset_name: optional string or null`
724741
725742 For a toolset member tool_result, the toolset family of the paired tool_use.
726743
727 - `BetaServerToolUseBlockParam object { id, input, name, 3 more }`
744 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
745
746 - `BetaServerToolUseBlockParam object`
728747
729748 - `id: string`
730749
750 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
751
731752 - `input: map[unknown]`
732753
733754 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 771
750771
751772 - `type: "server_tool_use"`
752773
753 - `"server_tool_use"`
754
755774 - `cache_control: optional BetaCacheControlEphemeral or null`
756775
757776 Create a cache control breakpoint at this content block.
from line 779
760779
761780 Tool invocation directly from the model.
762781
763 - `BetaDirectCaller object { type }`
782 - `BetaDirectCaller object`
764783
765784 Tool invocation directly from the model.
766785
767 - `BetaServerToolCaller object { tool_id, type }`
786 - `BetaServerToolCaller object`
768787
769788 Tool invocation generated by a server-side tool.
770789
771 - `BetaServerToolCaller20260120 object { tool_id, type }`
772
773 - `BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }`
790 - `BetaServerToolCaller20260120 object`
791
792 - `BetaWebSearchToolResultBlockParam object`
774793
775794 - `content: BetaWebSearchToolResultBlockParamContent`
776795
from line 801
782801
783802 - `type: "web_search_result"`
784803
785 - `"web_search_result"`
786
787804 - `url: string`
788805
789806 - `page_age: optional string or null`
790807
791 - `BetaWebSearchToolRequestError object { error_code, type }`
808 - `BetaWebSearchToolRequestError object`
792809
793810 - `error_code: BetaWebSearchToolResultErrorCode`
794811
from line 823
806823
807824 - `type: "web_search_tool_result_error"`
808825
809 - `"web_search_tool_result_error"`
810
811826 - `tool_use_id: string`
812827
828 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
829
813830 - `type: "web_search_tool_result"`
814831
815 - `"web_search_tool_result"`
816
817832 - `cache_control: optional BetaCacheControlEphemeral or null`
818833
819834 Create a cache control breakpoint at this content block.
from line 837
822837
823838 Tool invocation directly from the model.
824839
825 - `BetaDirectCaller object { type }`
840 - `BetaDirectCaller object`
826841
827842 Tool invocation directly from the model.
828843
829 - `BetaServerToolCaller object { tool_id, type }`
844 - `BetaServerToolCaller object`
830845
831846 Tool invocation generated by a server-side tool.
832847
833 - `BetaServerToolCaller20260120 object { tool_id, type }`
834
835 - `BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }`
848 - `BetaServerToolCaller20260120 object`
849
850 - `BetaWebFetchToolResultBlockParam object`
836851
837852 - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam`
838853
839 - `BetaWebFetchToolResultErrorBlockParam object { error_code, type }`
854 - `BetaWebFetchToolResultErrorBlockParam object`
840855
841856 - `error_code: BetaWebFetchToolResultErrorCode`
842857
from line 875
860875
861876 - `type: "web_fetch_tool_result_error"`
862877
863 - `"web_fetch_tool_result_error"`
864
865 - `BetaWebFetchBlockParam object { content, type, url, retrieved_at }`
878 - `BetaWebFetchBlockParam object`
866879
867880 - `content: BetaRequestDocumentBlock`
868881
869882 - `type: "web_fetch_result"`
870883
871 - `"web_fetch_result"`
872
873884 - `url: string`
874885
875886 Fetched content URL
from line 891
880891
881892 - `tool_use_id: string`
882893
894 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
895
883896 - `type: "web_fetch_tool_result"`
884897
885 - `"web_fetch_tool_result"`
886
887898 - `cache_control: optional BetaCacheControlEphemeral or null`
888899
889900 Create a cache control breakpoint at this content block.
from line 903
892903
893904 Tool invocation directly from the model.
894905
895 - `BetaDirectCaller object { type }`
906 - `BetaDirectCaller object`
896907
897908 Tool invocation directly from the model.
898909
899 - `BetaServerToolCaller object { tool_id, type }`
910 - `BetaServerToolCaller object`
900911
901912 Tool invocation generated by a server-side tool.
902913
903 - `BetaServerToolCaller20260120 object { tool_id, type }`
904
905 - `BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }`
914 - `BetaServerToolCaller20260120 object`
915
916 - `BetaAdvisorToolResultBlockParam object`
906917
907918 - `content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam`
908919
909 - `BetaAdvisorToolResultErrorParam object { error_code, type }`
920 - `BetaAdvisorToolResultErrorParam object`
910921
911922 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
912923
from line 937
926937
927938 - `type: "advisor_tool_result_error"`
928939
929 - `"advisor_tool_result_error"`
930
931 - `BetaAdvisorResultBlockParam object { text, type, stop_reason }`
940 - `BetaAdvisorResultBlockParam object`
932941
933942 - `text: string`
934943
935944 - `type: "advisor_result"`
936945
937 - `"advisor_result"`
938
939946 - `stop_reason: optional string or null`
940947
941 - `BetaAdvisorRedactedResultBlockParam object { encrypted_content, type, stop_reason }`
948 - `BetaAdvisorRedactedResultBlockParam object`
942949
943950 - `encrypted_content: string`
944951
from line 953
946953
947954 - `type: "advisor_redacted_result"`
948955
949 - `"advisor_redacted_result"`
950
951956 - `stop_reason: optional string or null`
952957
953958 - `tool_use_id: string`
954959
960 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
961
955962 - `type: "advisor_tool_result"`
956963
957 - `"advisor_tool_result"`
958
959964 - `cache_control: optional BetaCacheControlEphemeral or null`
960965
961966 Create a cache control breakpoint at this content block.
962967
963 - `BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
968 - `BetaCodeExecutionToolResultBlockParam object`
964969
965970 - `content: BetaCodeExecutionToolResultBlockParamContent`
966971
967972 Code execution result with encrypted stdout for PFC + web_search results.
968973
969 - `BetaCodeExecutionToolResultErrorParam object { error_code, type }`
974 - `BetaCodeExecutionToolResultErrorParam object`
970975
971976 - `error_code: BetaCodeExecutionToolResultErrorCode`
972977
from line 985
980985
981986 - `type: "code_execution_tool_result_error"`
982987
983 - `"code_execution_tool_result_error"`
984
985 - `BetaCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }`
988 - `BetaCodeExecutionResultBlockParam object`
986989
987990 - `content: array of BetaCodeExecutionOutputBlockParam`
988991
from line 993
990993
991994 - `type: "code_execution_output"`
992995
993 - `"code_execution_output"`
994
995996 - `return_code: number`
996997
997998 - `stderr: string`
from line 1001
10001001
10011002 - `type: "code_execution_result"`
10021003
1003 - `"code_execution_result"`
1004
1005 - `BetaEncryptedCodeExecutionResultBlockParam object { content, encrypted_stdout, return_code, 2 more }`
1004 - `BetaEncryptedCodeExecutionResultBlockParam object`
10061005
10071006 Code execution result with encrypted stdout for PFC + web_search results.
10081007
from line 1019
10201019
10211020 - `type: "encrypted_code_execution_result"`
10221021
1023 - `"encrypted_code_execution_result"`
1024
10251022 - `tool_use_id: string`
10261023
1024 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1025
10271026 - `type: "code_execution_tool_result"`
10281027
1029 - `"code_execution_tool_result"`
1030
10311028 - `cache_control: optional BetaCacheControlEphemeral or null`
10321029
10331030 Create a cache control breakpoint at this content block.
10341031
1035 - `BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1032 - `BetaBashCodeExecutionToolResultBlockParam object`
10361033
10371034 - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam`
10381035
1039 - `BetaBashCodeExecutionToolResultErrorParam object { error_code, type }`
1036 - `BetaBashCodeExecutionToolResultErrorParam object`
10401037
10411038 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
10421039
from line 1049
10521049
10531050 - `type: "bash_code_execution_tool_result_error"`
10541051
1055 - `"bash_code_execution_tool_result_error"`
1056
1057 - `BetaBashCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }`
1052 - `BetaBashCodeExecutionResultBlockParam object`
10581053
10591054 - `content: array of BetaBashCodeExecutionOutputBlockParam`
10601055
from line 1057
10621057
10631058 - `type: "bash_code_execution_output"`
10641059
1065 - `"bash_code_execution_output"`
1066
10671060 - `return_code: number`
10681061
10691062 - `stderr: string`
from line 1065
10721065
10731066 - `type: "bash_code_execution_result"`
10741067
1075 - `"bash_code_execution_result"`
1076
10771068 - `tool_use_id: string`
10781069
1070 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1071
10791072 - `type: "bash_code_execution_tool_result"`
10801073
1081 - `"bash_code_execution_tool_result"`
1082
10831074 - `cache_control: optional BetaCacheControlEphemeral or null`
10841075
10851076 Create a cache control breakpoint at this content block.
10861077
1087 - `BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1078 - `BetaTextEditorCodeExecutionToolResultBlockParam object`
10881079
10891080 - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam`
10901081
1091 - `BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }`
1082 - `BetaTextEditorCodeExecutionToolResultErrorParam object`
10921083
10931084 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
10941085
from line 1095
11041095
11051096 - `type: "text_editor_code_execution_tool_result_error"`
11061097
1107 - `"text_editor_code_execution_tool_result_error"`
1108
11091098 - `error_message: optional string or null`
11101099
1111 - `BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }`
1100 - `BetaTextEditorCodeExecutionViewResultBlockParam object`
11121101
11131102 - `content: string`
11141103
from line 1111
11221111
11231112 - `type: "text_editor_code_execution_view_result"`
11241113
1125 - `"text_editor_code_execution_view_result"`
1126
11271114 - `num_lines: optional number or null`
11281115
11291116 - `start_line: optional number or null`
11301117
11311118 - `total_lines: optional number or null`
11321119
1133 - `BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }`
1120 - `BetaTextEditorCodeExecutionCreateResultBlockParam object`
11341121
11351122 - `is_file_update: boolean`
11361123
11371124 - `type: "text_editor_code_execution_create_result"`
11381125
1139 - `"text_editor_code_execution_create_result"`
1140
1141 - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }`
1126 - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object`
11421127
11431128 - `type: "text_editor_code_execution_str_replace_result"`
11441129
1145 - `"text_editor_code_execution_str_replace_result"`
1146
11471130 - `lines: optional array of string or null`
11481131
11491132 - `new_lines: optional number or null`
from line 1139
11561139
11571140 - `tool_use_id: string`
11581141
1142 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1143
11591144 - `type: "text_editor_code_execution_tool_result"`
11601145
1161 - `"text_editor_code_execution_tool_result"`
1162
11631146 - `cache_control: optional BetaCacheControlEphemeral or null`
11641147
11651148 Create a cache control breakpoint at this content block.
11661149
1167 - `BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1150 - `BetaToolSearchToolResultBlockParam object`
11681151
11691152 - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam`
11701153
1171 - `BetaToolSearchToolResultErrorParam object { error_code, type, error_message }`
1154 - `BetaToolSearchToolResultErrorParam object`
11721155
11731156 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
11741157
from line 1165
11821165
11831166 - `type: "tool_search_tool_result_error"`
11841167
1185 - `"tool_search_tool_result_error"`
1186
11871168 - `error_message: optional string or null`
11881169
1189 - `BetaToolSearchToolSearchResultBlockParam object { tool_references, type }`
1170 - `BetaToolSearchToolSearchResultBlockParam object`
11901171
11911172 - `tool_references: array of BetaToolReferenceBlockParam`
11921173
11931174 - `tool_name: string`
11941175
1176 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
1177
11951178 - `type: "tool_reference"`
11961179
11971180 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1183
12001183
12011184 - `type: "tool_search_tool_search_result"`
12021185
1203 - `"tool_search_tool_search_result"`
1204
12051186 - `tool_use_id: string`
12061187
1188 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1189
12071190 - `type: "tool_search_tool_result"`
12081191
1209 - `"tool_search_tool_result"`
1210
12111192 - `cache_control: optional BetaCacheControlEphemeral or null`
12121193
12131194 Create a cache control breakpoint at this content block.
12141195
1215 - `BetaMCPToolUseBlockParam object { id, input, name, 3 more }`
1196 - `BetaMCPToolUseBlockParam object`
12161197
12171198 - `id: string`
12181199
1200 pattern: ^[a-zA-Z0-9_-]+$
1201
12191202 - `input: map[unknown]`
12201203
12211204 - `name: string`
from line 1209
12261209
12271210 - `type: "mcp_tool_use"`
12281211
1229 - `"mcp_tool_use"`
1230
12311212 - `cache_control: optional BetaCacheControlEphemeral or null`
12321213
12331214 Create a cache control breakpoint at this content block.
12341215
1235 - `BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }`
1216 - `BetaRequestMCPToolResultBlockParam object`
12361217
12371218 - `tool_use_id: string`
12381219
1220 pattern: ^[a-zA-Z0-9_-]+$
1221
12391222 - `type: "mcp_tool_result"`
12401223
1241 - `"mcp_tool_result"`
1242
12431224 - `cache_control: optional BetaCacheControlEphemeral or null`
12441225
12451226 Create a cache control breakpoint at this content block.
from line 1233
12521233
12531234 - `text: string`
12541235
1236 minLength: 1
1237
12551238 - `type: "text"`
12561239
12571240 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1245
12621245
12631246 - `is_error: optional boolean`
12641247
1265 - `BetaContainerUploadBlockParam object { file_id, type, cache_control }`
1248 - `BetaContainerUploadBlockParam object`
12661249
12671250 A content block that represents a file to be uploaded to the container
12681251 Files uploaded via this block will be available in the container's input directory.
from line 1254
12711254
12721255 - `type: "container_upload"`
12731256
1274 - `"container_upload"`
1275
12761257 - `cache_control: optional BetaCacheControlEphemeral or null`
12771258
12781259 Create a cache control breakpoint at this content block.
12791260
1280 - `BetaCompactionBlockParam object { type, cache_control, content, encrypted_content }`
1261 - `BetaCompactionBlockParam object`
12811262
12821263 A compaction block containing summary of previous context.
12831264
from line 1270
12891270
12901271 - `type: "compaction"`
12911272
1292 - `"compaction"`
1293
12941273 - `cache_control: optional BetaCacheControlEphemeral or null`
12951274
12961275 Create a cache control breakpoint at this content block.
from line 1282
13031282
13041283 Opaque metadata from prior compaction, to be round-tripped verbatim
13051284
1306 - `BetaRequestToolAdditionBlock object { tool, type, cache_control }`
1285 - `BetaRequestToolAdditionBlock object`
13071286
13081287 Mid-conversation directive to surface a declared tool.
13091288
from line 1297
13181297 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13191298 `mcp_toolset_reference` for those.
13201299
1321 - `BetaToolChangeToolReference object { name, type }`
1300 - `BetaToolChangeToolReference object`
13221301
13231302 Reference to a single tool the caller declared directly in
13241303 `tools[]`. Does not accept the composed `{server}_{name}` form the
from line 1306
13271306
13281307 - `name: string`
13291308
1309 pattern: ^[a-zA-Z0-9_-]{1,128}$
1310
13301311 - `type: "tool_reference"`
13311312
1332 - `"tool_reference"`
1333
1334 - `BetaToolChangeMCPToolReference object { name, server_name, type }`
1313 - `BetaToolChangeMCPToolReference object`
13351314
13361315 Reference to a single MCP tool by its server and remote name — the
13371316 same `server_name`/`name` pair `mcp_tool_use` carries.
from line 1321
13421321
13431322 - `type: "mcp_tool_reference"`
13441323
1345 - `"mcp_tool_reference"`
1346
1347 - `BetaToolChangeMCPToolsetReference object { server_name, type }`
1324 - `BetaToolChangeMCPToolsetReference object`
13481325
13491326 Reference to every tool in the named MCP server's toolset.
13501327
from line 1329
13521329
13531330 - `type: "mcp_toolset_reference"`
13541331
1355 - `"mcp_toolset_reference"`
1356
13571332 - `type: "tool_addition"`
13581333
1359 - `"tool_addition"`
1360
13611334 - `cache_control: optional BetaCacheControlEphemeral or null`
13621335
13631336 Create a cache control breakpoint at this content block.
13641337
1365 - `BetaRequestToolRemovalBlock object { tool, type, cache_control }`
1338 - `BetaRequestToolRemovalBlock object`
13661339
13671340 Mid-conversation directive to withdraw a tool.
13681341
from line 1350
13771350 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13781351 `mcp_toolset_reference` for those.
13791352
1380 - `BetaToolChangeToolReference object { name, type }`
1353 - `BetaToolChangeToolReference object`
13811354
13821355 Reference to a single tool the caller declared directly in
13831356 `tools[]`. Does not accept the composed `{server}_{name}` form the
13841357 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13851358 `mcp_toolset_reference` for those.
13861359
1387 - `BetaToolChangeMCPToolReference object { name, server_name, type }`
1360 - `BetaToolChangeMCPToolReference object`
13881361
13891362 Reference to a single MCP tool by its server and remote name — the
13901363 same `server_name`/`name` pair `mcp_tool_use` carries.
13911364
1392 - `BetaToolChangeMCPToolsetReference object { server_name, type }`
1365 - `BetaToolChangeMCPToolsetReference object`
13931366
13941367 Reference to every tool in the named MCP server's toolset.
13951368
13961369 - `type: "tool_removal"`
13971370
1398 - `"tool_removal"`
1399
14001371 - `cache_control: optional BetaCacheControlEphemeral or null`
14011372
14021373 Create a cache control breakpoint at this content block.
14031374
1404 - `BetaFallbackBlockParam object { from, to, type, trigger }`
1375 - `BetaFallbackBlockParam object`
14051376
14061377 A `fallback` block echoed back from a prior response.
14071378
from line 1472
15011472
15021473 - `type: "fallback"`
15031474
1504 - `"fallback"`
1505
15061475 - `trigger: optional unknown`
15071476
15081477 The response block's `trigger`, echoed verbatim. Accepted and ignored by the server; any object or `null` is allowed.
from line 1498
15291498
15301499 Container identifier for reuse across requests.
15311500
1532 - `BetaContainerParams object { id, skills }`
1501 - `BetaContainerParams object`
15331502
15341503 Container parameters with skills to be loaded.
15351504
from line 1510
15411510
15421511 List of skills to load in the container
15431512
1513 maxItems: 20
1514
15441515 - `skill_id: string`
15451516
15461517 Skill ID
15471518
1519 maxLength: 64, minLength: 1
1520
15481521 - `type: "anthropic" or "custom"`
15491522
15501523 Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
from line 1530
15571530
15581531 Skill version or 'latest' for most recent version
15591532
1533 maxLength: 64, minLength: 1
1534
15601535 - `string`
15611536
15621537 - `context_management: optional BetaContextManagementConfig or null`
from line 1544
15691544
15701545 List of context management edits to apply
15711546
1572 - `BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }`
1547 minItems: 0
1548
1549 - `BetaClearToolUses20250919Edit object`
15731550
15741551 - `type: "clear_tool_uses_20250919"`
15751552
1576 - `"clear_tool_uses_20250919"`
1577
15781553 - `clear_at_least: optional BetaInputTokensClearAtLeast or null`
15791554
15801555 Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.
15811556
15821557 - `type: "input_tokens"`
15831558
1584 - `"input_tokens"`
1585
15861559 - `value: number`
15871560
1561 minimum: 0
1562
15881563 - `clear_tool_inputs: optional boolean or array of string or null`
15891564
15901565 Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)
from line 1578
16031578
16041579 - `type: "tool_uses"`
16051580
1606 - `"tool_uses"`
1607
16081581 - `value: number`
16091582
1583 minimum: 0
1584
16101585 - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger`
16111586
16121587 Condition that triggers the context management strategy
16131588
1614 - `BetaInputTokensTrigger object { type, value }`
1589 - `BetaInputTokensTrigger object`
16151590
16161591 - `type: "input_tokens"`
16171592
1618 - `"input_tokens"`
1619
16201593 - `value: number`
16211594
1622 - `BetaToolUsesTrigger object { type, value }`
1595 minimum: 1
1596
1597 - `BetaToolUsesTrigger object`
16231598
16241599 - `type: "tool_uses"`
16251600
1626 - `"tool_uses"`
1627
16281601 - `value: number`
16291602
1630 - `BetaClearThinking20251015Edit object { type, keep }`
1603 minimum: 1
1604
1605 - `BetaClearThinking20251015Edit object`
16311606
16321607 - `type: "clear_thinking_20251015"`
16331608
1634 - `"clear_thinking_20251015"`
1635
16361609 - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"`
16371610
16381611 Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.
16391612
1640 - `BetaThinkingTurns object { type, value }`
1613 - `BetaThinkingTurns object`
16411614
16421615 - `type: "thinking_turns"`
16431616
1644 - `"thinking_turns"`
1645
16461617 - `value: number`
16471618
1648 - `BetaAllThinkingTurns object { type }`
1619 minimum: 1
1620
1621 - `BetaAllThinkingTurns object`
16491622
16501623 - `type: "all"`
16511624
1652 - `"all"`
1653
16541625 - `"all"`
16551626
1656 - `"all"`
1657
1658 - `BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }`
1627 - `BetaCompact20260112Edit object`
16591628
16601629 Automatically compact older context when reaching the configured trigger threshold.
16611630
16621631 - `type: "compact_20260112"`
1663
1664 - `"compact_20260112"`
16651632
16661633 - `instructions: optional string or null`
16671634
from line 1650
16831650 - `previous_message_id: optional string or null`
16841651
16851652 The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare.
1653
1654 maxLength: 256
16861655
16871656 - `fallback_credit_token: optional string or BetaFallbackCreditTokenParam or null`
16881657
from line 1678
17091678
17101679 - `string`
17111680
1712 - `BetaFallbackCreditTokenParam object { token, mode }`
1681 - `BetaFallbackCreditTokenParam object`
17131682
17141683 Object form of `fallback_credit_token`: the token plus a redemption
17151684 mode.
from line 1692
17231692
17241693 The opaque `fallback_credit_token` from a prior refusal's `stop_details` — the same string the bare-string form carries.
17251694
1695 maxLength: 2048, minLength: 1
1696
17261697 - `mode: optional "strict" or "best_effort"`
17271698
17281699 How a failing token affects the retry. `strict` (the default, and the bare-string behavior): a failing redemption is a 400 and the retry is not served. `best_effort`: the retry is served either way — a token-layer failure no longer rejects the request; the retry proceeds at normal price and the outcome is reported on the response's `usage.fallback_credit`. Two failures stay hard in both modes: a malformed token, and combining `fallback_credit_token` with `fallbacks`.
from line 1742
17711742
17721743 - `type: "json_schema"`
17731744
1774 - `"json_schema"`
1775
17761745 - `task_budget: optional BetaTokenTaskBudget or null`
17771746
17781747 User-configurable total token budget across contexts.
from line 1750
17811750
17821751 Total token budget across all contexts in the session.
17831752
1753 minimum: 1024
1754
17841755 - `type: "tokens"`
17851756
17861757 The budget type. Currently only 'tokens' is supported.
17871758
1788 - `"tokens"`
1789
17901759 - `remaining: optional number or null`
17911760
17921761 Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.
17931762
1763 minimum: 0
1764
17941765 - `speed: optional "standard" or "fast" or null`
17951766
17961767 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 1772
18011772
18021773 - `thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive or null`
18031774
1804 - `BetaThinkingConfigEnabled object { budget_tokens, type, display }`
1775 - `BetaThinkingConfigEnabled object`
18051776
18061777 - `budget_tokens: number`
18071778
from line 1782
18111782
18121783 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
18131784
1785 minimum: 1024
1786
18141787 - `type: "enabled"`
18151788
1816 - `"enabled"`
1817
18181789 - `display: optional "summarized" or "omitted" or null`
18191790
18201791 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
from line 1794
18231794
18241795 - `"omitted"`
18251796
1826 - `BetaThinkingConfigDisabled object { type }`
1797 - `BetaThinkingConfigDisabled object`
18271798
18281799 - `type: "disabled"`
18291800
1830 - `"disabled"`
1831
1832 - `BetaThinkingConfigAdaptive object { type, display }`
1801 - `BetaThinkingConfigAdaptive object`
18331802
18341803 - `type: "adaptive"`
18351804
1836 - `"adaptive"`
1837
18381805 - `display: optional "summarized" or "omitted" or null`
18391806
18401807 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
from line 1812
18451812
18461813 - `Default = "default"`
18471814
1848 - `"default"`
1849
18501815 - `inference_geo: optional string or null`
18511816
18521817 Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.
from line 1820
18551820
18561821 MCP servers to be utilized in this request
18571822
1823 maxItems: 20
1824
18581825 - `name: string`
18591826
18601827 - `type: "url"`
18611828
1862 - `"url"`
1863
18641829 - `url: string`
18651830
18661831 - `authorization_token: optional string or null`
from line 1846
18811846
18821847 This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.
18831848
1849 maxLength: 512
1850
18841851 - `output_config: optional BetaOutputConfig`
18851852
18861853 Configuration options for the model's output, such as the output format.
18871854
1888 - `output_format: optional BetaJSONOutputFormat or null`
1889
1890 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
1891
1892 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
1893
18941855 - `service_tier: optional "auto" or "standard_only"`
18951856
18961857 Determines whether to use priority capacity (if available) or standard capacity for this request.
from line 1896
19351896
19361897 - `text: string`
19371898
1899 minLength: 1
1900
19381901 - `type: "text"`
19391902
19401903 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1906
19431906
19441907 - `citations: optional array of BetaTextCitationParam or null`
19451908
1946 - `temperature: optional number`
1947
1948 Amount of randomness injected into the response.
1949
1950 Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.
1951
1952 Note that even with `temperature` of `0.0`, the results will not be fully deterministic.
1953
19541909 - `thinking: optional BetaThinkingConfigParam`
19551910
19561911 Configuration for enabling Claude's extended thinking.
from line 1914
19591914
19601915 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
19611916
1962 - `BetaThinkingConfigEnabled object { budget_tokens, type, display }`
1963
1964 - `BetaThinkingConfigDisabled object { type }`
1965
1966 - `BetaThinkingConfigAdaptive object { type, display }`
1917 - `BetaThinkingConfigEnabled object`
1918
1919 - `BetaThinkingConfigDisabled object`
1920
1921 - `BetaThinkingConfigAdaptive object`
19671922
19681923 - `tool_choice: optional BetaToolChoice`
19691924
19701925 How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
19711926
1972 - `BetaToolChoiceAuto object { type, disable_parallel_tool_use }`
1927 - `BetaToolChoiceAuto object`
19731928
19741929 The model will automatically decide whether to use tools.
19751930
19761931 - `type: "auto"`
19771932
1978 - `"auto"`
1979
19801933 - `disable_parallel_tool_use: optional boolean`
19811934
19821935 Whether to disable parallel tool use.
19831936
19841937 Defaults to `false`. If set to `true`, the model will output at most one tool use.
19851938
1986 - `BetaToolChoiceAny object { type, disable_parallel_tool_use }`
1939 - `BetaToolChoiceAny object`
19871940
19881941 The model will use any available tools.
19891942
19901943 - `type: "any"`
19911944
1992 - `"any"`
1993
19941945 - `disable_parallel_tool_use: optional boolean`
19951946
19961947 Whether to disable parallel tool use.
19971948
19981949 Defaults to `false`. If set to `true`, the model will output exactly one tool use.
19991950
2000 - `BetaToolChoiceTool object { name, type, disable_parallel_tool_use }`
1951 - `BetaToolChoiceTool object`
20011952
20021953 The model will use the specified tool with `tool_choice.name`.
20031954
from line 1958
20071958
20081959 - `type: "tool"`
20091960
2010 - `"tool"`
2011
20121961 - `disable_parallel_tool_use: optional boolean`
20131962
20141963 Whether to disable parallel tool use.
20151964
20161965 Defaults to `false`. If set to `true`, the model will output exactly one tool use.
20171966
2018 - `BetaToolChoiceNone object { type }`
1967 - `BetaToolChoiceNone object`
20191968
20201969 The model will not be allowed to use tools.
20211970
20221971 - `type: "none"`
2023
2024 - `"none"`
20251972
20261973 - `tools: optional array of BetaToolUnion`
20271974
from line 2034
20872034
20882035 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
20892036
2090 - `BetaTool object { input_schema, name, allowed_callers, 7 more }`
2091
2092 - `input_schema: object { type, properties, required }`
2037 - `BetaTool object`
2038
2039 - `input_schema: object`
20932040
20942041 [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input.
20952042
from line 2044
20972044
20982045 - `type: "object"`
20992046
2100 - `"object"`
2101
21022047 - `properties: optional map[unknown] or null`
21032048
21042049 - `required: optional array of string or null`
from line 2054
21092054
21102055 This is how the tool will be called by the model and in `tool_use` blocks.
21112056
2057 maxLength: 128, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,128}$
2058
21122059 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
21132060
21142061 - `"direct"`
from line 2092
21452092
21462093 - `type: optional "custom" or null`
21472094
2148 - `"custom"`
2149
2150 - `BetaToolBash20241022 object { name, type, allowed_callers, 4 more }`
2095 - `BetaToolBash20241022 object`
21512096
21522097 - `name: "bash"`
21532098
from line 2100
21552100
21562101 This is how the tool will be called by the model and in `tool_use` blocks.
21572102
2158 - `"bash"`
2159
21602103 - `type: "bash_20241022"`
21612104
2162 - `"bash_20241022"`
2163
21642105 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
21652106
21662107 - `"direct"`
from line 2126
21852126
21862127 When true, guarantees schema validation on tool names and inputs
21872128
2188 - `BetaToolBash20250124 object { name, type, allowed_callers, 4 more }`
2129 - `BetaToolBash20250124 object`
21892130
21902131 - `name: "bash"`
21912132
from line 2134
21932134
21942135 This is how the tool will be called by the model and in `tool_use` blocks.
21952136
2196 - `"bash"`
2197
21982137 - `type: "bash_20250124"`
21992138
2200 - `"bash_20250124"`
2201
22022139 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
22032140
22042141 - `"direct"`
from line 2160
22232160
22242161 When true, guarantees schema validation on tool names and inputs
22252162
2226 - `BetaCodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }`
2163 - `BetaCodeExecutionTool20250522 object`
22272164
22282165 - `name: "code_execution"`
22292166
from line 2168
22312168
22322169 This is how the tool will be called by the model and in `tool_use` blocks.
22332170
2234 - `"code_execution"`
2235
22362171 - `type: "code_execution_20250522"`
22372172
2238 - `"code_execution_20250522"`
2239
22402173 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
22412174
22422175 - `"direct"`
from line 2192
22592192
22602193 When true, guarantees schema validation on tool names and inputs
22612194
2262 - `BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }`
2195 - `BetaCodeExecutionTool20250825 object`
22632196
22642197 - `name: "code_execution"`
22652198
from line 2200
22672200
22682201 This is how the tool will be called by the model and in `tool_use` blocks.
22692202
2270 - `"code_execution"`
2271
22722203 - `type: "code_execution_20250825"`
22732204
2205 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2206
2207 - `"direct"`
2208
22742209 - `"code_execution_20250825"`
22752210
2211 - `"code_execution_20260120"`
2212
2213 - `"code_execution_20260521"`
2214
2215 - `cache_control: optional BetaCacheControlEphemeral or null`
2216
2217 Create a cache control breakpoint at this content block.
2218
2219 - `defer_loading: optional boolean`
2220
2221 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
2222
2223 - `strict: optional boolean`
2224
2225 When true, guarantees schema validation on tool names and inputs
2226
2227 - `BetaCodeExecutionTool20260120 object`
2228
2229 Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
2230
2231 - `name: "code_execution"`
2232
2233 Name of the tool.
2234
2235 This is how the tool will be called by the model and in `tool_use` blocks.
2236
2237 - `type: "code_execution_20260120"`
2238
22762239 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
22772240
22782241 - `"direct"`
from line 2258
22952258
22962259 When true, guarantees schema validation on tool names and inputs
22972260
2298 - `BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }`
2299
2300 Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
2261 - `BetaCodeExecutionTool20260521 object`
2262
2263 Code execution tool with REPL state persistence.
23012264
23022265 - `name: "code_execution"`
23032266
from line 2268
23052268
23062269 This is how the tool will be called by the model and in `tool_use` blocks.
23072270
2308 - `"code_execution"`
2309
2310 - `type: "code_execution_20260120"`
2271 - `type: "code_execution_20260521"`
2272
2273 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2274
2275 - `"direct"`
2276
2277 - `"code_execution_20250825"`
23112278
23122279 - `"code_execution_20260120"`
23132280
2314 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2315
2316 - `"direct"`
2317
2318 - `"code_execution_20250825"`
2319
2320 - `"code_execution_20260120"`
2321
23222281 - `"code_execution_20260521"`
23232282
23242283 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 2292
23332292
23342293 When true, guarantees schema validation on tool names and inputs
23352294
2336 - `BetaCodeExecutionTool20260521 object { name, type, allowed_callers, 3 more }`
2337
2338 Code execution tool with REPL state persistence.
2339
2340 - `name: "code_execution"`
2341
2342 Name of the tool.
2343
2344 This is how the tool will be called by the model and in `tool_use` blocks.
2345
2346 - `"code_execution"`
2347
2348 - `type: "code_execution_20260521"`
2349
2350 - `"code_execution_20260521"`
2351
2352 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2353
2354 - `"direct"`
2355
2356 - `"code_execution_20250825"`
2357
2358 - `"code_execution_20260120"`
2359
2360 - `"code_execution_20260521"`
2361
2362 - `cache_control: optional BetaCacheControlEphemeral or null`
2363
2364 Create a cache control breakpoint at this content block.
2365
2366 - `defer_loading: optional boolean`
2367
2368 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
2369
2370 - `strict: optional boolean`
2371
2372 When true, guarantees schema validation on tool names and inputs
2373
2374 - `BetaBrowserToolset20260801 object { type, allowed_callers, cache_control, configs }`
2295 - `BetaBrowserToolset20260801 object`
23752296
23762297 The browser toolset: a single `tools[]` entry (carrying no
23772298 `name`) that declares the browser tool family. The model is served
from line 2300
23792300 from its schema.
23802301
23812302 - `type: "browser_toolset_20260801"`
2382
2383 - `"browser_toolset_20260801"`
23842303
23852304 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
23862305
from line 2696
27772696
27782697 Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
27792698
2780 - `BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }`
2699 - `BetaToolComputerUse20241022 object`
27812700
27822701 - `display_height_px: number`
27832702
27842703 The height of the display in pixels.
27852704
2705 minimum: 1
2706
27862707 - `display_width_px: number`
27872708
27882709 The width of the display in pixels.
27892710
2711 minimum: 1
2712
27902713 - `name: "computer"`
27912714
27922715 Name of the tool.
27932716
27942717 This is how the tool will be called by the model and in `tool_use` blocks.
27952718
2796 - `"computer"`
2797
27982719 - `type: "computer_20241022"`
27992720
2800 - `"computer_20241022"`
2801
28022721 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
28032722
28042723 - `"direct"`
from line 2740
28212740
28222741 The X11 display number (e.g. 0, 1) for the display.
28232742
2743 minimum: 0
2744
28242745 - `input_examples: optional array of map[unknown]`
28252746
28262747 - `strict: optional boolean`
28272748
28282749 When true, guarantees schema validation on tool names and inputs
28292750
2830 - `BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }`
2751 - `BetaMemoryTool20250818 object`
28312752
28322753 - `name: "memory"`
28332754
from line 2756
28352756
28362757 This is how the tool will be called by the model and in `tool_use` blocks.
28372758
2838 - `"memory"`
2839
28402759 - `type: "memory_20250818"`
28412760
2842 - `"memory_20250818"`
2843
28442761 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
28452762
28462763 - `"direct"`
from line 2782
28652782
28662783 When true, guarantees schema validation on tool names and inputs
28672784
2868 - `BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }`
2785 - `BetaToolComputerUse20250124 object`
28692786
28702787 - `display_height_px: number`
28712788
28722789 The height of the display in pixels.
28732790
2791 minimum: 1
2792
28742793 - `display_width_px: number`
28752794
28762795 The width of the display in pixels.
28772796
2797 minimum: 1
2798
28782799 - `name: "computer"`
28792800
28802801 Name of the tool.
28812802
28822803 This is how the tool will be called by the model and in `tool_use` blocks.
28832804
2884 - `"computer"`
2885
28862805 - `type: "computer_20250124"`
28872806
2888 - `"computer_20250124"`
2889
28902807 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
28912808
28922809 - `"direct"`
from line 2826
29092826
29102827 The X11 display number (e.g. 0, 1) for the display.
29112828
2829 minimum: 0
2830
29122831 - `input_examples: optional array of map[unknown]`
29132832
29142833 - `strict: optional boolean`
29152834
29162835 When true, guarantees schema validation on tool names and inputs
29172836
2918 - `BetaToolTextEditor20241022 object { name, type, allowed_callers, 4 more }`
2837 - `BetaToolTextEditor20241022 object`
29192838
29202839 - `name: "str_replace_editor"`
29212840
from line 2842
29232842
29242843 This is how the tool will be called by the model and in `tool_use` blocks.
29252844
2926 - `"str_replace_editor"`
2927
29282845 - `type: "text_editor_20241022"`
29292846
2930 - `"text_editor_20241022"`
2931
29322847 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
29332848
29342849 - `"direct"`
from line 2868
29532868
29542869 When true, guarantees schema validation on tool names and inputs
29552870
2956 - `BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }`
2871 - `BetaToolComputerUse20251124 object`
29572872
29582873 - `display_height_px: number`
29592874
29602875 The height of the display in pixels.
29612876
2877 minimum: 1
2878
29622879 - `display_width_px: number`
29632880
29642881 The width of the display in pixels.
29652882
2883 minimum: 1
2884
29662885 - `name: "computer"`
29672886
29682887 Name of the tool.
29692888
29702889 This is how the tool will be called by the model and in `tool_use` blocks.
29712890
2972 - `"computer"`
2973
29742891 - `type: "computer_20251124"`
29752892
2976 - `"computer_20251124"`
2977
29782893 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
29792894
29802895 - `"direct"`
from line 2912
29972912
29982913 The X11 display number (e.g. 0, 1) for the display.
29992914
2915 minimum: 0
2916
30002917 - `enable_zoom: optional boolean`
30012918
30022919 Whether to enable an action to take a zoomed-in screenshot of the screen.
from line 2924
30072924
30082925 When true, guarantees schema validation on tool names and inputs
30092926
3010 - `BetaComputerToolset20260801 object { type, allowed_callers, cache_control, configs }`
2927 - `BetaComputerToolset20260801 object`
30112928
30122929 The computer toolset: a single `tools[]` entry (carrying no
30132930 `name`) that declares the computer tool family. The model is
from line 2937
30202937
30212938 - `type: "computer_toolset_20260801"`
30222939
3023 - `"computer_toolset_20260801"`
3024
30252940 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
30262941
30272942 - `"direct"`
from line 3164
32493164
32503165 Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
32513166
3252 - `BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }`
3167 - `BetaToolTextEditor20250124 object`
32533168
32543169 - `name: "str_replace_editor"`
32553170
from line 3172
32573172
32583173 This is how the tool will be called by the model and in `tool_use` blocks.
32593174
3260 - `"str_replace_editor"`
3261
32623175 - `type: "text_editor_20250124"`
32633176
3264 - `"text_editor_20250124"`
3265
32663177 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
32673178
32683179 - `"direct"`
from line 3198
32873198
32883199 When true, guarantees schema validation on tool names and inputs
32893200
3290 - `BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }`
3201 - `BetaToolTextEditor20250429 object`
32913202
32923203 - `name: "str_replace_based_edit_tool"`
32933204
from line 3206
32953206
32963207 This is how the tool will be called by the model and in `tool_use` blocks.
32973208
3298 - `"str_replace_based_edit_tool"`
3299
33003209 - `type: "text_editor_20250429"`
33013210
3302 - `"text_editor_20250429"`
3303
33043211 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33053212
33063213 - `"direct"`
from line 3232
33253232
33263233 When true, guarantees schema validation on tool names and inputs
33273234
3328 - `BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }`
3235 - `BetaToolTextEditor20250728 object`
33293236
33303237 - `name: "str_replace_based_edit_tool"`
33313238
from line 3240
33333240
33343241 This is how the tool will be called by the model and in `tool_use` blocks.
33353242
3336 - `"str_replace_based_edit_tool"`
3337
33383243 - `type: "text_editor_20250728"`
33393244
3340 - `"text_editor_20250728"`
3341
33423245 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33433246
33443247 - `"direct"`
from line 3266
33633266
33643267 Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.
33653268
3269 minimum: 1
3270
33663271 - `strict: optional boolean`
33673272
33683273 When true, guarantees schema validation on tool names and inputs
33693274
3370 - `BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }`
3275 - `BetaWebSearchTool20250305 object`
33713276
33723277 - `name: "web_search"`
33733278
from line 3280
33753280
33763281 This is how the tool will be called by the model and in `tool_use` blocks.
33773282
3378 - `"web_search"`
3379
33803283 - `type: "web_search_20250305"`
33813284
3382 - `"web_search_20250305"`
3383
33843285 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33853286
33863287 - `"direct"`
from line 3312
34113312
34123313 Maximum number of times the tool can be used in the API request.
34133314
3315 exclusiveMinimum: 0
3316
34143317 - `strict: optional boolean`
34153318
34163319 When true, guarantees schema validation on tool names and inputs
from line 3324
34213324
34223325 - `type: "approximate"`
34233326
3424 - `"approximate"`
3425
34263327 - `city: optional string or null`
34273328
34283329 The city of the user.
34293330
3331 maxLength: 255, minLength: 1
3332
34303333 - `country: optional string or null`
34313334
34323335 The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.
34333336
3337 maxLength: 2, minLength: 2
3338
34343339 - `region: optional string or null`
34353340
34363341 The region of the user.
34373342
3343 maxLength: 255, minLength: 1
3344
34383345 - `timezone: optional string or null`
34393346
34403347 The [IANA timezone](https://nodatime.org/TimeZones) of the user.
34413348
3442 - `BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }`
3349 maxLength: 255, minLength: 1
3350
3351 - `BetaWebFetchTool20250910 object`
34433352
34443353 - `name: "web_fetch"`
34453354
from line 3356
34473356
34483357 This is how the tool will be called by the model and in `tool_use` blocks.
34493358
3450 - `"web_fetch"`
3451
34523359 - `type: "web_fetch_20250910"`
34533360
3454 - `"web_fetch_20250910"`
3455
34563361 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
34573362
34583363 - `"direct"`
from line 3392
34873392
34883393 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
34893394
3395 exclusiveMinimum: 0
3396
34903397 - `max_uses: optional number or null`
34913398
34923399 Maximum number of times the tool can be used in the API request.
34933400
3401 exclusiveMinimum: 0
3402
34943403 - `strict: optional boolean`
34953404
34963405 When true, guarantees schema validation on tool names and inputs
34973406
3498 - `BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }`
3407 - `BetaWebSearchTool20260209 object`
34993408
35003409 - `name: "web_search"`
35013410
from line 3412
35033412
35043413 This is how the tool will be called by the model and in `tool_use` blocks.
35053414
3506 - `"web_search"`
3507
35083415 - `type: "web_search_20260209"`
35093416
3510 - `"web_search_20260209"`
3511
35123417 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
35133418
35143419 - `"direct"`
from line 3444
35393444
35403445 Maximum number of times the tool can be used in the API request.
35413446
3447 exclusiveMinimum: 0
3448
35423449 - `strict: optional boolean`
35433450
35443451 When true, guarantees schema validation on tool names and inputs
from line 3454
35473454
35483455 Parameters for the user's location. Used to provide more relevant search results.
35493456
3550 - `BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }`
3457 - `BetaWebFetchTool20260209 object`
35513458
35523459 - `name: "web_fetch"`
35533460
from line 3462
35553462
35563463 This is how the tool will be called by the model and in `tool_use` blocks.
35573464
3558 - `"web_fetch"`
3559
35603465 - `type: "web_fetch_20260209"`
35613466
3562 - `"web_fetch_20260209"`
3563
35643467 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
35653468
35663469 - `"direct"`
from line 3498
35953498
35963499 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
35973500
3501 exclusiveMinimum: 0
3502
35983503 - `max_uses: optional number or null`
35993504
36003505 Maximum number of times the tool can be used in the API request.
36013506
3507 exclusiveMinimum: 0
3508
36023509 - `strict: optional boolean`
36033510
36043511 When true, guarantees schema validation on tool names and inputs
36053512
3606 - `BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }`
3513 - `BetaWebFetchTool20260309 object`
36073514
36083515 Web fetch tool with use_cache parameter for bypassing cached content.
36093516
from line 3520
36133520
36143521 This is how the tool will be called by the model and in `tool_use` blocks.
36153522
3616 - `"web_fetch"`
3617
36183523 - `type: "web_fetch_20260309"`
36193524
3620 - `"web_fetch_20260309"`
3621
36223525 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
36233526
36243527 - `"direct"`
from line 3556
36533556
36543557 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
36553558
3559 exclusiveMinimum: 0
3560
36563561 - `max_uses: optional number or null`
36573562
36583563 Maximum number of times the tool can be used in the API request.
36593564
3565 exclusiveMinimum: 0
3566
36603567 - `strict: optional boolean`
36613568
36623569 When true, guarantees schema validation on tool names and inputs
from line 3572
36653572
36663573 Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.
36673574
3668 - `BetaWebSearchTool20260318 object { name, type, allowed_callers, 8 more }`
3575 - `BetaWebSearchTool20260318 object`
36693576
36703577 - `name: "web_search"`
36713578
from line 3580
36733580
36743581 This is how the tool will be called by the model and in `tool_use` blocks.
36753582
3676 - `"web_search"`
3677
36783583 - `type: "web_search_20260318"`
36793584
3680 - `"web_search_20260318"`
3681
36823585 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
36833586
36843587 - `"direct"`
from line 3612
37093612
37103613 Maximum number of times the tool can be used in the API request.
37113614
3615 exclusiveMinimum: 0
3616
37123617 - `response_inclusion: optional "full" or "excluded"`
37133618
37143619 How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3630
37253630
37263631 Parameters for the user's location. Used to provide more relevant search results.
37273632
3728 - `BetaWebFetchTool20260318 object { name, type, allowed_callers, 10 more }`
3633 - `BetaWebFetchTool20260318 object`
37293634
37303635 - `name: "web_fetch"`
37313636
from line 3638
37333638
37343639 This is how the tool will be called by the model and in `tool_use` blocks.
37353640
3736 - `"web_fetch"`
3737
37383641 - `type: "web_fetch_20260318"`
37393642
3740 - `"web_fetch_20260318"`
3741
37423643 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
37433644
37443645 - `"direct"`
from line 3674
37733674
37743675 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
37753676
3677 exclusiveMinimum: 0
3678
37763679 - `max_uses: optional number or null`
37773680
37783681 Maximum number of times the tool can be used in the API request.
37793682
3683 exclusiveMinimum: 0
3684
37803685 - `response_inclusion: optional "full" or "excluded"`
37813686
37823687 How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3698
37933698
37943699 Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.
37953700
3796 - `BetaAdvisorTool20260301 object { model, name, type, 7 more }`
3701 - `BetaAdvisorTool20260301 object`
37973702
37983703 - `model: Model`
37993704
from line 3712
38073712
38083713 This is how the tool will be called by the model and in `tool_use` blocks.
38093714
3810 - `"advisor"`
3811
38123715 - `type: "advisor_20260301"`
38133716
3814 - `"advisor_20260301"`
3815
38163717 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
38173718
38183719 - `"direct"`
from line 3740
38393740
38403741 Bounds the advisor's total output (thinking + text) per call. When the advisor hits this cap, the returned advisor_result or advisor_redacted_result block carries stop_reason='max_tokens', and a truncation note is appended to the advice text the worker model sees (inside the encrypted blob in redacted mode). When set, the server also emits a remaining-tokens budget block in the advisor's prompt so the advisor self-shapes toward the cap. When omitted, the advisor model's default output cap applies and no budget block is emitted.
38413742
3743 minimum: 1024
3744
38423745 - `max_uses: optional number or null`
38433746
38443747 Maximum number of times the tool can be used in the API request.
38453748
3749 exclusiveMinimum: 0
3750
38463751 - `strict: optional boolean`
38473752
38483753 When true, guarantees schema validation on tool names and inputs
38493754
3850 - `BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }`
3755 - `BetaToolSearchToolBm25_20251119 object`
38513756
38523757 - `name: "tool_search_tool_bm25"`
38533758
from line 3760
38553760
38563761 This is how the tool will be called by the model and in `tool_use` blocks.
38573762
3763 - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"`
3764
3765 - `"tool_search_tool_bm25_20251119"`
3766
38583767 - `"tool_search_tool_bm25"`
38593768
3860 - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"`
3861
3862 - `"tool_search_tool_bm25_20251119"`
3863
3864 - `"tool_search_tool_bm25"`
3865
38663769 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
38673770
38683771 - `"direct"`
from line 3788
38853788
38863789 When true, guarantees schema validation on tool names and inputs
38873790
3888 - `BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }`
3791 - `BetaToolSearchToolRegex20251119 object`
38893792
38903793 - `name: "tool_search_tool_regex"`
38913794
from line 3796
38933796
38943797 This is how the tool will be called by the model and in `tool_use` blocks.
38953798
3799 - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"`
3800
3801 - `"tool_search_tool_regex_20251119"`
3802
38963803 - `"tool_search_tool_regex"`
38973804
3898 - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"`
3899
3900 - `"tool_search_tool_regex_20251119"`
3901
3902 - `"tool_search_tool_regex"`
3903
39043805 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
39053806
39063807 - `"direct"`
from line 3824
39233824
39243825 When true, guarantees schema validation on tool names and inputs
39253826
3926 - `BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }`
3827 - `BetaMCPToolset object`
39273828
39283829 Configuration for a group of tools from an MCP server.
39293830
from line 3835
39343835
39353836 Name of the MCP server to configure tools for
39363837
3838 maxLength: 255, minLength: 1
3839
39373840 - `type: "mcp_toolset"`
39383841
3939 - `"mcp_toolset"`
3940
39413842 - `cache_control: optional BetaCacheControlEphemeral or null`
39423843
39433844 Create a cache control breakpoint at this content block.
from line 3859
39583859
39593860 - `enabled: optional boolean`
39603861
3862 - `output_format: optional BetaJSONOutputFormat or null`
3863
3864 **Deprecated**
3865
3866 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
3867
3868 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
3869
3870 - `temperature: optional number`
3871
3872 **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not support setting temperature. A value of 1.0 of will be accepted for backwards compatibility, all other values will be rejected with a 400 error.
3873
3874 Amount of randomness injected into the response.
3875
3876 Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.
3877
3878 Note that even with `temperature` of `0.0`, the results will not be fully deterministic.
3879
3880 maximum: 1, minimum: 0
3881
39613882 - `top_k: optional number`
39623883
3884 **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not accept top_k; any value will be rejected with a 400 error.
3885
39633886 Only sample from the top K options for each subsequent token.
39643887
39653888 Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).
39663889
39673890 Recommended for advanced use cases only.
39683891
3892 minimum: 0
3893
39693894 - `top_p: optional number`
39703895
3896 **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not support setting top_p. A value >= 0.99 will be accepted for backwards compatibility, all other values will be rejected with a 400 error.
3897
39713898 Use nucleus sampling.
39723899
39733900 In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`.
39743901
39753902 Recommended for advanced use cases only.
39763903
3977### Returns
3978
3979- `BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }`
3904 maximum: 1, minimum: 0
3905
3906## Returns
3907
3908- `BetaMessageBatch object`
39803909
39813910 - `id: string`
39823911
from line 3917
39883917
39893918 RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
39903919
3920 format: date-time
3921
39913922 - `cancel_initiated_at: string or null`
39923923
39933924 RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
39943925
3926 format: date-time
3927
39953928 - `created_at: string`
39963929
39973930 RFC 3339 datetime string representing the time at which the Message Batch was created.
39983931
3932 format: date-time
3933
39993934 - `ended_at: string or null`
40003935
40013936 RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
40023937
40033938 Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
40043939
3940 format: date-time
3941
40053942 - `expires_at: string`
40063943
40073944 RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
40083945
3946 format: date-time
3947
40093948 - `processing_status: "in_progress" or "canceling" or "ended"`
40103949
40113950 Processing status of the Message Batch.
from line 3967
40283967
40293968 This is zero until processing of the entire Message Batch has ended.
40303969
3970 default: 0
3971
40313972 - `errored: number`
40323973
40333974 Number of requests in the Message Batch that encountered an error.
40343975
40353976 This is zero until processing of the entire Message Batch has ended.
40363977
3978 default: 0
3979
40373980 - `expired: number`
40383981
40393982 Number of requests in the Message Batch that have expired.
40403983
40413984 This is zero until processing of the entire Message Batch has ended.
40423985
3986 default: 0
3987
40433988 - `processing: number`
40443989
40453990 Number of requests in the Message Batch that are processing.
40463991
3992 default: 0
3993
40473994 - `succeeded: number`
40483995
40493996 Number of requests in the Message Batch that have completed successfully.
40503997
40513998 This is zero until processing of the entire Message Batch has ended.
40523999
4000 default: 0
4001
40534002 - `results_url: string or null`
40544003
40554004 URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
from line 4011
40624011
40634012 For Message Batches, this is always `"message_batch"`.
40644013
4065 - `"message_batch"`
4066
4067### Example
4068
4069```http
4014 default: message_batch
4015
4016## Example
4017
4018```bash
40704019curl https://api.anthropic.com/v1/messages/batches \
40714020 -H 'Content-Type: application/json' \
40724021 -H 'anthropic-version: 2023-06-01' \
from line 4040
40914040 }'
40924041```
40934042
4094#### Response
4043### Response (200)
40954044
40964045```json
40974046{
40984047
api/beta/messages/batches/delete Changed · +10 / -15 lines
# Delete a Message Batch ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Delete a Message Batch ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Delete a Message Batch
3url: https://platform.claude.com/docs/en/api/beta/messages/batches/delete
4---
1# Delete a Message Batch
52
6## Delete a Message Batch
3**DELETE** `/v1/messages/batches/{message_batch_id}`
74
8**delete** `/v1/messages/batches/{message_batch_id}`
9
105Delete a Message Batch.
116
127Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it.
from line 8
138
149Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
1510
16### Path Parameters
11## Path parameters
1712
1813- `message_batch_id: string`
1914
2015 ID of the Message Batch.
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
100### Returns
95## Returns
10196
102- `BetaDeletedMessageBatch object { id, type }`
97- `BetaDeletedMessageBatch object`
10398
10499 - `id: string`
105100
from line 106
111106
112107 For Message Batches, this is always `"message_batch_deleted"`.
113108
114 - `"message_batch_deleted"`
109 default: message_batch_deleted
115110
116### Example
111## Example
117112
118```http
113```bash
119114curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
120115 -X DELETE \
121116 -H 'anthropic-version: 2023-06-01' \
from line 118
123118 -H "X-Api-Key: $ANTHROPIC_API_KEY"
124119```
125120
126#### Response
121### Response (200)
127122
128123```json
129124{
api/beta/messages/batches/list Changed · +33 / -16 lines
# List Message Batches ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Message Batches ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Message Batches
3url: https://platform.claude.com/docs/en/api/beta/messages/batches/list
4---
1# List Message Batches
52
6## List Message Batches
3**GET** `/v1/messages/batches`
74
8**get** `/v1/messages/batches`
9
105List all Message Batches within a Workspace. Most recently created batches are returned first.
116
127Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
138
14### Query Parameters
9## Query parameters
1510
1611- `after_id: optional string`
1712
from line 22
2722
2823 Defaults to `20`. Ranges from `1` to `1000`.
2924
30### Header Parameters
25 default: 20, maximum: 1000, minimum: 1
3126
27## Headers
28
3229- `"anthropic-beta": optional array of AnthropicBeta`
3330
3431 Optional header to specify the beta version(s) you want to use.
from line 102
105102
106103 - `"mid-conversation-tool-changes-2026-07-01"`
107104
108### Returns
105## Returns
109106
110107- `data: array of BetaMessageBatch`
111108
from line 116
119116
120117 RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
121118
119 format: date-time
120
122121 - `cancel_initiated_at: string or null`
123122
124123 RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
125124
125 format: date-time
126
126127 - `created_at: string`
127128
128129 RFC 3339 datetime string representing the time at which the Message Batch was created.
129130
131 format: date-time
132
130133 - `ended_at: string or null`
131134
132135 RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
from line 136
133136
134137 Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
135138
139 format: date-time
140
136141 - `expires_at: string`
137142
138143 RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
139144
145 format: date-time
146
140147 - `processing_status: "in_progress" or "canceling" or "ended"`
141148
142149 Processing status of the Message Batch.
from line 166
159166
160167 This is zero until processing of the entire Message Batch has ended.
161168
169 default: 0
170
162171 - `errored: number`
163172
164173 Number of requests in the Message Batch that encountered an error.
from line 174
165174
166175 This is zero until processing of the entire Message Batch has ended.
167176
177 default: 0
178
168179 - `expired: number`
169180
170181 Number of requests in the Message Batch that have expired.
from line 182
171182
172183 This is zero until processing of the entire Message Batch has ended.
173184
185 default: 0
186
174187 - `processing: number`
175188
176189 Number of requests in the Message Batch that are processing.
177190
191 default: 0
192
178193 - `succeeded: number`
179194
180195 Number of requests in the Message Batch that have completed successfully.
from line 196
181196
182197 This is zero until processing of the entire Message Batch has ended.
183198
199 default: 0
200
184201 - `results_url: string or null`
185202
186203 URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
from line 210
193210
194211 For Message Batches, this is always `"message_batch"`.
195212
196 - `"message_batch"`
213 default: message_batch
197214
198215- `first_id: string or null`
199216
from line 224
207224
208225 Last ID in the `data` list. Can be used as the `after_id` for the next page.
209226
210### Example
227## Example
211228
212```http
229```bash
213230curl https://api.anthropic.com/v1/messages/batches \
214231 -H 'anthropic-version: 2023-06-01' \
215232 -H 'anthropic-beta: message-batches-2024-09-24' \
from line 233
216233 -H "X-Api-Key: $ANTHROPIC_API_KEY"
217234```
218235
219#### Response
236### Response (200)
220237
221238```json
222239{
api/beta/messages/batches/results Changed · +363 / -236 lines
# Retrieve Message Batch results ## Path parameters ## Headers ## Returns ## Example ## Retrieve Message Batch results ### Path Parameters ### Header Parameters ### Returns ### Example
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: Retrieve Message Batch results
3url: https://platform.claude.com/docs/en/api/beta/messages/batches/results
4---
5
6## Retrieve Message Batch results
7
8**get** `/v1/messages/batches/{message_batch_id}/results`
1# Retrieve Message Batch results
2
3**GET** `/v1/messages/batches/{message_batch_id}/results`
94
105Streams the results of a Message Batch as a `.jsonl` file.
116
from line 8
138
149Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
1510
16### Path Parameters
11## Path parameters
1712
1813- `message_batch_id: string`
1914
2015 ID of the Message Batch.
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
100### Returns
101
102- `BetaMessageBatchIndividualResponse object { custom_id, result }`
95## Returns
96
97- `BetaMessageBatchIndividualResponse object`
10398
10499 This is a single line in the response `.jsonl` file and does not represent the response as a whole.
105100
from line 110
115110
116111 Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.
117112
118 - `BetaMessageBatchSucceededResult object { message, type }`
113 - `BetaMessageBatchSucceededResult object`
119114
120115 - `message: BetaMessage`
121116
from line 132
137132
138133 The time at which the container will expire.
139134
135 format: date-time
136
140137 - `skills: array of BetaSkill or null`
141138
142139 Skills loaded in the container
from line 142
145142
146143 Skill ID
147144
145 maxLength: 64, minLength: 1
146
148147 - `type: "anthropic" or "custom"`
149148
150149 Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
from line 155
156155 - `version: string`
157156
158157 The resolved version: a skill version ID for custom skills.
158
159 maxLength: 64, minLength: 1
159160
160161 - `content: array of BetaContentBlock`
161162
from line 187
186187 [{"type": "text", "text": "B)"}]
187188 ```
188189
189 - `BetaTextBlock object { citations, text, type }`
190 - `BetaTextBlock object`
190191
191192 - `citations: array of BetaTextCitation or null`
192193
from line 195
194195
195196 The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`.
196197
197 - `BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }`
198 - `BetaCitationCharLocation object`
198199
199200 - `cited_text: string`
200201
201202 - `document_index: number`
202203
204 minimum: 0
205
203206 - `document_title: string or null`
204207
205208 - `end_char_index: number`
from line 211
208211
209212 - `start_char_index: number`
210213
214 minimum: 0
215
211216 - `type: "char_location"`
212217
213 - `"char_location"`
214
215 - `BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }`
218 default: char_location
219
220 - `BetaCitationPageLocation object`
216221
217222 - `cited_text: string`
218223
219224 - `document_index: number`
220225
226 minimum: 0
227
221228 - `document_title: string or null`
222229
223230 - `end_page_number: number`
from line 233
226233
227234 - `start_page_number: number`
228235
236 minimum: 1
237
229238 - `type: "page_location"`
230239
231 - `"page_location"`
232
233 - `BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }`
240 default: page_location
241
242 - `BetaCitationContentBlockLocation object`
234243
235244 - `cited_text: string`
236245
from line 249
240249
241250 - `document_index: number`
242251
252 minimum: 0
253
243254 - `document_title: string or null`
244255
245256 - `end_block_index: number`
from line 265
254265
255266 0-based index of the first cited block in the source's `content` array.
256267
268 minimum: 0
269
257270 - `type: "content_block_location"`
258271
259 - `"content_block_location"`
260
261 - `BetaCitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }`
272 default: content_block_location
273
274 - `BetaCitationsWebSearchResultLocation object`
262275
263276 - `cited_text: string`
264277
from line 279
266279
267280 - `title: string or null`
268281
282 maxLength: 512
283
269284 - `type: "web_search_result_location"`
270285
271 - `"web_search_result_location"`
286 default: web_search_result_location
272287
273288 - `url: string`
274289
275 - `BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }`
290 - `BetaCitationSearchResultLocation object`
276291
277292 - `cited_text: string`
278293
from line 307
292307
293308 Counted separately from `document_index`; server-side web search results are not included in this count.
294309
310 minimum: 0
311
295312 - `source: string`
296313
297314 - `start_block_index: number`
298315
299316 0-based index of the first cited block in the source's `content` array.
300317
318 minimum: 0
319
301320 - `title: string or null`
302321
303322 - `type: "search_result_location"`
304323
305 - `"search_result_location"`
324 default: search_result_location
306325
307326 - `text: string`
308327
328 maxLength: 5000000, minLength: 0
329
309330 - `type: "text"`
310331
311 - `"text"`
312
313 - `BetaThinkingBlock object { signature, thinking, type }`
332 default: text
333
334 - `BetaThinkingBlock object`
314335
315336 - `signature: string`
316337
from line 347
326347
327348 - `type: "thinking"`
328349
329 - `"thinking"`
330
331 - `BetaRedactedThinkingBlock object { data, type }`
350 default: thinking
351
352 - `BetaRedactedThinkingBlock object`
332353
333354 - `data: string`
334355
from line 361
340361
341362 - `type: "redacted_thinking"`
342363
343 - `"redacted_thinking"`
344
345 - `BetaToolUseBlock object { id, input, name, 3 more }`
364 default: redacted_thinking
365
366 - `BetaToolUseBlock object`
346367
347368 - `id: string`
348369
370 pattern: ^[a-zA-Z0-9_-]+$
371
349372 - `input: map[unknown]`
350373
351374 - `name: string`
352375
376 minLength: 1
377
353378 - `type: "tool_use"`
354379
355 - `"tool_use"`
380 default: tool_use
356381
357382 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
358383
359384 Tool invocation directly from the model.
360385
361 - `BetaDirectCaller object { type }`
386 - `BetaDirectCaller object`
362387
363388 Tool invocation directly from the model.
364389
365390 - `type: "direct"`
366391
367 - `"direct"`
368
369 - `BetaServerToolCaller object { tool_id, type }`
392 - `BetaServerToolCaller object`
370393
371394 Tool invocation generated by a server-side tool.
372395
373396 - `tool_id: string`
374397
398 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
399
375400 - `type: "code_execution_20250825"`
376401
377 - `"code_execution_20250825"`
378
379 - `BetaServerToolCaller20260120 object { tool_id, type }`
402 - `BetaServerToolCaller20260120 object`
380403
381404 - `tool_id: string`
382405
406 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
407
383408 - `type: "code_execution_20260120"`
384409
385 - `"code_execution_20260120"`
386
387410 - `toolset_name: optional string or null`
388411
389412 For a toolset member tool_use, the toolset family.
390413
391 - `BetaServerToolUseBlock object { id, input, name, 2 more }`
414 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
415
416 - `BetaServerToolUseBlock object`
392417
393418 - `id: string`
394419
420 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
421
395422 - `input: map[unknown]`
396423
397424 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 441
414441
415442 - `type: "server_tool_use"`
416443
417 - `"server_tool_use"`
444 default: server_tool_use
418445
419446 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
420447
421448 Tool invocation directly from the model.
422449
423 - `BetaDirectCaller object { type }`
450 - `BetaDirectCaller object`
424451
425452 Tool invocation directly from the model.
426453
427 - `BetaServerToolCaller object { tool_id, type }`
454 - `BetaServerToolCaller object`
428455
429456 Tool invocation generated by a server-side tool.
430457
431 - `BetaServerToolCaller20260120 object { tool_id, type }`
432
433 - `BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }`
458 - `BetaServerToolCaller20260120 object`
459
460 - `BetaWebSearchToolResultBlock object`
434461
435462 - `content: BetaWebSearchToolResultBlockContent`
436463
437 - `BetaWebSearchToolResultError object { error_code, type }`
464 - `BetaWebSearchToolResultError object`
438465
439466 - `error_code: BetaWebSearchToolResultErrorCode`
440467
from line 479
452479
453480 - `type: "web_search_tool_result_error"`
454481
455 - `"web_search_tool_result_error"`
482 default: web_search_tool_result_error
456483
457484 - `array of BetaWebSearchResultBlock`
458485
from line 491
464491
465492 - `type: "web_search_result"`
466493
467 - `"web_search_result"`
494 default: web_search_result
468495
469496 - `url: string`
470497
471498 - `tool_use_id: string`
472499
500 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
501
473502 - `type: "web_search_tool_result"`
474503
475 - `"web_search_tool_result"`
504 default: web_search_tool_result
476505
477506 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
478507
479508 Tool invocation directly from the model.
480509
481 - `BetaDirectCaller object { type }`
510 - `BetaDirectCaller object`
482511
483512 Tool invocation directly from the model.
484513
485 - `BetaServerToolCaller object { tool_id, type }`
514 - `BetaServerToolCaller object`
486515
487516 Tool invocation generated by a server-side tool.
488517
489 - `BetaServerToolCaller20260120 object { tool_id, type }`
490
491 - `BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }`
518 - `BetaServerToolCaller20260120 object`
519
520 - `BetaWebFetchToolResultBlock object`
492521
493522 - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock`
494523
495 - `BetaWebFetchToolResultErrorBlock object { error_code, type }`
524 - `BetaWebFetchToolResultErrorBlock object`
496525
497526 - `error_code: BetaWebFetchToolResultErrorCode`
498527
from line 545
516545
517546 - `type: "web_fetch_tool_result_error"`
518547
519 - `"web_fetch_tool_result_error"`
520
521 - `BetaWebFetchBlock object { content, retrieved_at, type, url }`
548 default: web_fetch_tool_result_error
549
550 - `BetaWebFetchBlock object`
522551
523552 - `content: BetaDocumentBlock`
524553
from line 557
528557
529558 - `enabled: boolean`
530559
560 default: false
561
531562 - `source: BetaBase64PDFSource or BetaPlainTextSource`
532563
533 - `BetaBase64PDFSource object { data, media_type, type }`
564 - `BetaBase64PDFSource object`
534565
535566 - `data: string`
536567
568 format: byte
569
537570 - `media_type: "application/pdf"`
538571
539 - `"application/pdf"`
540
541572 - `type: "base64"`
542573
543 - `"base64"`
544
545 - `BetaPlainTextSource object { data, media_type, type }`
574 - `BetaPlainTextSource object`
546575
547576 - `data: string`
548577
549578 - `media_type: "text/plain"`
550579
551 - `"text/plain"`
552
553580 - `type: "text"`
554581
555 - `"text"`
556
557582 - `title: string or null`
558583
559584 The title of the document
560585
561586 - `type: "document"`
562587
563 - `"document"`
588 default: document
564589
565590 - `retrieved_at: string or null`
566591
from line 593
568593
569594 - `type: "web_fetch_result"`
570595
571 - `"web_fetch_result"`
596 default: web_fetch_result
572597
573598 - `url: string`
574599
from line 601
576601
577602 - `tool_use_id: string`
578603
604 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
605
579606 - `type: "web_fetch_tool_result"`
580607
581 - `"web_fetch_tool_result"`
608 default: web_fetch_tool_result
582609
583610 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
584611
585612 Tool invocation directly from the model.
586613
587 - `BetaDirectCaller object { type }`
614 - `BetaDirectCaller object`
588615
589616 Tool invocation directly from the model.
590617
591 - `BetaServerToolCaller object { tool_id, type }`
618 - `BetaServerToolCaller object`
592619
593620 Tool invocation generated by a server-side tool.
594621
595 - `BetaServerToolCaller20260120 object { tool_id, type }`
596
597 - `BetaAdvisorToolResultBlock object { content, tool_use_id, type }`
622 - `BetaServerToolCaller20260120 object`
623
624 - `BetaAdvisorToolResultBlock object`
598625
599626 - `content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock`
600627
601 - `BetaAdvisorToolResultError object { error_code, type }`
628 - `BetaAdvisorToolResultError object`
602629
603630 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
604631
from line 645
618645
619646 - `type: "advisor_tool_result_error"`
620647
621 - `"advisor_tool_result_error"`
622
623 - `BetaAdvisorResultBlock object { stop_reason, text, type }`
648 default: advisor_tool_result_error
649
650 - `BetaAdvisorResultBlock object`
624651
625652 - `stop_reason: string or null`
626653
from line 657
630657
631658 - `type: "advisor_result"`
632659
633 - `"advisor_result"`
634
635 - `BetaAdvisorRedactedResultBlock object { encrypted_content, stop_reason, type }`
660 default: advisor_result
661
662 - `BetaAdvisorRedactedResultBlock object`
636663
637664 - `encrypted_content: string`
638665
from line 671
644671
645672 - `type: "advisor_redacted_result"`
646673
647 - `"advisor_redacted_result"`
674 default: advisor_redacted_result
648675
649676 - `tool_use_id: string`
650677
678 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
679
651680 - `type: "advisor_tool_result"`
652681
653 - `"advisor_tool_result"`
654
655 - `BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }`
682 default: advisor_tool_result
683
684 - `BetaCodeExecutionToolResultBlock object`
656685
657686 - `content: BetaCodeExecutionToolResultBlockContent`
658687
659688 Code execution result with encrypted stdout for PFC + web_search results.
660689
661 - `BetaCodeExecutionToolResultError object { error_code, type }`
690 - `BetaCodeExecutionToolResultError object`
662691
663692 - `error_code: BetaCodeExecutionToolResultErrorCode`
664693
from line 701
672701
673702 - `type: "code_execution_tool_result_error"`
674703
675 - `"code_execution_tool_result_error"`
676
677 - `BetaCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
704 default: code_execution_tool_result_error
705
706 - `BetaCodeExecutionResultBlock object`
678707
679708 - `content: array of BetaCodeExecutionOutputBlock`
680709
from line 711
682711
683712 - `type: "code_execution_output"`
684713
685 - `"code_execution_output"`
714 default: code_execution_output
686715
687716 - `return_code: number`
688717
from line 721
692721
693722 - `type: "code_execution_result"`
694723
695 - `"code_execution_result"`
696
697 - `BetaEncryptedCodeExecutionResultBlock object { content, encrypted_stdout, return_code, 2 more }`
724 default: code_execution_result
725
726 - `BetaEncryptedCodeExecutionResultBlock object`
698727
699728 Code execution result with encrypted stdout for PFC + web_search results.
700729
from line 733
704733
705734 - `type: "code_execution_output"`
706735
736 default: code_execution_output
737
707738 - `encrypted_stdout: string`
708739
709740 - `return_code: number`
from line 743
712743
713744 - `type: "encrypted_code_execution_result"`
714745
715 - `"encrypted_code_execution_result"`
746 default: encrypted_code_execution_result
716747
717748 - `tool_use_id: string`
718749
750 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
751
719752 - `type: "code_execution_tool_result"`
720753
721 - `"code_execution_tool_result"`
722
723 - `BetaBashCodeExecutionToolResultBlock object { content, tool_use_id, type }`
754 default: code_execution_tool_result
755
756 - `BetaBashCodeExecutionToolResultBlock object`
724757
725758 - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock`
726759
727 - `BetaBashCodeExecutionToolResultError object { error_code, type }`
760 - `BetaBashCodeExecutionToolResultError object`
728761
729762 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
730763
from line 773
740773
741774 - `type: "bash_code_execution_tool_result_error"`
742775
743 - `"bash_code_execution_tool_result_error"`
744
745 - `BetaBashCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
776 default: bash_code_execution_tool_result_error
777
778 - `BetaBashCodeExecutionResultBlock object`
746779
747780 - `content: array of BetaBashCodeExecutionOutputBlock`
748781
from line 783
750783
751784 - `type: "bash_code_execution_output"`
752785
753 - `"bash_code_execution_output"`
786 default: bash_code_execution_output
754787
755788 - `return_code: number`
756789
from line 793
760793
761794 - `type: "bash_code_execution_result"`
762795
763 - `"bash_code_execution_result"`
796 default: bash_code_execution_result
764797
765798 - `tool_use_id: string`
766799
800 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
801
767802 - `type: "bash_code_execution_tool_result"`
768803
769 - `"bash_code_execution_tool_result"`
770
771 - `BetaTextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }`
804 default: bash_code_execution_tool_result
805
806 - `BetaTextEditorCodeExecutionToolResultBlock object`
772807
773808 - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock`
774809
775 - `BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }`
810 - `BetaTextEditorCodeExecutionToolResultError object`
776811
777812 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
778813
from line 825
790825
791826 - `type: "text_editor_code_execution_tool_result_error"`
792827
793 - `"text_editor_code_execution_tool_result_error"`
794
795 - `BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }`
828 default: text_editor_code_execution_tool_result_error
829
830 - `BetaTextEditorCodeExecutionViewResultBlock object`
796831
797832 - `content: string`
798833
from line 847
812847
813848 - `type: "text_editor_code_execution_view_result"`
814849
815 - `"text_editor_code_execution_view_result"`
816
817 - `BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }`
850 default: text_editor_code_execution_view_result
851
852 - `BetaTextEditorCodeExecutionCreateResultBlock object`
818853
819854 - `is_file_update: boolean`
820855
821856 - `type: "text_editor_code_execution_create_result"`
822857
823 - `"text_editor_code_execution_create_result"`
824
825 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }`
858 default: text_editor_code_execution_create_result
859
860 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object`
826861
827862 - `lines: array of string or null`
828863
from line 871
836871
837872 - `type: "text_editor_code_execution_str_replace_result"`
838873
839 - `"text_editor_code_execution_str_replace_result"`
874 default: text_editor_code_execution_str_replace_result
840875
841876 - `tool_use_id: string`
842877
878 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
879
843880 - `type: "text_editor_code_execution_tool_result"`
844881
845 - `"text_editor_code_execution_tool_result"`
846
847 - `BetaToolSearchToolResultBlock object { content, tool_use_id, type }`
882 default: text_editor_code_execution_tool_result
883
884 - `BetaToolSearchToolResultBlock object`
848885
849886 - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock`
850887
851 - `BetaToolSearchToolResultError object { error_code, error_message, type }`
888 - `BetaToolSearchToolResultError object`
852889
853890 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
854891
from line 901
864901
865902 - `type: "tool_search_tool_result_error"`
866903
867 - `"tool_search_tool_result_error"`
868
869 - `BetaToolSearchToolSearchResultBlock object { tool_references, type }`
904 default: tool_search_tool_result_error
905
906 - `BetaToolSearchToolSearchResultBlock object`
870907
871908 - `tool_references: array of BetaToolReferenceBlock`
872909
873910 - `tool_name: string`
874911
912 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
913
875914 - `type: "tool_reference"`
876915
877 - `"tool_reference"`
916 default: tool_reference
878917
879918 - `type: "tool_search_tool_search_result"`
880919
881 - `"tool_search_tool_search_result"`
920 default: tool_search_tool_search_result
882921
883922 - `tool_use_id: string`
884923
924 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
925
885926 - `type: "tool_search_tool_result"`
886927
887 - `"tool_search_tool_result"`
888
889 - `BetaMCPToolUseBlock object { id, input, name, 2 more }`
928 default: tool_search_tool_result
929
930 - `BetaMCPToolUseBlock object`
890931
891932 - `id: string`
892933
934 pattern: ^[a-zA-Z0-9_-]+$
935
893936 - `input: map[unknown]`
894937
895938 - `name: string`
from line 945
902945
903946 - `type: "mcp_tool_use"`
904947
905 - `"mcp_tool_use"`
906
907 - `BetaMCPToolResultBlock object { content, is_error, tool_use_id, type }`
948 default: mcp_tool_use
949
950 - `BetaMCPToolResultBlock object`
908951
909952 - `content: string or array of BetaTextBlock`
910953
from line 963
920963
921964 - `text: string`
922965
966 maxLength: 5000000, minLength: 0
967
923968 - `type: "text"`
924969
970 default: text
971
925972 - `is_error: boolean`
926973
974 default: false
975
927976 - `tool_use_id: string`
928977
978 pattern: ^[a-zA-Z0-9_-]+$
979
929980 - `type: "mcp_tool_result"`
930981
931 - `"mcp_tool_result"`
932
933 - `BetaContainerUploadBlock object { file_id, type }`
982 default: mcp_tool_result
983
984 - `BetaContainerUploadBlock object`
934985
935986 Response model for a file uploaded to the container.
936987
from line 989
938989
939990 - `type: "container_upload"`
940991
941 - `"container_upload"`
942
943 - `BetaCompactionBlock object { content, encrypted_content, type }`
992 default: container_upload
993
994 - `BetaCompactionBlock object`
944995
945996 A compaction block returned when autocompact is triggered.
946997
from line 1009
9581009
9591010 - `type: "compaction"`
9601011
961 - `"compaction"`
962
963 - `BetaFallbackBlock object { from, to, trigger, type }`
1012 default: compaction
1013
1014 - `BetaFallbackBlock object`
9641015
9651016 Marks the point in `content` where one model's output gives way to the next.
9661017
from line 1137
10861137
10871138 - `type: "refusal"`
10881139
1089 - `"refusal"`
1140 default: refusal
10901141
10911142 - `type: "fallback"`
10921143
1093 - `"fallback"`
1144 default: fallback
10941145
10951146 - `context_management: BetaContextManagementResponse or null`
10961147
from line 1153
11021153
11031154 List of context management edits that were applied.
11041155
1105 - `BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }`
1156 - `BetaClearToolUses20250919EditResponse object`
11061157
11071158 - `cleared_input_tokens: number`
11081159
11091160 Number of input tokens cleared by this edit.
11101161
1162 minimum: 0
1163
11111164 - `cleared_tool_uses: number`
11121165
11131166 Number of tool uses that were cleared.
11141167
1168 minimum: 0
1169
11151170 - `type: "clear_tool_uses_20250919"`
11161171
11171172 The type of context management edit applied.
11181173
1119 - `"clear_tool_uses_20250919"`
1120
1121 - `BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }`
1174 default: clear_tool_uses_20250919
1175
1176 - `BetaClearThinking20251015EditResponse object`
11221177
11231178 - `cleared_input_tokens: number`
11241179
11251180 Number of input tokens cleared by this edit.
11261181
1182 minimum: 0
1183
11271184 - `cleared_thinking_turns: number`
11281185
11291186 Number of thinking turns that were cleared.
11301187
1188 minimum: 0
1189
11311190 - `type: "clear_thinking_20251015"`
11321191
11331192 The type of context management edit applied.
11341193
1135 - `"clear_thinking_20251015"`
1194 default: clear_thinking_20251015
11361195
11371196 - `diagnostics: BetaDiagnostics or null`
11381197
from line 1202
11431202
11441203 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.
11451204
1146 - `BetaCacheMissModelChanged object { cache_missed_input_tokens, type }`
1205 - `BetaCacheMissModelChanged object`
11471206
11481207 - `cache_missed_input_tokens: number`
11491208
from line 1210
11511210
11521211 - `type: "model_changed"`
11531212
1154 - `"model_changed"`
1155
1156 - `BetaCacheMissSystemChanged object { cache_missed_input_tokens, type }`
1213 default: model_changed
1214
1215 - `BetaCacheMissSystemChanged object`
11571216
11581217 - `cache_missed_input_tokens: number`
11591218
from line 1220
11611220
11621221 - `type: "system_changed"`
11631222
1164 - `"system_changed"`
1165
1166 - `BetaCacheMissToolsChanged object { cache_missed_input_tokens, type }`
1223 default: system_changed
1224
1225 - `BetaCacheMissToolsChanged object`
11671226
11681227 - `cache_missed_input_tokens: number`
11691228
from line 1230
11711230
11721231 - `type: "tools_changed"`
11731232
1174 - `"tools_changed"`
1175
1176 - `BetaCacheMissMessagesChanged object { cache_missed_input_tokens, type }`
1233 default: tools_changed
1234
1235 - `BetaCacheMissMessagesChanged object`
11771236
11781237 - `cache_missed_input_tokens: number`
11791238
from line 1240
11811240
11821241 - `type: "messages_changed"`
11831242
1184 - `"messages_changed"`
1185
1186 - `BetaCacheMissPreviousMessageNotFound object { type }`
1243 default: messages_changed
1244
1245 - `BetaCacheMissPreviousMessageNotFound object`
11871246
11881247 - `type: "previous_message_not_found"`
11891248
1190 - `"previous_message_not_found"`
1191
1192 - `BetaCacheMissUnavailable object { type }`
1249 default: previous_message_not_found
1250
1251 - `BetaCacheMissUnavailable object`
11931252
11941253 - `type: "unavailable"`
11951254
1196 - `"unavailable"`
1255 default: unavailable
11971256
11981257 - `model: Model`
11991258
from line 1266
12071266
12081267 This will always be `"assistant"`.
12091268
1210 - `"assistant"`
1269 default: assistant
12111270
12121271 - `stop_details: BetaRefusalStopDetails or null`
12131272
from line 1353
12941353
12951354 - `type: "refusal"`
12961355
1297 - `"refusal"`
1356 default: refusal
12981357
12991358 - `stop_reason: BetaStopReason or null`
13001359
from line 1399
13401399
13411400 For Messages, this is always `"message"`.
13421401
1343 - `"message"`
1402 default: message
13441403
13451404 - `usage: BetaUsage`
13461405
from line 1421
13621421
13631422 The number of input tokens used to create the 1 hour cache entry.
13641423
1424 default: 0, minimum: 0
1425
13651426 - `ephemeral_5m_input_tokens: number`
13661427
13671428 The number of input tokens used to create the 5 minute cache entry.
13681429
1430 default: 0, minimum: 0
1431
13691432 - `cache_creation_input_tokens: number or null`
13701433
13711434 The number of input tokens used to create the cache entry.
13721435
1436 minimum: 0
1437
13731438 - `cache_read_input_tokens: number or null`
13741439
13751440 The number of input tokens read from the cache.
1441
1442 minimum: 0
13761443
13771444 - `fallback_credit: BetaFallbackCreditUsage or null`
13781445
from line 1454
13871454 resulting shift is zero because there was nothing to move. `not_applied`:
13881455 no reprice was applied; the arm's `reason` says why.
13891456
1390 - `BetaFallbackCreditRedeemed object { type }`
1457 - `BetaFallbackCreditRedeemed object`
13911458
13921459 The reprice was applied: the retry is billed as if the conversation
13931460 had been on the retry model all along.
13941461
13951462 - `type: "redeemed"`
13961463
1397 - `"redeemed"`
1398
1399 - `BetaFallbackCreditNotApplied object { reason, type, remove_to_redeem }`
1464 default: redeemed
1465
1466 - `BetaFallbackCreditNotApplied object`
14001467
14011468 No reprice was applied; `reason` says why.
14021469
from line 1500
14331500
14341501 - `type: "not_applied"`
14351502
1436 - `"not_applied"`
1503 default: not_applied
14371504
14381505 - `remove_to_redeem: optional array of string or null`
14391506
from line 1521
14541521
14551522 The number of input tokens which were used.
14561523
1524 minimum: 0
1525
14571526 - `iterations: BetaIterationsUsage or null`
14581527
14591528 Per-iteration token usage breakdown.
from line 1533
14641533 - Calculate the true context window size from the last iteration
14651534 - Understand token accumulation across server-side tool use loops
14661535
1467 - `BetaMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
1536 - `BetaMessageIterationUsage object`
14681537
14691538 Token usage for a sampling iteration.
14701539
from line 1545
14761545
14771546 The number of input tokens used to create the cache entry.
14781547
1548 default: 0, minimum: 0
1549
14791550 - `cache_read_input_tokens: number`
14801551
14811552 The number of input tokens read from the cache.
14821553
1554 default: 0, minimum: 0
1555
14831556 - `input_tokens: number`
14841557
14851558 The number of input tokens which were used.
14861559
1560 minimum: 0
1561
14871562 - `model: Model`
14881563
14891564 The model that will complete your prompt.
from line 1569
14941569
14951570 The number of output tokens which were used.
14961571
1572 minimum: 0
1573
14971574 - `type: "message"`
14981575
14991576 Usage for a sampling iteration
15001577
1501 - `"message"`
1502
1503 - `BetaCompactionIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }`
1578 default: message
1579
1580 - `BetaCompactionIterationUsage object`
15041581
15051582 Token usage for a compaction iteration.
15061583
from line 1589
15121589
15131590 The number of input tokens used to create the cache entry.
15141591
1592 default: 0, minimum: 0
1593
15151594 - `cache_read_input_tokens: number`
15161595
15171596 The number of input tokens read from the cache.
15181597
1598 default: 0, minimum: 0
1599
15191600 - `input_tokens: number`
15201601
15211602 The number of input tokens which were used.
15221603
1604 minimum: 0
1605
15231606 - `output_tokens: number`
15241607
15251608 The number of output tokens which were used.
15261609
1610 minimum: 0
1611
15271612 - `type: "compaction"`
15281613
15291614 Usage for a compaction iteration
15301615
1531 - `"compaction"`
1532
1533 - `BetaAdvisorMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
1616 default: compaction
1617
1618 - `BetaAdvisorMessageIterationUsage object`
15341619
15351620 Token usage for an advisor sub-inference iteration.
15361621
from line 1627
15421627
15431628 The number of input tokens used to create the cache entry.
15441629
1630 default: 0, minimum: 0
1631
15451632 - `cache_read_input_tokens: number`
15461633
15471634 The number of input tokens read from the cache.
15481635
1636 default: 0, minimum: 0
1637
15491638 - `input_tokens: number`
15501639
15511640 The number of input tokens which were used.
15521641
1642 minimum: 0
1643
15531644 - `model: Model`
15541645
15551646 The model that will complete your prompt.
from line 1651
15601651
15611652 The number of output tokens which were used.
15621653
1654 minimum: 0
1655
15631656 - `type: "advisor_message"`
15641657
15651658 Usage for an advisor sub-inference iteration
15661659
1567 - `"advisor_message"`
1568
1569 - `BetaFallbackMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
1660 default: advisor_message
1661
1662 - `BetaFallbackMessageIterationUsage object`
15701663
15711664 Token usage for the fallback-model attempt of a server-side fallback request.
15721665
from line 1676
15831676
15841677 The number of input tokens used to create the cache entry.
15851678
1679 default: 0, minimum: 0
1680
15861681 - `cache_read_input_tokens: number`
15871682
15881683 The number of input tokens read from the cache.
15891684
1685 default: 0, minimum: 0
1686
15901687 - `input_tokens: number`
15911688
15921689 The number of input tokens which were used.
15931690
1691 minimum: 0
1692
15941693 - `model: Model`
15951694
15961695 The model that will complete your prompt.
from line 1700
16011700
16021701 The number of output tokens which were used.
16031702
1703 minimum: 0
1704
16041705 - `type: "fallback_message"`
16051706
16061707 Usage for the fallback-model attempt that served the response
16071708
1608 - `"fallback_message"`
1709 default: fallback_message
16091710
16101711 - `output_tokens: number`
16111712
16121713 The number of output tokens which were used.
1714
1715 minimum: 0
16131716
16141717 - `output_tokens_details: BetaOutputTokensDetails or null`
16151718
from line 1734
16311734 generation count by a small number of tokens. Always ≤ `output_tokens`;
16321735 `output_tokens - thinking_tokens` approximates the non-reasoning output.
16331736
1737 default: 0, minimum: 0
1738
16341739 - `server_tool_use: BetaServerToolUsage or null`
16351740
16361741 The number of server tool requests.
from line 1744
16391744
16401745 The number of web fetch tool requests.
16411746
1747 default: 0, minimum: 0
1748
16421749 - `web_search_requests: number`
16431750
16441751 The number of web search tool requests.
16451752
1753 default: 0, minimum: 0
1754
16461755 - `service_tier: "standard" or "priority" or "batch" or null`
16471756
16481757 If the request used the priority, standard, or batch tier.
from line 1772
16631772
16641773 - `type: "succeeded"`
16651774
1666 - `"succeeded"`
1667
1668 - `BetaMessageBatchErroredResult object { error, type }`
1775 default: succeeded
1776
1777 - `BetaMessageBatchErroredResult object`
16691778
16701779 - `error: BetaErrorResponse`
16711780
16721781 - `error: BetaError`
16731782
1674 - `BetaInvalidRequestError object { message, type }`
1783 - `BetaInvalidRequestError object`
16751784
16761785 - `message: string`
16771786
1787 default: Invalid request
1788
16781789 - `type: "invalid_request_error"`
16791790
1680 - `"invalid_request_error"`
1681
1682 - `BetaAuthenticationError object { message, type }`
1791 default: invalid_request_error
1792
1793 - `BetaAuthenticationError object`
16831794
16841795 - `message: string`
16851796
1797 default: Authentication error
1798
16861799 - `type: "authentication_error"`
16871800
1688 - `"authentication_error"`
1689
1690 - `BetaBillingError object { message, type }`
1801 default: authentication_error
1802
1803 - `BetaBillingError object`
16911804
16921805 - `message: string`
16931806
1807 default: Billing error
1808
16941809 - `type: "billing_error"`
16951810
1696 - `"billing_error"`
1697
1698 - `BetaPermissionError object { message, type }`
1811 default: billing_error
1812
1813 - `BetaPermissionError object`
16991814
17001815 - `message: string`
17011816
1817 default: Permission denied
1818
17021819 - `type: "permission_error"`
17031820
1704 - `"permission_error"`
1705
1706 - `BetaNotFoundError object { message, type }`
1821 default: permission_error
1822
1823 - `BetaNotFoundError object`
17071824
17081825 - `message: string`
17091826
1827 default: Not found
1828
17101829 - `type: "not_found_error"`
17111830
1712 - `"not_found_error"`
1713
1714 - `BetaRateLimitError object { message, type }`
1831 default: not_found_error
1832
1833 - `BetaRateLimitError object`
17151834
17161835 - `message: string`
17171836
1837 default: Rate limited
1838
17181839 - `type: "rate_limit_error"`
17191840
1720 - `"rate_limit_error"`
1721
1722 - `BetaGatewayTimeoutError object { message, type }`
1841 default: rate_limit_error
1842
1843 - `BetaGatewayTimeoutError object`
17231844
17241845 - `message: string`
17251846
1847 default: Request timeout
1848
17261849 - `type: "timeout_error"`
17271850
1728 - `"timeout_error"`
1729
1730 - `BetaAPIError object { message, type }`
1851 default: timeout_error
1852
1853 - `BetaAPIError object`
17311854
17321855 - `message: string`
17331856
1857 default: Internal server error
1858
17341859 - `type: "api_error"`
17351860
1736 - `"api_error"`
1737
1738 - `BetaOverloadedError object { message, type }`
1861 default: api_error
1862
1863 - `BetaOverloadedError object`
17391864
17401865 - `message: string`
17411866
1867 default: Overloaded
1868
17421869 - `type: "overloaded_error"`
17431870
1744 - `"overloaded_error"`
1871 default: overloaded_error
17451872
17461873 - `request_id: string or null`
17471874
17481875 - `type: "error"`
17491876
1750 - `"error"`
1877 default: error
17511878
17521879 - `type: "errored"`
17531880
1754 - `"errored"`
1755
1756 - `BetaMessageBatchCanceledResult object { type }`
1881 default: errored
1882
1883 - `BetaMessageBatchCanceledResult object`
17571884
17581885 - `type: "canceled"`
17591886
1760 - `"canceled"`
1761
1762 - `BetaMessageBatchExpiredResult object { type }`
1887 default: canceled
1888
1889 - `BetaMessageBatchExpiredResult object`
17631890
17641891 - `type: "expired"`
17651892
1766 - `"expired"`
1767
1768### Example
1769
1770```http
1893 default: expired
1894
1895## Example
1896
1897```bash
17711898curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \
17721899 -H 'anthropic-version: 2023-06-01' \
17731900 -H 'anthropic-beta: message-batches-2024-09-24' \
17741901
api/beta/messages/batches/retrieve Changed · +34 / -19 lines
# Retrieve a Message Batch ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Retrieve a Message Batch ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Retrieve a Message Batch
3url: https://platform.claude.com/docs/en/api/beta/messages/batches/retrieve
4---
1# Retrieve a Message Batch
52
6## Retrieve a Message Batch
3**GET** `/v1/messages/batches/{message_batch_id}`
74
8**get** `/v1/messages/batches/{message_batch_id}`
9
105This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response.
116
127Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
138
14### Path Parameters
9## Path parameters
1510
1611- `message_batch_id: string`
1712
1813 ID of the Message Batch.
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
100- `BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }`
95- `BetaMessageBatch object`
10196
10297 - `id: string`
10398
from line 104
109104
110105 RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
111106
107 format: date-time
108
112109 - `cancel_initiated_at: string or null`
113110
114111 RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
115112
113 format: date-time
114
116115 - `created_at: string`
117116
118117 RFC 3339 datetime string representing the time at which the Message Batch was created.
119118
119 format: date-time
120
120121 - `ended_at: string or null`
121122
122123 RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
from line 124
123124
124125 Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
125126
127 format: date-time
128
126129 - `expires_at: string`
127130
128131 RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
129132
133 format: date-time
134
130135 - `processing_status: "in_progress" or "canceling" or "ended"`
131136
132137 Processing status of the Message Batch.
from line 154
149154
150155 This is zero until processing of the entire Message Batch has ended.
151156
157 default: 0
158
152159 - `errored: number`
153160
154161 Number of requests in the Message Batch that encountered an error.
from line 162
155162
156163 This is zero until processing of the entire Message Batch has ended.
157164
165 default: 0
166
158167 - `expired: number`
159168
160169 Number of requests in the Message Batch that have expired.
from line 170
161170
162171 This is zero until processing of the entire Message Batch has ended.
163172
173 default: 0
174
164175 - `processing: number`
165176
166177 Number of requests in the Message Batch that are processing.
167178
179 default: 0
180
168181 - `succeeded: number`
169182
170183 Number of requests in the Message Batch that have completed successfully.
from line 184
171184
172185 This is zero until processing of the entire Message Batch has ended.
173186
187 default: 0
188
174189 - `results_url: string or null`
175190
176191 URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
from line 198
183198
184199 For Message Batches, this is always `"message_batch"`.
185200
186 - `"message_batch"`
201 default: message_batch
187202
188### Example
203## Example
189204
190```http
205```bash
191206curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
192207 -H 'anthropic-version: 2023-06-01' \
193208 -H 'anthropic-beta: message-batches-2024-09-24' \
from line 209
194209 -H "X-Api-Key: $ANTHROPIC_API_KEY"
195210```
196211
197#### Response
212### Response (200)
198213
199214```json
200215{
api/beta/messages/count_tokens Changed · +392 / -491 lines
# Count tokens in a Message ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Count tokens in a Message ### 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: Count tokens in a Message
3url: https://platform.claude.com/docs/en/api/beta/messages/count_tokens
4---
5
6## Count tokens in a Message
7
8**post** `/v1/messages/count_tokens`
1# Count tokens in a Message
2
3**POST** `/v1/messages/count_tokens`
94
105Count the number of tokens in a Message.
116
from line 8
138
149Learn more about token counting in our [user guide](https://platform.claude.com/docs/en/build-with-claude/token-counting)
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 90
9590
9691 The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header.
9792
98### Body Parameters
93## Body parameters
9994
10095- `messages: array of BetaMessageParam`
10196
from line 149
154149
155150 - `array of BetaContentBlockParam`
156151
157 - `BetaTextBlockParam object { text, type, cache_control, citations }`
152 - `BetaTextBlockParam object`
158153
159154 - `text: string`
160155
156 minLength: 1
157
161158 - `type: "text"`
162159
163 - `"text"`
164
165160 - `cache_control: optional BetaCacheControlEphemeral or null`
166161
167162 Create a cache control breakpoint at this content block.
168163
169164 - `type: "ephemeral"`
170
171 - `"ephemeral"`
172165
173166 - `ttl: optional "5m" or "1h"`
174167
from line 180
187180
188181 - `citations: optional array of BetaTextCitationParam or null`
189182
190 - `BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
183 - `BetaCitationCharLocationParam object`
191184
192185 - `cited_text: string`
193186
194187 - `document_index: number`
195188
189 minimum: 0
190
196191 - `document_title: string or null`
197192
193 maxLength: 500, minLength: 1
194
198195 - `end_char_index: number`
199196
200197 - `start_char_index: number`
201198
199 minimum: 0
200
202201 - `type: "char_location"`
203202
204 - `"char_location"`
205
206 - `BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
203 - `BetaCitationPageLocationParam object`
207204
208205 - `cited_text: string`
209206
210207 - `document_index: number`
211208
209 minimum: 0
210
212211 - `document_title: string or null`
213212
213 maxLength: 500, minLength: 1
214
214215 - `end_page_number: number`
215216
216217 - `start_page_number: number`
217218
219 minimum: 1
220
218221 - `type: "page_location"`
219222
220 - `"page_location"`
221
222 - `BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
223 - `BetaCitationContentBlockLocationParam object`
223224
224225 - `cited_text: string`
225226
from line 230
229230
230231 - `document_index: number`
231232
233 minimum: 0
234
232235 - `document_title: string or null`
233236
237 maxLength: 500, minLength: 1
238
234239 - `end_block_index: number`
235240
236241 Exclusive 0-based end index of the cited block range in the source's `content` array.
from line 246
241246
242247 0-based index of the first cited block in the source's `content` array.
243248
249 minimum: 0
250
244251 - `type: "content_block_location"`
245252
246 - `"content_block_location"`
247
248 - `BetaCitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
253 - `BetaCitationWebSearchResultLocationParam object`
249254
250255 - `cited_text: string`
251256
from line 258
253258
254259 - `title: string or null`
255260
261 maxLength: 512, minLength: 1
262
256263 - `type: "web_search_result_location"`
257264
258 - `"web_search_result_location"`
259
260265 - `url: string`
261266
262 - `BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
267 minLength: 1
268
269 - `BetaCitationSearchResultLocationParam object`
263270
264271 - `cited_text: string`
265272
from line 286
279286
280287 Counted separately from `document_index`; server-side web search results are not included in this count.
281288
289 minimum: 0
290
282291 - `source: string`
283292
284293 - `start_block_index: number`
285294
286295 0-based index of the first cited block in the source's `content` array.
287296
297 minimum: 0
298
288299 - `title: string or null`
289300
290301 - `type: "search_result_location"`
291302
292 - `"search_result_location"`
293
294 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
303 - `BetaImageBlockParam object`
295304
296305 - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource`
297306
298 - `BetaBase64ImageSource object { data, media_type, type }`
307 - `BetaBase64ImageSource object`
299308
300309 - `data: string`
301310
311 format: byte
312
302313 - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
303314
304315 - `"image/jpeg"`
from line 322
311322
312323 - `type: "base64"`
313324
314 - `"base64"`
315
316 - `BetaURLImageSource object { type, url }`
325 - `BetaURLImageSource object`
317326
318327 - `type: "url"`
319328
320 - `"url"`
321
322329 - `url: string`
323330
324 - `BetaFileImageSource object { file_id, type }`
331 - `BetaFileImageSource object`
325332
326333 - `file_id: string`
327334
328335 - `type: "file"`
329336
330 - `"file"`
331
332337 - `type: "image"`
333338
334 - `"image"`
335
336339 - `cache_control: optional BetaCacheControlEphemeral or null`
337340
338341 Create a cache control breakpoint at this content block.
from line 352
349352
350353 - `"error"`
351354
352 - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }`
355 - `BetaRequestDocumentBlock object`
353356
354357 - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more`
355358
356 - `BetaBase64PDFSource object { data, media_type, type }`
359 - `BetaBase64PDFSource object`
357360
358361 - `data: string`
359362
363 format: byte
364
360365 - `media_type: "application/pdf"`
361366
362 - `"application/pdf"`
363
364367 - `type: "base64"`
365368
366 - `"base64"`
367
368 - `BetaPlainTextSource object { data, media_type, type }`
369 - `BetaPlainTextSource object`
369370
370371 - `data: string`
371372
372373 - `media_type: "text/plain"`
373374
374 - `"text/plain"`
375
376375 - `type: "text"`
377376
378 - `"text"`
379
380 - `BetaContentBlockSource object { content, type }`
377 - `BetaContentBlockSource object`
381378
382379 - `content: string or array of BetaContentBlockSourceContent`
383380
from line 382
385382
386383 - `BetaContentBlockSourceContent = array of BetaContentBlockSourceContent`
387384
388 - `BetaTextBlockParam object { text, type, cache_control, citations }`
389
390 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
385 - `BetaTextBlockParam object`
386
387 - `BetaImageBlockParam object`
391388
392389 - `type: "content"`
393390
394 - `"content"`
395
396 - `BetaURLPDFSource object { type, url }`
391 - `BetaURLPDFSource object`
397392
398393 - `type: "url"`
399394
400 - `"url"`
401
402395 - `url: string`
403396
404 - `BetaFileDocumentSource object { file_id, type }`
397 - `BetaFileDocumentSource object`
405398
406399 - `file_id: string`
407400
408401 - `type: "file"`
409402
410 - `"file"`
411
412403 - `type: "document"`
413404
414 - `"document"`
415
416405 - `cache_control: optional BetaCacheControlEphemeral or null`
417406
418407 Create a cache control breakpoint at this content block.
from line 412
423412
424413 - `context: optional string or null`
425414
415 minLength: 1
416
426417 - `title: optional string or null`
427418
428 - `BetaSearchResultBlockParam object { content, source, title, 3 more }`
419 maxLength: 500, minLength: 1
420
421 - `BetaSearchResultBlockParam object`
429422
430423 - `content: array of BetaTextBlockParam`
431424
432425 - `text: string`
433426
427 minLength: 1
428
434429 - `type: "text"`
435430
436431 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 440
445440
446441 - `type: "search_result"`
447442
448 - `"search_result"`
449
450443 - `cache_control: optional BetaCacheControlEphemeral or null`
451444
452445 Create a cache control breakpoint at this content block.
453446
454447 - `citations: optional BetaCitationsConfigParam`
455448
456 - `BetaThinkingBlockParam object { signature, thinking, type }`
449 - `BetaThinkingBlockParam object`
457450
458451 - `signature: string`
459452
from line 460
467460
468461 - `type: "thinking"`
469462
470 - `"thinking"`
471
472 - `BetaRedactedThinkingBlockParam object { data, type }`
463 - `BetaRedactedThinkingBlockParam object`
473464
474465 - `data: string`
475466
from line 468
477468
478469 - `type: "redacted_thinking"`
479470
480 - `"redacted_thinking"`
481
482 - `BetaToolUseBlockParam object { id, input, name, 4 more }`
471 - `BetaToolUseBlockParam object`
483472
484473 - `id: string`
485474
475 pattern: ^[a-zA-Z0-9_-]+$
476
486477 - `input: map[unknown]`
487478
488479 - `name: string`
489480
481 maxLength: 200, minLength: 1
482
490483 - `type: "tool_use"`
491484
492 - `"tool_use"`
493
494485 - `cache_control: optional BetaCacheControlEphemeral or null`
495486
496487 Create a cache control breakpoint at this content block.
from line 490
499490
500491 Tool invocation directly from the model.
501492
502 - `BetaDirectCaller object { type }`
493 - `BetaDirectCaller object`
503494
504495 Tool invocation directly from the model.
505496
506497 - `type: "direct"`
507498
508 - `"direct"`
509
510 - `BetaServerToolCaller object { tool_id, type }`
499 - `BetaServerToolCaller object`
511500
512501 Tool invocation generated by a server-side tool.
513502
514503 - `tool_id: string`
515504
505 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
506
516507 - `type: "code_execution_20250825"`
517508
518 - `"code_execution_20250825"`
519
520 - `BetaServerToolCaller20260120 object { tool_id, type }`
509 - `BetaServerToolCaller20260120 object`
521510
522511 - `tool_id: string`
523512
513 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
514
524515 - `type: "code_execution_20260120"`
525516
526 - `"code_execution_20260120"`
527
528517 - `toolset_name: optional string or null`
529518
530519 For a toolset member tool_use, the toolset family this member belongs to.
531520
532 - `BetaToolResultBlockParam object { tool_use_id, type, cache_control, 3 more }`
521 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
522
523 - `BetaToolResultBlockParam object`
533524
534525 - `tool_use_id: string`
535526
527 pattern: ^[a-zA-Z0-9_-]+$
528
536529 - `type: "tool_result"`
537530
538 - `"tool_result"`
539
540531 - `cache_control: optional BetaCacheControlEphemeral or null`
541532
542533 Create a cache control breakpoint at this content block.
from line 538
547538
548539 - `array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 3 more`
549540
550 - `BetaTextBlockParam object { text, type, cache_control, citations }`
551
552 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
553
554 - `BetaSearchResultBlockParam object { content, source, title, 3 more }`
555
556 - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }`
557
558 - `BetaToolReferenceBlockParam object { tool_name, type, cache_control }`
541 - `BetaTextBlockParam object`
542
543 - `BetaImageBlockParam object`
544
545 - `BetaSearchResultBlockParam object`
546
547 - `BetaRequestDocumentBlock object`
548
549 - `BetaToolReferenceBlockParam object`
559550
560551 Tool reference block that can be included in tool_result content.
561552
562553 - `tool_name: string`
563554
555 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
556
564557 - `type: "tool_reference"`
565558
566 - `"tool_reference"`
567
568559 - `cache_control: optional BetaCacheControlEphemeral or null`
569560
570561 Create a cache control breakpoint at this content block.
571562
572 - `BetaBrowserStateBlockParam object { tabs, type, cache_control, state_changes }`
563 - `BetaBrowserStateBlockParam object`
573564
574565 The caller's browser state after a browser toolset member call —
575566 the full inventory of open tabs, which tab is active, and any side
from line 574
583574
584575 All tabs open in the browser after this call — the full inventory, not a delta. May be empty. Whenever non-empty, exactly one entry carries `active: true`.
585576
577 maxItems: 100
578
586579 - `tab_id: string`
587580
588581 The caller-assigned identifier for this tab, unique within the inventory.
589582
583 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
584
590585 - `title: string`
591586
592587 The title of the page the tab is showing. May be empty.
593588
589 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
590
594591 - `url: string`
595592
596593 The URL of the page the tab is showing. May be empty.
597594
595 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
596
598597 - `active: optional boolean`
599598
600599 Whether this tab is the active tab after this call. Whenever `tabs` is non-empty, exactly one entry is marked `active: true`.
601600
602601 - `type: "browser_state"`
603602
604 - `"browser_state"`
605
606603 - `cache_control: optional BetaCacheControlEphemeral or null`
607604
608605 Create a cache control breakpoint at this content block.
from line 608
611608
612609 Tabs opened and download state changes during this call. "Nothing to report" is expressed by omitting the field, never by an empty list.
613610
614 - `BetaBrowserStateChangeTabOpened object { tab_id, type }`
611 maxItems: 200, minItems: 1
612
613 - `BetaBrowserStateChangeTabOpened object`
615614
616615 A tab this call's execution opened that remains open at its end —
617616 the creation delta of the `tabs` inventory, not an event log.
from line 624
625624
626625 The `tab_id` of the opened tab, present in `tabs`.
627626
627 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
628
628629 - `type: "tab_opened"`
629630
630 - `"tab_opened"`
631
632 - `BetaBrowserStateChangeDownloadStarted object { download_id, type, url }`
631 - `BetaBrowserStateChangeDownloadStarted object`
633632
634633 A file download that started during this call.
635634
from line 636
637636
638637 The caller-assigned identifier for this download, stable across the state changes reporting it.
639638
639 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
640
640641 - `type: "download_started"`
641642
642 - `"download_started"`
643
644643 - `url: string`
645644
646645 The final post-redirect URL the download was served from.
647646
648 - `BetaBrowserStateChangeDownloadCompleted object { download_id, type, url, 2 more }`
647 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
648
649 - `BetaBrowserStateChangeDownloadCompleted object`
649650
650651 A file download that finished during this call, reported with the
651652 same `download_id` as its `download_started` — or without a prior
from line 657
656657
657658 The caller-assigned identifier for this download, stable across the state changes reporting it.
658659
660 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
661
659662 - `type: "download_completed"`
660663
661 - `"download_completed"`
662
663664 - `url: string`
664665
665666 The final post-redirect URL the download was served from.
666667
668 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
669
667670 - `path: optional string or null`
668671
669672 Where the executor saved the file, on the executor's filesystem. Only included when another tool in the same environment can read the file at that path.
670673
674 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096
675
671676 - `size_bytes: optional number or null`
672677
673678 The completed download's size.
674679
675 - `BetaBrowserStateChangeDownloadFailed object { download_id, type, url, error }`
680 minimum: 0
681
682 - `BetaBrowserStateChangeDownloadFailed object`
676683
677684 A file download that failed — or was cancelled — during this call.
678685
from line 687
680687
681688 The caller-assigned identifier for this download, stable across the state changes reporting it.
682689
690 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
691
683692 - `type: "download_failed"`
684693
685 - `"download_failed"`
686
687694 - `url: string`
688695
689696 The final post-redirect URL the download was served from.
690697
698 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
699
691700 - `error: optional string or null`
692701
693702 The failure or cancellation detail, when known.
694703
704 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096
705
695706 - `is_error: optional boolean`
696707
697708 - `toolset_name: optional string or null`
698709
699710 For a toolset member tool_result, the toolset family of the paired tool_use.
700711
701 - `BetaServerToolUseBlockParam object { id, input, name, 3 more }`
712 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
713
714 - `BetaServerToolUseBlockParam object`
702715
703716 - `id: string`
704717
718 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
719
705720 - `input: map[unknown]`
706721
707722 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 739
724739
725740 - `type: "server_tool_use"`
726741
727 - `"server_tool_use"`
728
729742 - `cache_control: optional BetaCacheControlEphemeral or null`
730743
731744 Create a cache control breakpoint at this content block.
from line 747
734747
735748 Tool invocation directly from the model.
736749
737 - `BetaDirectCaller object { type }`
750 - `BetaDirectCaller object`
738751
739752 Tool invocation directly from the model.
740753
741 - `BetaServerToolCaller object { tool_id, type }`
754 - `BetaServerToolCaller object`
742755
743756 Tool invocation generated by a server-side tool.
744757
745 - `BetaServerToolCaller20260120 object { tool_id, type }`
746
747 - `BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }`
758 - `BetaServerToolCaller20260120 object`
759
760 - `BetaWebSearchToolResultBlockParam object`
748761
749762 - `content: BetaWebSearchToolResultBlockParamContent`
750763
from line 769
756769
757770 - `type: "web_search_result"`
758771
759 - `"web_search_result"`
760
761772 - `url: string`
762773
763774 - `page_age: optional string or null`
764775
765 - `BetaWebSearchToolRequestError object { error_code, type }`
776 - `BetaWebSearchToolRequestError object`
766777
767778 - `error_code: BetaWebSearchToolResultErrorCode`
768779
from line 791
780791
781792 - `type: "web_search_tool_result_error"`
782793
783 - `"web_search_tool_result_error"`
784
785794 - `tool_use_id: string`
786795
796 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
797
787798 - `type: "web_search_tool_result"`
788799
789 - `"web_search_tool_result"`
790
791800 - `cache_control: optional BetaCacheControlEphemeral or null`
792801
793802 Create a cache control breakpoint at this content block.
from line 805
796805
797806 Tool invocation directly from the model.
798807
799 - `BetaDirectCaller object { type }`
808 - `BetaDirectCaller object`
800809
801810 Tool invocation directly from the model.
802811
803 - `BetaServerToolCaller object { tool_id, type }`
812 - `BetaServerToolCaller object`
804813
805814 Tool invocation generated by a server-side tool.
806815
807 - `BetaServerToolCaller20260120 object { tool_id, type }`
808
809 - `BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }`
816 - `BetaServerToolCaller20260120 object`
817
818 - `BetaWebFetchToolResultBlockParam object`
810819
811820 - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam`
812821
813 - `BetaWebFetchToolResultErrorBlockParam object { error_code, type }`
822 - `BetaWebFetchToolResultErrorBlockParam object`
814823
815824 - `error_code: BetaWebFetchToolResultErrorCode`
816825
from line 843
834843
835844 - `type: "web_fetch_tool_result_error"`
836845
837 - `"web_fetch_tool_result_error"`
838
839 - `BetaWebFetchBlockParam object { content, type, url, retrieved_at }`
846 - `BetaWebFetchBlockParam object`
840847
841848 - `content: BetaRequestDocumentBlock`
842849
843850 - `type: "web_fetch_result"`
844851
845 - `"web_fetch_result"`
846
847852 - `url: string`
848853
849854 Fetched content URL
from line 859
854859
855860 - `tool_use_id: string`
856861
862 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
863
857864 - `type: "web_fetch_tool_result"`
858865
859 - `"web_fetch_tool_result"`
860
861866 - `cache_control: optional BetaCacheControlEphemeral or null`
862867
863868 Create a cache control breakpoint at this content block.
from line 871
866871
867872 Tool invocation directly from the model.
868873
869 - `BetaDirectCaller object { type }`
874 - `BetaDirectCaller object`
870875
871876 Tool invocation directly from the model.
872877
873 - `BetaServerToolCaller object { tool_id, type }`
878 - `BetaServerToolCaller object`
874879
875880 Tool invocation generated by a server-side tool.
876881
877 - `BetaServerToolCaller20260120 object { tool_id, type }`
878
879 - `BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }`
882 - `BetaServerToolCaller20260120 object`
883
884 - `BetaAdvisorToolResultBlockParam object`
880885
881886 - `content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam`
882887
883 - `BetaAdvisorToolResultErrorParam object { error_code, type }`
888 - `BetaAdvisorToolResultErrorParam object`
884889
885890 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
886891
from line 905
900905
901906 - `type: "advisor_tool_result_error"`
902907
903 - `"advisor_tool_result_error"`
904
905 - `BetaAdvisorResultBlockParam object { text, type, stop_reason }`
908 - `BetaAdvisorResultBlockParam object`
906909
907910 - `text: string`
908911
909912 - `type: "advisor_result"`
910913
911 - `"advisor_result"`
912
913914 - `stop_reason: optional string or null`
914915
915 - `BetaAdvisorRedactedResultBlockParam object { encrypted_content, type, stop_reason }`
916 - `BetaAdvisorRedactedResultBlockParam object`
916917
917918 - `encrypted_content: string`
918919
from line 921
920921
921922 - `type: "advisor_redacted_result"`
922923
923 - `"advisor_redacted_result"`
924
925924 - `stop_reason: optional string or null`
926925
927926 - `tool_use_id: string`
928927
928 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
929
929930 - `type: "advisor_tool_result"`
930931
931 - `"advisor_tool_result"`
932
933932 - `cache_control: optional BetaCacheControlEphemeral or null`
934933
935934 Create a cache control breakpoint at this content block.
936935
937 - `BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
936 - `BetaCodeExecutionToolResultBlockParam object`
938937
939938 - `content: BetaCodeExecutionToolResultBlockParamContent`
940939
941940 Code execution result with encrypted stdout for PFC + web_search results.
942941
943 - `BetaCodeExecutionToolResultErrorParam object { error_code, type }`
942 - `BetaCodeExecutionToolResultErrorParam object`
944943
945944 - `error_code: BetaCodeExecutionToolResultErrorCode`
946945
from line 953
954953
955954 - `type: "code_execution_tool_result_error"`
956955
957 - `"code_execution_tool_result_error"`
958
959 - `BetaCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }`
956 - `BetaCodeExecutionResultBlockParam object`
960957
961958 - `content: array of BetaCodeExecutionOutputBlockParam`
962959
from line 961
964961
965962 - `type: "code_execution_output"`
966963
967 - `"code_execution_output"`
968
969964 - `return_code: number`
970965
971966 - `stderr: string`
from line 969
974969
975970 - `type: "code_execution_result"`
976971
977 - `"code_execution_result"`
978
979 - `BetaEncryptedCodeExecutionResultBlockParam object { content, encrypted_stdout, return_code, 2 more }`
972 - `BetaEncryptedCodeExecutionResultBlockParam object`
980973
981974 Code execution result with encrypted stdout for PFC + web_search results.
982975
from line 987
994987
995988 - `type: "encrypted_code_execution_result"`
996989
997 - `"encrypted_code_execution_result"`
998
999990 - `tool_use_id: string`
1000991
992 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
993
1001994 - `type: "code_execution_tool_result"`
1002995
1003 - `"code_execution_tool_result"`
1004
1005996 - `cache_control: optional BetaCacheControlEphemeral or null`
1006997
1007998 Create a cache control breakpoint at this content block.
1008999
1009 - `BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1000 - `BetaBashCodeExecutionToolResultBlockParam object`
10101001
10111002 - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam`
10121003
1013 - `BetaBashCodeExecutionToolResultErrorParam object { error_code, type }`
1004 - `BetaBashCodeExecutionToolResultErrorParam object`
10141005
10151006 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
10161007
from line 1017
10261017
10271018 - `type: "bash_code_execution_tool_result_error"`
10281019
1029 - `"bash_code_execution_tool_result_error"`
1030
1031 - `BetaBashCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }`
1020 - `BetaBashCodeExecutionResultBlockParam object`
10321021
10331022 - `content: array of BetaBashCodeExecutionOutputBlockParam`
10341023
from line 1025
10361025
10371026 - `type: "bash_code_execution_output"`
10381027
1039 - `"bash_code_execution_output"`
1040
10411028 - `return_code: number`
10421029
10431030 - `stderr: string`
from line 1033
10461033
10471034 - `type: "bash_code_execution_result"`
10481035
1049 - `"bash_code_execution_result"`
1050
10511036 - `tool_use_id: string`
10521037
1038 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1039
10531040 - `type: "bash_code_execution_tool_result"`
10541041
1055 - `"bash_code_execution_tool_result"`
1056
10571042 - `cache_control: optional BetaCacheControlEphemeral or null`
10581043
10591044 Create a cache control breakpoint at this content block.
10601045
1061 - `BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1046 - `BetaTextEditorCodeExecutionToolResultBlockParam object`
10621047
10631048 - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam`
10641049
1065 - `BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }`
1050 - `BetaTextEditorCodeExecutionToolResultErrorParam object`
10661051
10671052 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
10681053
from line 1063
10781063
10791064 - `type: "text_editor_code_execution_tool_result_error"`
10801065
1081 - `"text_editor_code_execution_tool_result_error"`
1082
10831066 - `error_message: optional string or null`
10841067
1085 - `BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }`
1068 - `BetaTextEditorCodeExecutionViewResultBlockParam object`
10861069
10871070 - `content: string`
10881071
from line 1079
10961079
10971080 - `type: "text_editor_code_execution_view_result"`
10981081
1099 - `"text_editor_code_execution_view_result"`
1100
11011082 - `num_lines: optional number or null`
11021083
11031084 - `start_line: optional number or null`
11041085
11051086 - `total_lines: optional number or null`
11061087
1107 - `BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }`
1088 - `BetaTextEditorCodeExecutionCreateResultBlockParam object`
11081089
11091090 - `is_file_update: boolean`
11101091
11111092 - `type: "text_editor_code_execution_create_result"`
11121093
1113 - `"text_editor_code_execution_create_result"`
1114
1115 - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }`
1094 - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object`
11161095
11171096 - `type: "text_editor_code_execution_str_replace_result"`
11181097
1119 - `"text_editor_code_execution_str_replace_result"`
1120
11211098 - `lines: optional array of string or null`
11221099
11231100 - `new_lines: optional number or null`
from line 1107
11301107
11311108 - `tool_use_id: string`
11321109
1110 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1111
11331112 - `type: "text_editor_code_execution_tool_result"`
11341113
1135 - `"text_editor_code_execution_tool_result"`
1136
11371114 - `cache_control: optional BetaCacheControlEphemeral or null`
11381115
11391116 Create a cache control breakpoint at this content block.
11401117
1141 - `BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1118 - `BetaToolSearchToolResultBlockParam object`
11421119
11431120 - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam`
11441121
1145 - `BetaToolSearchToolResultErrorParam object { error_code, type, error_message }`
1122 - `BetaToolSearchToolResultErrorParam object`
11461123
11471124 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
11481125
from line 1133
11561133
11571134 - `type: "tool_search_tool_result_error"`
11581135
1159 - `"tool_search_tool_result_error"`
1160
11611136 - `error_message: optional string or null`
11621137
1163 - `BetaToolSearchToolSearchResultBlockParam object { tool_references, type }`
1138 - `BetaToolSearchToolSearchResultBlockParam object`
11641139
11651140 - `tool_references: array of BetaToolReferenceBlockParam`
11661141
11671142 - `tool_name: string`
11681143
1144 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
1145
11691146 - `type: "tool_reference"`
11701147
11711148 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1151
11741151
11751152 - `type: "tool_search_tool_search_result"`
11761153
1177 - `"tool_search_tool_search_result"`
1178
11791154 - `tool_use_id: string`
11801155
1156 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1157
11811158 - `type: "tool_search_tool_result"`
11821159
1183 - `"tool_search_tool_result"`
1184
11851160 - `cache_control: optional BetaCacheControlEphemeral or null`
11861161
11871162 Create a cache control breakpoint at this content block.
11881163
1189 - `BetaMCPToolUseBlockParam object { id, input, name, 3 more }`
1164 - `BetaMCPToolUseBlockParam object`
11901165
11911166 - `id: string`
11921167
1168 pattern: ^[a-zA-Z0-9_-]+$
1169
11931170 - `input: map[unknown]`
11941171
11951172 - `name: string`
from line 1177
12001177
12011178 - `type: "mcp_tool_use"`
12021179
1203 - `"mcp_tool_use"`
1204
12051180 - `cache_control: optional BetaCacheControlEphemeral or null`
12061181
12071182 Create a cache control breakpoint at this content block.
12081183
1209 - `BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }`
1184 - `BetaRequestMCPToolResultBlockParam object`
12101185
12111186 - `tool_use_id: string`
12121187
1188 pattern: ^[a-zA-Z0-9_-]+$
1189
12131190 - `type: "mcp_tool_result"`
12141191
1215 - `"mcp_tool_result"`
1216
12171192 - `cache_control: optional BetaCacheControlEphemeral or null`
12181193
12191194 Create a cache control breakpoint at this content block.
from line 1201
12261201
12271202 - `text: string`
12281203
1204 minLength: 1
1205
12291206 - `type: "text"`
12301207
12311208 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1213
12361213
12371214 - `is_error: optional boolean`
12381215
1239 - `BetaContainerUploadBlockParam object { file_id, type, cache_control }`
1216 - `BetaContainerUploadBlockParam object`
12401217
12411218 A content block that represents a file to be uploaded to the container
12421219 Files uploaded via this block will be available in the container's input directory.
from line 1222
12451222
12461223 - `type: "container_upload"`
12471224
1248 - `"container_upload"`
1249
12501225 - `cache_control: optional BetaCacheControlEphemeral or null`
12511226
12521227 Create a cache control breakpoint at this content block.
12531228
1254 - `BetaCompactionBlockParam object { type, cache_control, content, encrypted_content }`
1229 - `BetaCompactionBlockParam object`
12551230
12561231 A compaction block containing summary of previous context.
12571232
from line 1238
12631238
12641239 - `type: "compaction"`
12651240
1266 - `"compaction"`
1267
12681241 - `cache_control: optional BetaCacheControlEphemeral or null`
12691242
12701243 Create a cache control breakpoint at this content block.
from line 1250
12771250
12781251 Opaque metadata from prior compaction, to be round-tripped verbatim
12791252
1280 - `BetaRequestToolAdditionBlock object { tool, type, cache_control }`
1253 - `BetaRequestToolAdditionBlock object`
12811254
12821255 Mid-conversation directive to surface a declared tool.
12831256
from line 1265
12921265 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
12931266 `mcp_toolset_reference` for those.
12941267
1295 - `BetaToolChangeToolReference object { name, type }`
1268 - `BetaToolChangeToolReference object`
12961269
12971270 Reference to a single tool the caller declared directly in
12981271 `tools[]`. Does not accept the composed `{server}_{name}` form the
from line 1274
13011274
13021275 - `name: string`
13031276
1277 pattern: ^[a-zA-Z0-9_-]{1,128}$
1278
13041279 - `type: "tool_reference"`
13051280
1306 - `"tool_reference"`
1307
1308 - `BetaToolChangeMCPToolReference object { name, server_name, type }`
1281 - `BetaToolChangeMCPToolReference object`
13091282
13101283 Reference to a single MCP tool by its server and remote name — the
13111284 same `server_name`/`name` pair `mcp_tool_use` carries.
from line 1289
13161289
13171290 - `type: "mcp_tool_reference"`
13181291
1319 - `"mcp_tool_reference"`
1320
1321 - `BetaToolChangeMCPToolsetReference object { server_name, type }`
1292 - `BetaToolChangeMCPToolsetReference object`
13221293
13231294 Reference to every tool in the named MCP server's toolset.
13241295
from line 1297
13261297
13271298 - `type: "mcp_toolset_reference"`
13281299
1329 - `"mcp_toolset_reference"`
1330
13311300 - `type: "tool_addition"`
13321301
1333 - `"tool_addition"`
1334
13351302 - `cache_control: optional BetaCacheControlEphemeral or null`
13361303
13371304 Create a cache control breakpoint at this content block.
13381305
1339 - `BetaRequestToolRemovalBlock object { tool, type, cache_control }`
1306 - `BetaRequestToolRemovalBlock object`
13401307
13411308 Mid-conversation directive to withdraw a tool.
13421309
from line 1318
13511318 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13521319 `mcp_toolset_reference` for those.
13531320
1354 - `BetaToolChangeToolReference object { name, type }`
1321 - `BetaToolChangeToolReference object`
13551322
13561323 Reference to a single tool the caller declared directly in
13571324 `tools[]`. Does not accept the composed `{server}_{name}` form the
13581325 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13591326 `mcp_toolset_reference` for those.
13601327
1361 - `BetaToolChangeMCPToolReference object { name, server_name, type }`
1328 - `BetaToolChangeMCPToolReference object`
13621329
13631330 Reference to a single MCP tool by its server and remote name — the
13641331 same `server_name`/`name` pair `mcp_tool_use` carries.
13651332
1366 - `BetaToolChangeMCPToolsetReference object { server_name, type }`
1333 - `BetaToolChangeMCPToolsetReference object`
13671334
13681335 Reference to every tool in the named MCP server's toolset.
13691336
13701337 - `type: "tool_removal"`
13711338
1372 - `"tool_removal"`
1373
13741339 - `cache_control: optional BetaCacheControlEphemeral or null`
13751340
13761341 Create a cache control breakpoint at this content block.
13771342
1378 - `BetaFallbackBlockParam object { from, to, type, trigger }`
1343 - `BetaFallbackBlockParam object`
13791344
13801345 A `fallback` block echoed back from a prior response.
13811346
from line 1440
14751440
14761441 - `type: "fallback"`
14771442
1478 - `"fallback"`
1479
14801443 - `trigger: optional unknown`
14811444
14821445 The response block's `trigger`, echoed verbatim. Accepted and ignored by the server; any object or `null` is allowed.
from line 1472
15091472
15101473 List of context management edits to apply
15111474
1512 - `BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }`
1475 minItems: 0
1476
1477 - `BetaClearToolUses20250919Edit object`
15131478
15141479 - `type: "clear_tool_uses_20250919"`
15151480
1516 - `"clear_tool_uses_20250919"`
1517
15181481 - `clear_at_least: optional BetaInputTokensClearAtLeast or null`
15191482
15201483 Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.
15211484
15221485 - `type: "input_tokens"`
15231486
1524 - `"input_tokens"`
1525
15261487 - `value: number`
15271488
1489 minimum: 0
1490
15281491 - `clear_tool_inputs: optional boolean or array of string or null`
15291492
15301493 Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)
from line 1506
15431506
15441507 - `type: "tool_uses"`
15451508
1546 - `"tool_uses"`
1547
15481509 - `value: number`
15491510
1511 minimum: 0
1512
15501513 - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger`
15511514
15521515 Condition that triggers the context management strategy
15531516
1554 - `BetaInputTokensTrigger object { type, value }`
1517 - `BetaInputTokensTrigger object`
15551518
15561519 - `type: "input_tokens"`
15571520
1558 - `"input_tokens"`
1559
15601521 - `value: number`
15611522
1562 - `BetaToolUsesTrigger object { type, value }`
1523 minimum: 1
1524
1525 - `BetaToolUsesTrigger object`
15631526
15641527 - `type: "tool_uses"`
15651528
1566 - `"tool_uses"`
1567
15681529 - `value: number`
15691530
1570 - `BetaClearThinking20251015Edit object { type, keep }`
1531 minimum: 1
1532
1533 - `BetaClearThinking20251015Edit object`
15711534
15721535 - `type: "clear_thinking_20251015"`
15731536
1574 - `"clear_thinking_20251015"`
1575
15761537 - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"`
15771538
15781539 Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.
15791540
1580 - `BetaThinkingTurns object { type, value }`
1541 - `BetaThinkingTurns object`
15811542
15821543 - `type: "thinking_turns"`
15831544
1584 - `"thinking_turns"`
1585
15861545 - `value: number`
15871546
1588 - `BetaAllThinkingTurns object { type }`
1547 minimum: 1
1548
1549 - `BetaAllThinkingTurns object`
15891550
15901551 - `type: "all"`
15911552
1592 - `"all"`
1593
15941553 - `"all"`
15951554
1596 - `"all"`
1597
1598 - `BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }`
1555 - `BetaCompact20260112Edit object`
15991556
16001557 Automatically compact older context when reaching the configured trigger threshold.
16011558
16021559 - `type: "compact_20260112"`
16031560
1604 - `"compact_20260112"`
1605
16061561 - `instructions: optional string or null`
16071562
16081563 Additional instructions for summarization.
from line 1574
16191574
16201575 MCP servers to be utilized in this request
16211576
1577 maxItems: 20
1578
16221579 - `name: string`
16231580
16241581 - `type: "url"`
16251582
1626 - `"url"`
1627
16281583 - `url: string`
16291584
16301585 - `authorization_token: optional string or null`
from line 1618
16631618
16641619 - `type: "json_schema"`
16651620
1666 - `"json_schema"`
1667
16681621 - `task_budget: optional BetaTokenTaskBudget or null`
16691622
16701623 User-configurable total token budget across contexts.
from line 1626
16731626
16741627 Total token budget across all contexts in the session.
16751628
1629 minimum: 1024
1630
16761631 - `type: "tokens"`
16771632
16781633 The budget type. Currently only 'tokens' is supported.
16791634
1680 - `"tokens"`
1681
16821635 - `remaining: optional number or null`
16831636
16841637 Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.
16851638
1686- `output_format: optional BetaJSONOutputFormat or null`
1687
1688 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
1689
1690 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
1639 minimum: 0
16911640
16921641- `speed: optional "standard" or "fast" or null`
16931642
from line 1658
17091658
17101659 - `text: string`
17111660
1661 minLength: 1
1662
17121663 - `type: "text"`
17131664
17141665 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1676
17251676
17261677 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
17271678
1728 - `BetaThinkingConfigEnabled object { budget_tokens, type, display }`
1679 - `BetaThinkingConfigEnabled object`
17291680
17301681 - `budget_tokens: number`
17311682
from line 1686
17351686
17361687 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
17371688
1689 minimum: 1024
1690
17381691 - `type: "enabled"`
17391692
1740 - `"enabled"`
1741
17421693 - `display: optional "summarized" or "omitted" or null`
17431694
17441695 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
from line 1698
17471698
17481699 - `"omitted"`
17491700
1750 - `BetaThinkingConfigDisabled object { type }`
1701 - `BetaThinkingConfigDisabled object`
17511702
17521703 - `type: "disabled"`
17531704
1754 - `"disabled"`
1755
1756 - `BetaThinkingConfigAdaptive object { type, display }`
1705 - `BetaThinkingConfigAdaptive object`
17571706
17581707 - `type: "adaptive"`
17591708
1760 - `"adaptive"`
1761
17621709 - `display: optional "summarized" or "omitted" or null`
17631710
17641711 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
from line 1718
17711718
17721719 How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
17731720
1774 - `BetaToolChoiceAuto object { type, disable_parallel_tool_use }`
1721 - `BetaToolChoiceAuto object`
17751722
17761723 The model will automatically decide whether to use tools.
17771724
17781725 - `type: "auto"`
17791726
1780 - `"auto"`
1781
17821727 - `disable_parallel_tool_use: optional boolean`
17831728
17841729 Whether to disable parallel tool use.
17851730
17861731 Defaults to `false`. If set to `true`, the model will output at most one tool use.
17871732
1788 - `BetaToolChoiceAny object { type, disable_parallel_tool_use }`
1733 - `BetaToolChoiceAny object`
17891734
17901735 The model will use any available tools.
17911736
17921737 - `type: "any"`
17931738
1794 - `"any"`
1795
17961739 - `disable_parallel_tool_use: optional boolean`
17971740
17981741 Whether to disable parallel tool use.
17991742
18001743 Defaults to `false`. If set to `true`, the model will output exactly one tool use.
18011744
1802 - `BetaToolChoiceTool object { name, type, disable_parallel_tool_use }`
1745 - `BetaToolChoiceTool object`
18031746
18041747 The model will use the specified tool with `tool_choice.name`.
18051748
from line 1752
18091752
18101753 - `type: "tool"`
18111754
1812 - `"tool"`
1813
18141755 - `disable_parallel_tool_use: optional boolean`
18151756
18161757 Whether to disable parallel tool use.
18171758
18181759 Defaults to `false`. If set to `true`, the model will output exactly one tool use.
18191760
1820 - `BetaToolChoiceNone object { type }`
1761 - `BetaToolChoiceNone object`
18211762
18221763 The model will not be allowed to use tools.
18231764
18241765 - `type: "none"`
1825
1826 - `"none"`
18271766
18281767- `tools: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 25 more`
18291768
from line 1828
18891828
18901829 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
18911830
1892 - `BetaTool object { input_schema, name, allowed_callers, 7 more }`
1893
1894 - `input_schema: object { type, properties, required }`
1831 - `BetaTool object`
1832
1833 - `input_schema: object`
18951834
18961835 [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input.
18971836
from line 1838
18991838
19001839 - `type: "object"`
19011840
1902 - `"object"`
1903
19041841 - `properties: optional map[unknown] or null`
19051842
19061843 - `required: optional array of string or null`
from line 1848
19111848
19121849 This is how the tool will be called by the model and in `tool_use` blocks.
19131850
1851 maxLength: 128, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,128}$
1852
19141853 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
19151854
19161855 - `"direct"`
from line 1886
19471886
19481887 - `type: optional "custom" or null`
19491888
1950 - `"custom"`
1951
1952 - `BetaToolBash20241022 object { name, type, allowed_callers, 4 more }`
1889 - `BetaToolBash20241022 object`
19531890
19541891 - `name: "bash"`
19551892
from line 1894
19571894
19581895 This is how the tool will be called by the model and in `tool_use` blocks.
19591896
1960 - `"bash"`
1961
19621897 - `type: "bash_20241022"`
19631898
1964 - `"bash_20241022"`
1965
19661899 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
19671900
19681901 - `"direct"`
from line 1920
19871920
19881921 When true, guarantees schema validation on tool names and inputs
19891922
1990 - `BetaToolBash20250124 object { name, type, allowed_callers, 4 more }`
1923 - `BetaToolBash20250124 object`
19911924
19921925 - `name: "bash"`
19931926
from line 1928
19951928
19961929 This is how the tool will be called by the model and in `tool_use` blocks.
19971930
1998 - `"bash"`
1999
20001931 - `type: "bash_20250124"`
20011932
2002 - `"bash_20250124"`
2003
20041933 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
20051934
20061935 - `"direct"`
from line 1954
20251954
20261955 When true, guarantees schema validation on tool names and inputs
20271956
2028 - `BetaCodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }`
1957 - `BetaCodeExecutionTool20250522 object`
20291958
20301959 - `name: "code_execution"`
20311960
from line 1962
20331962
20341963 This is how the tool will be called by the model and in `tool_use` blocks.
20351964
2036 - `"code_execution"`
2037
20381965 - `type: "code_execution_20250522"`
20391966
2040 - `"code_execution_20250522"`
2041
20421967 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
20431968
20441969 - `"direct"`
from line 1986
20611986
20621987 When true, guarantees schema validation on tool names and inputs
20631988
2064 - `BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }`
1989 - `BetaCodeExecutionTool20250825 object`
20651990
20661991 - `name: "code_execution"`
20671992
from line 1994
20691994
20701995 This is how the tool will be called by the model and in `tool_use` blocks.
20711996
2072 - `"code_execution"`
2073
20741997 - `type: "code_execution_20250825"`
20751998
1999 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2000
2001 - `"direct"`
2002
20762003 - `"code_execution_20250825"`
20772004
2005 - `"code_execution_20260120"`
2006
2007 - `"code_execution_20260521"`
2008
2009 - `cache_control: optional BetaCacheControlEphemeral or null`
2010
2011 Create a cache control breakpoint at this content block.
2012
2013 - `defer_loading: optional boolean`
2014
2015 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
2016
2017 - `strict: optional boolean`
2018
2019 When true, guarantees schema validation on tool names and inputs
2020
2021 - `BetaCodeExecutionTool20260120 object`
2022
2023 Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
2024
2025 - `name: "code_execution"`
2026
2027 Name of the tool.
2028
2029 This is how the tool will be called by the model and in `tool_use` blocks.
2030
2031 - `type: "code_execution_20260120"`
2032
20782033 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
20792034
20802035 - `"direct"`
from line 2052
20972052
20982053 When true, guarantees schema validation on tool names and inputs
20992054
2100 - `BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }`
2101
2102 Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
2055 - `BetaCodeExecutionTool20260521 object`
2056
2057 Code execution tool with REPL state persistence.
21032058
21042059 - `name: "code_execution"`
21052060
from line 2062
21072062
21082063 This is how the tool will be called by the model and in `tool_use` blocks.
21092064
2110 - `"code_execution"`
2111
2112 - `type: "code_execution_20260120"`
2065 - `type: "code_execution_20260521"`
2066
2067 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2068
2069 - `"direct"`
2070
2071 - `"code_execution_20250825"`
21132072
21142073 - `"code_execution_20260120"`
21152074
2116 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2117
2118 - `"direct"`
2119
2120 - `"code_execution_20250825"`
2121
2122 - `"code_execution_20260120"`
2123
21242075 - `"code_execution_20260521"`
21252076
21262077 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 2086
21352086
21362087 When true, guarantees schema validation on tool names and inputs
21372088
2138 - `BetaCodeExecutionTool20260521 object { name, type, allowed_callers, 3 more }`
2139
2140 Code execution tool with REPL state persistence.
2141
2142 - `name: "code_execution"`
2143
2144 Name of the tool.
2145
2146 This is how the tool will be called by the model and in `tool_use` blocks.
2147
2148 - `"code_execution"`
2149
2150 - `type: "code_execution_20260521"`
2151
2152 - `"code_execution_20260521"`
2153
2154 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2155
2156 - `"direct"`
2157
2158 - `"code_execution_20250825"`
2159
2160 - `"code_execution_20260120"`
2161
2162 - `"code_execution_20260521"`
2163
2164 - `cache_control: optional BetaCacheControlEphemeral or null`
2165
2166 Create a cache control breakpoint at this content block.
2167
2168 - `defer_loading: optional boolean`
2169
2170 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
2171
2172 - `strict: optional boolean`
2173
2174 When true, guarantees schema validation on tool names and inputs
2175
2176 - `BetaBrowserToolset20260801 object { type, allowed_callers, cache_control, configs }`
2089 - `BetaBrowserToolset20260801 object`
21772090
21782091 The browser toolset: a single `tools[]` entry (carrying no
21792092 `name`) that declares the browser tool family. The model is served
from line 2094
21812094 from its schema.
21822095
21832096 - `type: "browser_toolset_20260801"`
2184
2185 - `"browser_toolset_20260801"`
21862097
21872098 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
21882099
from line 2490
25792490
25802491 Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
25812492
2582 - `BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }`
2493 - `BetaToolComputerUse20241022 object`
25832494
25842495 - `display_height_px: number`
25852496
25862497 The height of the display in pixels.
25872498
2499 minimum: 1
2500
25882501 - `display_width_px: number`
25892502
25902503 The width of the display in pixels.
25912504
2505 minimum: 1
2506
25922507 - `name: "computer"`
25932508
25942509 Name of the tool.
25952510
25962511 This is how the tool will be called by the model and in `tool_use` blocks.
25972512
2598 - `"computer"`
2599
26002513 - `type: "computer_20241022"`
26012514
2602 - `"computer_20241022"`
2603
26042515 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
26052516
26062517 - `"direct"`
from line 2534
26232534
26242535 The X11 display number (e.g. 0, 1) for the display.
26252536
2537 minimum: 0
2538
26262539 - `input_examples: optional array of map[unknown]`
26272540
26282541 - `strict: optional boolean`
26292542
26302543 When true, guarantees schema validation on tool names and inputs
26312544
2632 - `BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }`
2545 - `BetaMemoryTool20250818 object`
26332546
26342547 - `name: "memory"`
26352548
from line 2550
26372550
26382551 This is how the tool will be called by the model and in `tool_use` blocks.
26392552
2640 - `"memory"`
2641
26422553 - `type: "memory_20250818"`
26432554
2644 - `"memory_20250818"`
2645
26462555 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
26472556
26482557 - `"direct"`
from line 2576
26672576
26682577 When true, guarantees schema validation on tool names and inputs
26692578
2670 - `BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }`
2579 - `BetaToolComputerUse20250124 object`
26712580
26722581 - `display_height_px: number`
26732582
26742583 The height of the display in pixels.
26752584
2585 minimum: 1
2586
26762587 - `display_width_px: number`
26772588
26782589 The width of the display in pixels.
26792590
2591 minimum: 1
2592
26802593 - `name: "computer"`
26812594
26822595 Name of the tool.
26832596
26842597 This is how the tool will be called by the model and in `tool_use` blocks.
26852598
2686 - `"computer"`
2687
26882599 - `type: "computer_20250124"`
26892600
2690 - `"computer_20250124"`
2691
26922601 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
26932602
26942603 - `"direct"`
from line 2620
27112620
27122621 The X11 display number (e.g. 0, 1) for the display.
27132622
2623 minimum: 0
2624
27142625 - `input_examples: optional array of map[unknown]`
27152626
27162627 - `strict: optional boolean`
27172628
27182629 When true, guarantees schema validation on tool names and inputs
27192630
2720 - `BetaToolTextEditor20241022 object { name, type, allowed_callers, 4 more }`
2631 - `BetaToolTextEditor20241022 object`
27212632
27222633 - `name: "str_replace_editor"`
27232634
from line 2636
27252636
27262637 This is how the tool will be called by the model and in `tool_use` blocks.
27272638
2728 - `"str_replace_editor"`
2729
27302639 - `type: "text_editor_20241022"`
27312640
2732 - `"text_editor_20241022"`
2733
27342641 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
27352642
27362643 - `"direct"`
from line 2662
27552662
27562663 When true, guarantees schema validation on tool names and inputs
27572664
2758 - `BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }`
2665 - `BetaToolComputerUse20251124 object`
27592666
27602667 - `display_height_px: number`
27612668
27622669 The height of the display in pixels.
27632670
2671 minimum: 1
2672
27642673 - `display_width_px: number`
27652674
27662675 The width of the display in pixels.
27672676
2677 minimum: 1
2678
27682679 - `name: "computer"`
27692680
27702681 Name of the tool.
27712682
27722683 This is how the tool will be called by the model and in `tool_use` blocks.
27732684
2774 - `"computer"`
2775
27762685 - `type: "computer_20251124"`
27772686
2778 - `"computer_20251124"`
2779
27802687 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
27812688
27822689 - `"direct"`
from line 2706
27992706
28002707 The X11 display number (e.g. 0, 1) for the display.
28012708
2709 minimum: 0
2710
28022711 - `enable_zoom: optional boolean`
28032712
28042713 Whether to enable an action to take a zoomed-in screenshot of the screen.
from line 2718
28092718
28102719 When true, guarantees schema validation on tool names and inputs
28112720
2812 - `BetaComputerToolset20260801 object { type, allowed_callers, cache_control, configs }`
2721 - `BetaComputerToolset20260801 object`
28132722
28142723 The computer toolset: a single `tools[]` entry (carrying no
28152724 `name`) that declares the computer tool family. The model is
from line 2731
28222731
28232732 - `type: "computer_toolset_20260801"`
28242733
2825 - `"computer_toolset_20260801"`
2826
28272734 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
28282735
28292736 - `"direct"`
from line 2958
30512958
30522959 Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
30532960
3054 - `BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }`
2961 - `BetaToolTextEditor20250124 object`
30552962
30562963 - `name: "str_replace_editor"`
30572964
from line 2966
30592966
30602967 This is how the tool will be called by the model and in `tool_use` blocks.
30612968
3062 - `"str_replace_editor"`
3063
30642969 - `type: "text_editor_20250124"`
30652970
3066 - `"text_editor_20250124"`
3067
30682971 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
30692972
30702973 - `"direct"`
from line 2992
30892992
30902993 When true, guarantees schema validation on tool names and inputs
30912994
3092 - `BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }`
2995 - `BetaToolTextEditor20250429 object`
30932996
30942997 - `name: "str_replace_based_edit_tool"`
30952998
from line 3000
30973000
30983001 This is how the tool will be called by the model and in `tool_use` blocks.
30993002
3100 - `"str_replace_based_edit_tool"`
3101
31023003 - `type: "text_editor_20250429"`
31033004
3104 - `"text_editor_20250429"`
3105
31063005 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
31073006
31083007 - `"direct"`
from line 3026
31273026
31283027 When true, guarantees schema validation on tool names and inputs
31293028
3130 - `BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }`
3029 - `BetaToolTextEditor20250728 object`
31313030
31323031 - `name: "str_replace_based_edit_tool"`
31333032
from line 3034
31353034
31363035 This is how the tool will be called by the model and in `tool_use` blocks.
31373036
3138 - `"str_replace_based_edit_tool"`
3139
31403037 - `type: "text_editor_20250728"`
31413038
3142 - `"text_editor_20250728"`
3143
31443039 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
31453040
31463041 - `"direct"`
from line 3060
31653060
31663061 Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.
31673062
3063 minimum: 1
3064
31683065 - `strict: optional boolean`
31693066
31703067 When true, guarantees schema validation on tool names and inputs
31713068
3172 - `BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }`
3069 - `BetaWebSearchTool20250305 object`
31733070
31743071 - `name: "web_search"`
31753072
from line 3074
31773074
31783075 This is how the tool will be called by the model and in `tool_use` blocks.
31793076
3180 - `"web_search"`
3181
31823077 - `type: "web_search_20250305"`
31833078
3184 - `"web_search_20250305"`
3185
31863079 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
31873080
31883081 - `"direct"`
from line 3106
32133106
32143107 Maximum number of times the tool can be used in the API request.
32153108
3109 exclusiveMinimum: 0
3110
32163111 - `strict: optional boolean`
32173112
32183113 When true, guarantees schema validation on tool names and inputs
from line 3118
32233118
32243119 - `type: "approximate"`
32253120
3226 - `"approximate"`
3227
32283121 - `city: optional string or null`
32293122
32303123 The city of the user.
32313124
3125 maxLength: 255, minLength: 1
3126
32323127 - `country: optional string or null`
32333128
32343129 The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.
32353130
3131 maxLength: 2, minLength: 2
3132
32363133 - `region: optional string or null`
32373134
32383135 The region of the user.
32393136
3137 maxLength: 255, minLength: 1
3138
32403139 - `timezone: optional string or null`
32413140
32423141 The [IANA timezone](https://nodatime.org/TimeZones) of the user.
32433142
3244 - `BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }`
3143 maxLength: 255, minLength: 1
3144
3145 - `BetaWebFetchTool20250910 object`
32453146
32463147 - `name: "web_fetch"`
32473148
from line 3150
32493150
32503151 This is how the tool will be called by the model and in `tool_use` blocks.
32513152
3252 - `"web_fetch"`
3253
32543153 - `type: "web_fetch_20250910"`
32553154
3256 - `"web_fetch_20250910"`
3257
32583155 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
32593156
32603157 - `"direct"`
from line 3186
32893186
32903187 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
32913188
3189 exclusiveMinimum: 0
3190
32923191 - `max_uses: optional number or null`
32933192
32943193 Maximum number of times the tool can be used in the API request.
32953194
3195 exclusiveMinimum: 0
3196
32963197 - `strict: optional boolean`
32973198
32983199 When true, guarantees schema validation on tool names and inputs
32993200
3300 - `BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }`
3201 - `BetaWebSearchTool20260209 object`
33013202
33023203 - `name: "web_search"`
33033204
from line 3206
33053206
33063207 This is how the tool will be called by the model and in `tool_use` blocks.
33073208
3308 - `"web_search"`
3309
33103209 - `type: "web_search_20260209"`
33113210
3312 - `"web_search_20260209"`
3313
33143211 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33153212
33163213 - `"direct"`
from line 3238
33413238
33423239 Maximum number of times the tool can be used in the API request.
33433240
3241 exclusiveMinimum: 0
3242
33443243 - `strict: optional boolean`
33453244
33463245 When true, guarantees schema validation on tool names and inputs
from line 3248
33493248
33503249 Parameters for the user's location. Used to provide more relevant search results.
33513250
3352 - `BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }`
3251 - `BetaWebFetchTool20260209 object`
33533252
33543253 - `name: "web_fetch"`
33553254
from line 3256
33573256
33583257 This is how the tool will be called by the model and in `tool_use` blocks.
33593258
3360 - `"web_fetch"`
3361
33623259 - `type: "web_fetch_20260209"`
33633260
3364 - `"web_fetch_20260209"`
3365
33663261 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33673262
33683263 - `"direct"`
from line 3292
33973292
33983293 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
33993294
3295 exclusiveMinimum: 0
3296
34003297 - `max_uses: optional number or null`
34013298
34023299 Maximum number of times the tool can be used in the API request.
34033300
3301 exclusiveMinimum: 0
3302
34043303 - `strict: optional boolean`
34053304
34063305 When true, guarantees schema validation on tool names and inputs
34073306
3408 - `BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }`
3307 - `BetaWebFetchTool20260309 object`
34093308
34103309 Web fetch tool with use_cache parameter for bypassing cached content.
34113310
from line 3314
34153314
34163315 This is how the tool will be called by the model and in `tool_use` blocks.
34173316
3418 - `"web_fetch"`
3419
34203317 - `type: "web_fetch_20260309"`
34213318
3422 - `"web_fetch_20260309"`
3423
34243319 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
34253320
34263321 - `"direct"`
from line 3350
34553350
34563351 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
34573352
3353 exclusiveMinimum: 0
3354
34583355 - `max_uses: optional number or null`
34593356
34603357 Maximum number of times the tool can be used in the API request.
34613358
3359 exclusiveMinimum: 0
3360
34623361 - `strict: optional boolean`
34633362
34643363 When true, guarantees schema validation on tool names and inputs
from line 3366
34673366
34683367 Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.
34693368
3470 - `BetaWebSearchTool20260318 object { name, type, allowed_callers, 8 more }`
3369 - `BetaWebSearchTool20260318 object`
34713370
34723371 - `name: "web_search"`
34733372
from line 3374
34753374
34763375 This is how the tool will be called by the model and in `tool_use` blocks.
34773376
3478 - `"web_search"`
3479
34803377 - `type: "web_search_20260318"`
34813378
3482 - `"web_search_20260318"`
3483
34843379 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
34853380
34863381 - `"direct"`
from line 3406
35113406
35123407 Maximum number of times the tool can be used in the API request.
35133408
3409 exclusiveMinimum: 0
3410
35143411 - `response_inclusion: optional "full" or "excluded"`
35153412
35163413 How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3424
35273424
35283425 Parameters for the user's location. Used to provide more relevant search results.
35293426
3530 - `BetaWebFetchTool20260318 object { name, type, allowed_callers, 10 more }`
3427 - `BetaWebFetchTool20260318 object`
35313428
35323429 - `name: "web_fetch"`
35333430
from line 3432
35353432
35363433 This is how the tool will be called by the model and in `tool_use` blocks.
35373434
3538 - `"web_fetch"`
3539
35403435 - `type: "web_fetch_20260318"`
35413436
3542 - `"web_fetch_20260318"`
3543
35443437 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
35453438
35463439 - `"direct"`
from line 3468
35753468
35763469 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
35773470
3471 exclusiveMinimum: 0
3472
35783473 - `max_uses: optional number or null`
35793474
35803475 Maximum number of times the tool can be used in the API request.
35813476
3477 exclusiveMinimum: 0
3478
35823479 - `response_inclusion: optional "full" or "excluded"`
35833480
35843481 How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3492
35953492
35963493 Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.
35973494
3598 - `BetaAdvisorTool20260301 object { model, name, type, 7 more }`
3495 - `BetaAdvisorTool20260301 object`
35993496
36003497 - `model: Model`
36013498
from line 3506
36093506
36103507 This is how the tool will be called by the model and in `tool_use` blocks.
36113508
3612 - `"advisor"`
3613
36143509 - `type: "advisor_20260301"`
36153510
3616 - `"advisor_20260301"`
3617
36183511 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
36193512
36203513 - `"direct"`
from line 3534
36413534
36423535 Bounds the advisor's total output (thinking + text) per call. When the advisor hits this cap, the returned advisor_result or advisor_redacted_result block carries stop_reason='max_tokens', and a truncation note is appended to the advice text the worker model sees (inside the encrypted blob in redacted mode). When set, the server also emits a remaining-tokens budget block in the advisor's prompt so the advisor self-shapes toward the cap. When omitted, the advisor model's default output cap applies and no budget block is emitted.
36433536
3537 minimum: 1024
3538
36443539 - `max_uses: optional number or null`
36453540
36463541 Maximum number of times the tool can be used in the API request.
36473542
3543 exclusiveMinimum: 0
3544
36483545 - `strict: optional boolean`
36493546
36503547 When true, guarantees schema validation on tool names and inputs
36513548
3652 - `BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }`
3549 - `BetaToolSearchToolBm25_20251119 object`
36533550
36543551 - `name: "tool_search_tool_bm25"`
36553552
from line 3554
36573554
36583555 This is how the tool will be called by the model and in `tool_use` blocks.
36593556
3557 - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"`
3558
3559 - `"tool_search_tool_bm25_20251119"`
3560
36603561 - `"tool_search_tool_bm25"`
36613562
3662 - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"`
3663
3664 - `"tool_search_tool_bm25_20251119"`
3665
3666 - `"tool_search_tool_bm25"`
3667
36683563 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
36693564
36703565 - `"direct"`
from line 3582
36873582
36883583 When true, guarantees schema validation on tool names and inputs
36893584
3690 - `BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }`
3585 - `BetaToolSearchToolRegex20251119 object`
36913586
36923587 - `name: "tool_search_tool_regex"`
36933588
from line 3590
36953590
36963591 This is how the tool will be called by the model and in `tool_use` blocks.
36973592
3593 - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"`
3594
3595 - `"tool_search_tool_regex_20251119"`
3596
36983597 - `"tool_search_tool_regex"`
36993598
3700 - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"`
3701
3702 - `"tool_search_tool_regex_20251119"`
3703
3704 - `"tool_search_tool_regex"`
3705
37063599 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
37073600
37083601 - `"direct"`
from line 3618
37253618
37263619 When true, guarantees schema validation on tool names and inputs
37273620
3728 - `BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }`
3621 - `BetaMCPToolset object`
37293622
37303623 Configuration for a group of tools from an MCP server.
37313624
from line 3629
37363629
37373630 Name of the MCP server to configure tools for
37383631
3632 maxLength: 255, minLength: 1
3633
37393634 - `type: "mcp_toolset"`
37403635
3741 - `"mcp_toolset"`
3742
37433636 - `cache_control: optional BetaCacheControlEphemeral or null`
37443637
37453638 Create a cache control breakpoint at this content block.
from line 3653
37603653
37613654 - `enabled: optional boolean`
37623655
3763### Returns
3764
3765- `BetaMessageTokensCount object { context_management, input_tokens }`
3656- `output_format: optional BetaJSONOutputFormat or null`
3657
3658 **Deprecated**
3659
3660 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
3661
3662 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
3663
3664## Returns
3665
3666- `BetaMessageTokensCount object`
37663667
37673668 - `context_management: BetaCountTokensContextManagementResponse or null`
37683669
from line 3677
37763677
37773678 The total number of tokens across the provided list of messages, system prompt, and tools.
37783679
3779### Example
3780
3781```http
3680## Example
3681
3682```bash
37823683curl https://api.anthropic.com/v1/messages/count_tokens \
37833684 -H 'Content-Type: application/json' \
37843685 -H 'anthropic-version: 2023-06-01' \
from line 3719
38183719 }'
38193720```
38203721
3821#### Response
3722### Response (200)
38223723
38233724```json
38243725{
38253726
api/beta/messages/create Changed · +984 / -690 lines
# Create a Message ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create a Message ### 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: Create a Message
3url: https://platform.claude.com/docs/en/api/beta/messages/create
4---
5
6## Create a Message
7
8**post** `/v1/messages`
1# Create a Message
2
3**POST** `/v1/messages`
94
105Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.
116
from line 8
138
149Learn more about the Messages API in our [user guide](https://platform.claude.com/docs/en/get-started)
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 90
9590
9691 The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header.
9792
98### Body Parameters
93## Body parameters
9994
10095- `max_tokens: number`
10196
from line 101
106101 Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.
107102
108103 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
104
105 minimum: 0
109106
110107- `messages: array of BetaMessageParam`
111108
from line 161
164161
165162 - `array of BetaContentBlockParam`
166163
167 - `BetaTextBlockParam object { text, type, cache_control, citations }`
164 - `BetaTextBlockParam object`
168165
169166 - `text: string`
170167
168 minLength: 1
169
171170 - `type: "text"`
172171
173 - `"text"`
174
175172 - `cache_control: optional BetaCacheControlEphemeral or null`
176173
177174 Create a cache control breakpoint at this content block.
178175
179176 - `type: "ephemeral"`
180
181 - `"ephemeral"`
182177
183178 - `ttl: optional "5m" or "1h"`
184179
from line 192
197192
198193 - `citations: optional array of BetaTextCitationParam or null`
199194
200 - `BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
195 - `BetaCitationCharLocationParam object`
201196
202197 - `cited_text: string`
203198
204199 - `document_index: number`
205200
201 minimum: 0
202
206203 - `document_title: string or null`
207204
205 maxLength: 500, minLength: 1
206
208207 - `end_char_index: number`
209208
210209 - `start_char_index: number`
211210
211 minimum: 0
212
212213 - `type: "char_location"`
213214
214 - `"char_location"`
215
216 - `BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
215 - `BetaCitationPageLocationParam object`
217216
218217 - `cited_text: string`
219218
220219 - `document_index: number`
221220
221 minimum: 0
222
222223 - `document_title: string or null`
223224
225 maxLength: 500, minLength: 1
226
224227 - `end_page_number: number`
225228
226229 - `start_page_number: number`
227230
231 minimum: 1
232
228233 - `type: "page_location"`
229234
230 - `"page_location"`
231
232 - `BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
235 - `BetaCitationContentBlockLocationParam object`
233236
234237 - `cited_text: string`
235238
from line 242
239242
240243 - `document_index: number`
241244
245 minimum: 0
246
242247 - `document_title: string or null`
243248
249 maxLength: 500, minLength: 1
250
244251 - `end_block_index: number`
245252
246253 Exclusive 0-based end index of the cited block range in the source's `content` array.
from line 258
251258
252259 0-based index of the first cited block in the source's `content` array.
253260
261 minimum: 0
262
254263 - `type: "content_block_location"`
255264
256 - `"content_block_location"`
257
258 - `BetaCitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
265 - `BetaCitationWebSearchResultLocationParam object`
259266
260267 - `cited_text: string`
261268
from line 270
263270
264271 - `title: string or null`
265272
273 maxLength: 512, minLength: 1
274
266275 - `type: "web_search_result_location"`
267276
268 - `"web_search_result_location"`
269
270277 - `url: string`
271278
272 - `BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
279 minLength: 1
280
281 - `BetaCitationSearchResultLocationParam object`
273282
274283 - `cited_text: string`
275284
from line 298
289298
290299 Counted separately from `document_index`; server-side web search results are not included in this count.
291300
301 minimum: 0
302
292303 - `source: string`
293304
294305 - `start_block_index: number`
295306
296307 0-based index of the first cited block in the source's `content` array.
297308
309 minimum: 0
310
298311 - `title: string or null`
299312
300313 - `type: "search_result_location"`
301314
302 - `"search_result_location"`
303
304 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
315 - `BetaImageBlockParam object`
305316
306317 - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource`
307318
308 - `BetaBase64ImageSource object { data, media_type, type }`
319 - `BetaBase64ImageSource object`
309320
310321 - `data: string`
311322
323 format: byte
324
312325 - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
313326
314327 - `"image/jpeg"`
from line 334
321334
322335 - `type: "base64"`
323336
324 - `"base64"`
325
326 - `BetaURLImageSource object { type, url }`
337 - `BetaURLImageSource object`
327338
328339 - `type: "url"`
329340
330 - `"url"`
331
332341 - `url: string`
333342
334 - `BetaFileImageSource object { file_id, type }`
343 - `BetaFileImageSource object`
335344
336345 - `file_id: string`
337346
338347 - `type: "file"`
339348
340 - `"file"`
341
342349 - `type: "image"`
343350
344 - `"image"`
345
346351 - `cache_control: optional BetaCacheControlEphemeral or null`
347352
348353 Create a cache control breakpoint at this content block.
from line 364
359364
360365 - `"error"`
361366
362 - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }`
367 - `BetaRequestDocumentBlock object`
363368
364369 - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more`
365370
366 - `BetaBase64PDFSource object { data, media_type, type }`
371 - `BetaBase64PDFSource object`
367372
368373 - `data: string`
369374
375 format: byte
376
370377 - `media_type: "application/pdf"`
371378
372 - `"application/pdf"`
373
374379 - `type: "base64"`
375380
376 - `"base64"`
377
378 - `BetaPlainTextSource object { data, media_type, type }`
381 - `BetaPlainTextSource object`
379382
380383 - `data: string`
381384
382385 - `media_type: "text/plain"`
383386
384 - `"text/plain"`
385
386387 - `type: "text"`
387388
388 - `"text"`
389
390 - `BetaContentBlockSource object { content, type }`
389 - `BetaContentBlockSource object`
391390
392391 - `content: string or array of BetaContentBlockSourceContent`
393392
from line 394
395394
396395 - `BetaContentBlockSourceContent = array of BetaContentBlockSourceContent`
397396
398 - `BetaTextBlockParam object { text, type, cache_control, citations }`
399
400 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
397 - `BetaTextBlockParam object`
398
399 - `BetaImageBlockParam object`
401400
402401 - `type: "content"`
403402
404 - `"content"`
405
406 - `BetaURLPDFSource object { type, url }`
403 - `BetaURLPDFSource object`
407404
408405 - `type: "url"`
409406
410 - `"url"`
411
412407 - `url: string`
413408
414 - `BetaFileDocumentSource object { file_id, type }`
409 - `BetaFileDocumentSource object`
415410
416411 - `file_id: string`
417412
418413 - `type: "file"`
419414
420 - `"file"`
421
422415 - `type: "document"`
423416
424 - `"document"`
425
426417 - `cache_control: optional BetaCacheControlEphemeral or null`
427418
428419 Create a cache control breakpoint at this content block.
from line 424
433424
434425 - `context: optional string or null`
435426
427 minLength: 1
428
436429 - `title: optional string or null`
437430
438 - `BetaSearchResultBlockParam object { content, source, title, 3 more }`
431 maxLength: 500, minLength: 1
432
433 - `BetaSearchResultBlockParam object`
439434
440435 - `content: array of BetaTextBlockParam`
441436
442437 - `text: string`
443438
439 minLength: 1
440
444441 - `type: "text"`
445442
446443 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 452
455452
456453 - `type: "search_result"`
457454
458 - `"search_result"`
459
460455 - `cache_control: optional BetaCacheControlEphemeral or null`
461456
462457 Create a cache control breakpoint at this content block.
463458
464459 - `citations: optional BetaCitationsConfigParam`
465460
466 - `BetaThinkingBlockParam object { signature, thinking, type }`
461 - `BetaThinkingBlockParam object`
467462
468463 - `signature: string`
469464
from line 472
477472
478473 - `type: "thinking"`
479474
480 - `"thinking"`
481
482 - `BetaRedactedThinkingBlockParam object { data, type }`
475 - `BetaRedactedThinkingBlockParam object`
483476
484477 - `data: string`
485478
from line 480
487480
488481 - `type: "redacted_thinking"`
489482
490 - `"redacted_thinking"`
491
492 - `BetaToolUseBlockParam object { id, input, name, 4 more }`
483 - `BetaToolUseBlockParam object`
493484
494485 - `id: string`
495486
487 pattern: ^[a-zA-Z0-9_-]+$
488
496489 - `input: map[unknown]`
497490
498491 - `name: string`
499492
493 maxLength: 200, minLength: 1
494
500495 - `type: "tool_use"`
501496
502 - `"tool_use"`
503
504497 - `cache_control: optional BetaCacheControlEphemeral or null`
505498
506499 Create a cache control breakpoint at this content block.
from line 502
509502
510503 Tool invocation directly from the model.
511504
512 - `BetaDirectCaller object { type }`
505 - `BetaDirectCaller object`
513506
514507 Tool invocation directly from the model.
515508
516509 - `type: "direct"`
517510
518 - `"direct"`
519
520 - `BetaServerToolCaller object { tool_id, type }`
511 - `BetaServerToolCaller object`
521512
522513 Tool invocation generated by a server-side tool.
523514
524515 - `tool_id: string`
525516
517 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
518
526519 - `type: "code_execution_20250825"`
527520
528 - `"code_execution_20250825"`
529
530 - `BetaServerToolCaller20260120 object { tool_id, type }`
521 - `BetaServerToolCaller20260120 object`
531522
532523 - `tool_id: string`
533524
525 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
526
534527 - `type: "code_execution_20260120"`
535528
536 - `"code_execution_20260120"`
537
538529 - `toolset_name: optional string or null`
539530
540531 For a toolset member tool_use, the toolset family this member belongs to.
541532
542 - `BetaToolResultBlockParam object { tool_use_id, type, cache_control, 3 more }`
533 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
534
535 - `BetaToolResultBlockParam object`
543536
544537 - `tool_use_id: string`
545538
539 pattern: ^[a-zA-Z0-9_-]+$
540
546541 - `type: "tool_result"`
547542
548 - `"tool_result"`
549
550543 - `cache_control: optional BetaCacheControlEphemeral or null`
551544
552545 Create a cache control breakpoint at this content block.
from line 550
557550
558551 - `array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 3 more`
559552
560 - `BetaTextBlockParam object { text, type, cache_control, citations }`
561
562 - `BetaImageBlockParam object { source, type, cache_control, transformations }`
563
564 - `BetaSearchResultBlockParam object { content, source, title, 3 more }`
565
566 - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }`
567
568 - `BetaToolReferenceBlockParam object { tool_name, type, cache_control }`
553 - `BetaTextBlockParam object`
554
555 - `BetaImageBlockParam object`
556
557 - `BetaSearchResultBlockParam object`
558
559 - `BetaRequestDocumentBlock object`
560
561 - `BetaToolReferenceBlockParam object`
569562
570563 Tool reference block that can be included in tool_result content.
571564
572565 - `tool_name: string`
573566
567 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
568
574569 - `type: "tool_reference"`
575570
576 - `"tool_reference"`
577
578571 - `cache_control: optional BetaCacheControlEphemeral or null`
579572
580573 Create a cache control breakpoint at this content block.
581574
582 - `BetaBrowserStateBlockParam object { tabs, type, cache_control, state_changes }`
575 - `BetaBrowserStateBlockParam object`
583576
584577 The caller's browser state after a browser toolset member call —
585578 the full inventory of open tabs, which tab is active, and any side
from line 586
593586
594587 All tabs open in the browser after this call — the full inventory, not a delta. May be empty. Whenever non-empty, exactly one entry carries `active: true`.
595588
589 maxItems: 100
590
596591 - `tab_id: string`
597592
598593 The caller-assigned identifier for this tab, unique within the inventory.
599594
595 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
596
600597 - `title: string`
601598
602599 The title of the page the tab is showing. May be empty.
603600
601 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
602
604603 - `url: string`
605604
606605 The URL of the page the tab is showing. May be empty.
607606
607 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
608
608609 - `active: optional boolean`
609610
610611 Whether this tab is the active tab after this call. Whenever `tabs` is non-empty, exactly one entry is marked `active: true`.
611612
612613 - `type: "browser_state"`
613614
614 - `"browser_state"`
615
616615 - `cache_control: optional BetaCacheControlEphemeral or null`
617616
618617 Create a cache control breakpoint at this content block.
from line 620
621620
622621 Tabs opened and download state changes during this call. "Nothing to report" is expressed by omitting the field, never by an empty list.
623622
624 - `BetaBrowserStateChangeTabOpened object { tab_id, type }`
623 maxItems: 200, minItems: 1
624
625 - `BetaBrowserStateChangeTabOpened object`
625626
626627 A tab this call's execution opened that remains open at its end —
627628 the creation delta of the `tabs` inventory, not an event log.
from line 636
635636
636637 The `tab_id` of the opened tab, present in `tabs`.
637638
639 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
640
638641 - `type: "tab_opened"`
639642
640 - `"tab_opened"`
641
642 - `BetaBrowserStateChangeDownloadStarted object { download_id, type, url }`
643 - `BetaBrowserStateChangeDownloadStarted object`
643644
644645 A file download that started during this call.
645646
from line 648
647648
648649 The caller-assigned identifier for this download, stable across the state changes reporting it.
649650
651 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
652
650653 - `type: "download_started"`
651654
652 - `"download_started"`
653
654655 - `url: string`
655656
656657 The final post-redirect URL the download was served from.
657658
658 - `BetaBrowserStateChangeDownloadCompleted object { download_id, type, url, 2 more }`
659 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
660
661 - `BetaBrowserStateChangeDownloadCompleted object`
659662
660663 A file download that finished during this call, reported with the
661664 same `download_id` as its `download_started` — or without a prior
from line 669
666669
667670 The caller-assigned identifier for this download, stable across the state changes reporting it.
668671
672 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
673
669674 - `type: "download_completed"`
670675
671 - `"download_completed"`
672
673676 - `url: string`
674677
675678 The final post-redirect URL the download was served from.
676679
680 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
681
677682 - `path: optional string or null`
678683
679684 Where the executor saved the file, on the executor's filesystem. Only included when another tool in the same environment can read the file at that path.
680685
686 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096
687
681688 - `size_bytes: optional number or null`
682689
683690 The completed download's size.
684691
685 - `BetaBrowserStateChangeDownloadFailed object { download_id, type, url, error }`
692 minimum: 0
693
694 - `BetaBrowserStateChangeDownloadFailed object`
686695
687696 A file download that failed — or was cancelled — during this call.
688697
from line 699
690699
691700 The caller-assigned identifier for this download, stable across the state changes reporting it.
692701
702 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
703
693704 - `type: "download_failed"`
694705
695 - `"download_failed"`
696
697706 - `url: string`
698707
699708 The final post-redirect URL the download was served from.
700709
710 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$
711
701712 - `error: optional string or null`
702713
703714 The failure or cancellation detail, when known.
704715
716 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096
717
705718 - `is_error: optional boolean`
706719
707720 - `toolset_name: optional string or null`
708721
709722 For a toolset member tool_result, the toolset family of the paired tool_use.
710723
711 - `BetaServerToolUseBlockParam object { id, input, name, 3 more }`
724 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
725
726 - `BetaServerToolUseBlockParam object`
712727
713728 - `id: string`
714729
730 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
731
715732 - `input: map[unknown]`
716733
717734 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 751
734751
735752 - `type: "server_tool_use"`
736753
737 - `"server_tool_use"`
738
739754 - `cache_control: optional BetaCacheControlEphemeral or null`
740755
741756 Create a cache control breakpoint at this content block.
from line 759
744759
745760 Tool invocation directly from the model.
746761
747 - `BetaDirectCaller object { type }`
762 - `BetaDirectCaller object`
748763
749764 Tool invocation directly from the model.
750765
751 - `BetaServerToolCaller object { tool_id, type }`
766 - `BetaServerToolCaller object`
752767
753768 Tool invocation generated by a server-side tool.
754769
755 - `BetaServerToolCaller20260120 object { tool_id, type }`
756
757 - `BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }`
770 - `BetaServerToolCaller20260120 object`
771
772 - `BetaWebSearchToolResultBlockParam object`
758773
759774 - `content: BetaWebSearchToolResultBlockParamContent`
760775
from line 781
766781
767782 - `type: "web_search_result"`
768783
769 - `"web_search_result"`
770
771784 - `url: string`
772785
773786 - `page_age: optional string or null`
774787
775 - `BetaWebSearchToolRequestError object { error_code, type }`
788 - `BetaWebSearchToolRequestError object`
776789
777790 - `error_code: BetaWebSearchToolResultErrorCode`
778791
from line 803
790803
791804 - `type: "web_search_tool_result_error"`
792805
793 - `"web_search_tool_result_error"`
794
795806 - `tool_use_id: string`
796807
808 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
809
797810 - `type: "web_search_tool_result"`
798811
799 - `"web_search_tool_result"`
800
801812 - `cache_control: optional BetaCacheControlEphemeral or null`
802813
803814 Create a cache control breakpoint at this content block.
from line 817
806817
807818 Tool invocation directly from the model.
808819
809 - `BetaDirectCaller object { type }`
820 - `BetaDirectCaller object`
810821
811822 Tool invocation directly from the model.
812823
813 - `BetaServerToolCaller object { tool_id, type }`
824 - `BetaServerToolCaller object`
814825
815826 Tool invocation generated by a server-side tool.
816827
817 - `BetaServerToolCaller20260120 object { tool_id, type }`
818
819 - `BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }`
828 - `BetaServerToolCaller20260120 object`
829
830 - `BetaWebFetchToolResultBlockParam object`
820831
821832 - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam`
822833
823 - `BetaWebFetchToolResultErrorBlockParam object { error_code, type }`
834 - `BetaWebFetchToolResultErrorBlockParam object`
824835
825836 - `error_code: BetaWebFetchToolResultErrorCode`
826837
from line 855
844855
845856 - `type: "web_fetch_tool_result_error"`
846857
847 - `"web_fetch_tool_result_error"`
848
849 - `BetaWebFetchBlockParam object { content, type, url, retrieved_at }`
858 - `BetaWebFetchBlockParam object`
850859
851860 - `content: BetaRequestDocumentBlock`
852861
853862 - `type: "web_fetch_result"`
854863
855 - `"web_fetch_result"`
856
857864 - `url: string`
858865
859866 Fetched content URL
from line 871
864871
865872 - `tool_use_id: string`
866873
874 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
875
867876 - `type: "web_fetch_tool_result"`
868877
869 - `"web_fetch_tool_result"`
870
871878 - `cache_control: optional BetaCacheControlEphemeral or null`
872879
873880 Create a cache control breakpoint at this content block.
from line 883
876883
877884 Tool invocation directly from the model.
878885
879 - `BetaDirectCaller object { type }`
886 - `BetaDirectCaller object`
880887
881888 Tool invocation directly from the model.
882889
883 - `BetaServerToolCaller object { tool_id, type }`
890 - `BetaServerToolCaller object`
884891
885892 Tool invocation generated by a server-side tool.
886893
887 - `BetaServerToolCaller20260120 object { tool_id, type }`
888
889 - `BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }`
894 - `BetaServerToolCaller20260120 object`
895
896 - `BetaAdvisorToolResultBlockParam object`
890897
891898 - `content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam`
892899
893 - `BetaAdvisorToolResultErrorParam object { error_code, type }`
900 - `BetaAdvisorToolResultErrorParam object`
894901
895902 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
896903
from line 917
910917
911918 - `type: "advisor_tool_result_error"`
912919
913 - `"advisor_tool_result_error"`
914
915 - `BetaAdvisorResultBlockParam object { text, type, stop_reason }`
920 - `BetaAdvisorResultBlockParam object`
916921
917922 - `text: string`
918923
919924 - `type: "advisor_result"`
920925
921 - `"advisor_result"`
922
923926 - `stop_reason: optional string or null`
924927
925 - `BetaAdvisorRedactedResultBlockParam object { encrypted_content, type, stop_reason }`
928 - `BetaAdvisorRedactedResultBlockParam object`
926929
927930 - `encrypted_content: string`
928931
from line 933
930933
931934 - `type: "advisor_redacted_result"`
932935
933 - `"advisor_redacted_result"`
934
935936 - `stop_reason: optional string or null`
936937
937938 - `tool_use_id: string`
938939
940 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
941
939942 - `type: "advisor_tool_result"`
940943
941 - `"advisor_tool_result"`
942
943944 - `cache_control: optional BetaCacheControlEphemeral or null`
944945
945946 Create a cache control breakpoint at this content block.
946947
947 - `BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
948 - `BetaCodeExecutionToolResultBlockParam object`
948949
949950 - `content: BetaCodeExecutionToolResultBlockParamContent`
950951
951952 Code execution result with encrypted stdout for PFC + web_search results.
952953
953 - `BetaCodeExecutionToolResultErrorParam object { error_code, type }`
954 - `BetaCodeExecutionToolResultErrorParam object`
954955
955956 - `error_code: BetaCodeExecutionToolResultErrorCode`
956957
from line 965
964965
965966 - `type: "code_execution_tool_result_error"`
966967
967 - `"code_execution_tool_result_error"`
968
969 - `BetaCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }`
968 - `BetaCodeExecutionResultBlockParam object`
970969
971970 - `content: array of BetaCodeExecutionOutputBlockParam`
972971
from line 973
974973
975974 - `type: "code_execution_output"`
976975
977 - `"code_execution_output"`
978
979976 - `return_code: number`
980977
981978 - `stderr: string`
from line 981
984981
985982 - `type: "code_execution_result"`
986983
987 - `"code_execution_result"`
988
989 - `BetaEncryptedCodeExecutionResultBlockParam object { content, encrypted_stdout, return_code, 2 more }`
984 - `BetaEncryptedCodeExecutionResultBlockParam object`
990985
991986 Code execution result with encrypted stdout for PFC + web_search results.
992987
from line 999
1004999
10051000 - `type: "encrypted_code_execution_result"`
10061001
1007 - `"encrypted_code_execution_result"`
1008
10091002 - `tool_use_id: string`
10101003
1004 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1005
10111006 - `type: "code_execution_tool_result"`
10121007
1013 - `"code_execution_tool_result"`
1014
10151008 - `cache_control: optional BetaCacheControlEphemeral or null`
10161009
10171010 Create a cache control breakpoint at this content block.
10181011
1019 - `BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1012 - `BetaBashCodeExecutionToolResultBlockParam object`
10201013
10211014 - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam`
10221015
1023 - `BetaBashCodeExecutionToolResultErrorParam object { error_code, type }`
1016 - `BetaBashCodeExecutionToolResultErrorParam object`
10241017
10251018 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
10261019
from line 1029
10361029
10371030 - `type: "bash_code_execution_tool_result_error"`
10381031
1039 - `"bash_code_execution_tool_result_error"`
1040
1041 - `BetaBashCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }`
1032 - `BetaBashCodeExecutionResultBlockParam object`
10421033
10431034 - `content: array of BetaBashCodeExecutionOutputBlockParam`
10441035
from line 1037
10461037
10471038 - `type: "bash_code_execution_output"`
10481039
1049 - `"bash_code_execution_output"`
1050
10511040 - `return_code: number`
10521041
10531042 - `stderr: string`
from line 1045
10561045
10571046 - `type: "bash_code_execution_result"`
10581047
1059 - `"bash_code_execution_result"`
1060
10611048 - `tool_use_id: string`
10621049
1050 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1051
10631052 - `type: "bash_code_execution_tool_result"`
10641053
1065 - `"bash_code_execution_tool_result"`
1066
10671054 - `cache_control: optional BetaCacheControlEphemeral or null`
10681055
10691056 Create a cache control breakpoint at this content block.
10701057
1071 - `BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1058 - `BetaTextEditorCodeExecutionToolResultBlockParam object`
10721059
10731060 - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam`
10741061
1075 - `BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }`
1062 - `BetaTextEditorCodeExecutionToolResultErrorParam object`
10761063
10771064 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
10781065
from line 1075
10881075
10891076 - `type: "text_editor_code_execution_tool_result_error"`
10901077
1091 - `"text_editor_code_execution_tool_result_error"`
1092
10931078 - `error_message: optional string or null`
10941079
1095 - `BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }`
1080 - `BetaTextEditorCodeExecutionViewResultBlockParam object`
10961081
10971082 - `content: string`
10981083
from line 1091
11061091
11071092 - `type: "text_editor_code_execution_view_result"`
11081093
1109 - `"text_editor_code_execution_view_result"`
1110
11111094 - `num_lines: optional number or null`
11121095
11131096 - `start_line: optional number or null`
11141097
11151098 - `total_lines: optional number or null`
11161099
1117 - `BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }`
1100 - `BetaTextEditorCodeExecutionCreateResultBlockParam object`
11181101
11191102 - `is_file_update: boolean`
11201103
11211104 - `type: "text_editor_code_execution_create_result"`
11221105
1123 - `"text_editor_code_execution_create_result"`
1124
1125 - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }`
1106 - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object`
11261107
11271108 - `type: "text_editor_code_execution_str_replace_result"`
11281109
1129 - `"text_editor_code_execution_str_replace_result"`
1130
11311110 - `lines: optional array of string or null`
11321111
11331112 - `new_lines: optional number or null`
from line 1119
11401119
11411120 - `tool_use_id: string`
11421121
1122 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1123
11431124 - `type: "text_editor_code_execution_tool_result"`
11441125
1145 - `"text_editor_code_execution_tool_result"`
1146
11471126 - `cache_control: optional BetaCacheControlEphemeral or null`
11481127
11491128 Create a cache control breakpoint at this content block.
11501129
1151 - `BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }`
1130 - `BetaToolSearchToolResultBlockParam object`
11521131
11531132 - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam`
11541133
1155 - `BetaToolSearchToolResultErrorParam object { error_code, type, error_message }`
1134 - `BetaToolSearchToolResultErrorParam object`
11561135
11571136 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
11581137
from line 1145
11661145
11671146 - `type: "tool_search_tool_result_error"`
11681147
1169 - `"tool_search_tool_result_error"`
1170
11711148 - `error_message: optional string or null`
11721149
1173 - `BetaToolSearchToolSearchResultBlockParam object { tool_references, type }`
1150 - `BetaToolSearchToolSearchResultBlockParam object`
11741151
11751152 - `tool_references: array of BetaToolReferenceBlockParam`
11761153
11771154 - `tool_name: string`
11781155
1156 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
1157
11791158 - `type: "tool_reference"`
11801159
11811160 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1163
11841163
11851164 - `type: "tool_search_tool_search_result"`
11861165
1187 - `"tool_search_tool_search_result"`
1188
11891166 - `tool_use_id: string`
11901167
1168 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
1169
11911170 - `type: "tool_search_tool_result"`
11921171
1193 - `"tool_search_tool_result"`
1194
11951172 - `cache_control: optional BetaCacheControlEphemeral or null`
11961173
11971174 Create a cache control breakpoint at this content block.
11981175
1199 - `BetaMCPToolUseBlockParam object { id, input, name, 3 more }`
1176 - `BetaMCPToolUseBlockParam object`
12001177
12011178 - `id: string`
12021179
1180 pattern: ^[a-zA-Z0-9_-]+$
1181
12031182 - `input: map[unknown]`
12041183
12051184 - `name: string`
from line 1189
12101189
12111190 - `type: "mcp_tool_use"`
12121191
1213 - `"mcp_tool_use"`
1214
12151192 - `cache_control: optional BetaCacheControlEphemeral or null`
12161193
12171194 Create a cache control breakpoint at this content block.
12181195
1219 - `BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }`
1196 - `BetaRequestMCPToolResultBlockParam object`
12201197
12211198 - `tool_use_id: string`
12221199
1200 pattern: ^[a-zA-Z0-9_-]+$
1201
12231202 - `type: "mcp_tool_result"`
12241203
1225 - `"mcp_tool_result"`
1226
12271204 - `cache_control: optional BetaCacheControlEphemeral or null`
12281205
12291206 Create a cache control breakpoint at this content block.
from line 1213
12361213
12371214 - `text: string`
12381215
1216 minLength: 1
1217
12391218 - `type: "text"`
12401219
12411220 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1225
12461225
12471226 - `is_error: optional boolean`
12481227
1249 - `BetaContainerUploadBlockParam object { file_id, type, cache_control }`
1228 - `BetaContainerUploadBlockParam object`
12501229
12511230 A content block that represents a file to be uploaded to the container
12521231 Files uploaded via this block will be available in the container's input directory.
from line 1234
12551234
12561235 - `type: "container_upload"`
12571236
1258 - `"container_upload"`
1259
12601237 - `cache_control: optional BetaCacheControlEphemeral or null`
12611238
12621239 Create a cache control breakpoint at this content block.
12631240
1264 - `BetaCompactionBlockParam object { type, cache_control, content, encrypted_content }`
1241 - `BetaCompactionBlockParam object`
12651242
12661243 A compaction block containing summary of previous context.
12671244
from line 1250
12731250
12741251 - `type: "compaction"`
12751252
1276 - `"compaction"`
1277
12781253 - `cache_control: optional BetaCacheControlEphemeral or null`
12791254
12801255 Create a cache control breakpoint at this content block.
from line 1262
12871262
12881263 Opaque metadata from prior compaction, to be round-tripped verbatim
12891264
1290 - `BetaRequestToolAdditionBlock object { tool, type, cache_control }`
1265 - `BetaRequestToolAdditionBlock object`
12911266
12921267 Mid-conversation directive to surface a declared tool.
12931268
from line 1277
13021277 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13031278 `mcp_toolset_reference` for those.
13041279
1305 - `BetaToolChangeToolReference object { name, type }`
1280 - `BetaToolChangeToolReference object`
13061281
13071282 Reference to a single tool the caller declared directly in
13081283 `tools[]`. Does not accept the composed `{server}_{name}` form the
from line 1286
13111286
13121287 - `name: string`
13131288
1289 pattern: ^[a-zA-Z0-9_-]{1,128}$
1290
13141291 - `type: "tool_reference"`
13151292
1316 - `"tool_reference"`
1317
1318 - `BetaToolChangeMCPToolReference object { name, server_name, type }`
1293 - `BetaToolChangeMCPToolReference object`
13191294
13201295 Reference to a single MCP tool by its server and remote name — the
13211296 same `server_name`/`name` pair `mcp_tool_use` carries.
from line 1301
13261301
13271302 - `type: "mcp_tool_reference"`
13281303
1329 - `"mcp_tool_reference"`
1330
1331 - `BetaToolChangeMCPToolsetReference object { server_name, type }`
1304 - `BetaToolChangeMCPToolsetReference object`
13321305
13331306 Reference to every tool in the named MCP server's toolset.
13341307
from line 1309
13361309
13371310 - `type: "mcp_toolset_reference"`
13381311
1339 - `"mcp_toolset_reference"`
1340
13411312 - `type: "tool_addition"`
13421313
1343 - `"tool_addition"`
1344
13451314 - `cache_control: optional BetaCacheControlEphemeral or null`
13461315
13471316 Create a cache control breakpoint at this content block.
13481317
1349 - `BetaRequestToolRemovalBlock object { tool, type, cache_control }`
1318 - `BetaRequestToolRemovalBlock object`
13501319
13511320 Mid-conversation directive to withdraw a tool.
13521321
from line 1330
13611330 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13621331 `mcp_toolset_reference` for those.
13631332
1364 - `BetaToolChangeToolReference object { name, type }`
1333 - `BetaToolChangeToolReference object`
13651334
13661335 Reference to a single tool the caller declared directly in
13671336 `tools[]`. Does not accept the composed `{server}_{name}` form the
13681337 server assigns to MCP-resolved tools — use `mcp_tool_reference` or
13691338 `mcp_toolset_reference` for those.
13701339
1371 - `BetaToolChangeMCPToolReference object { name, server_name, type }`
1340 - `BetaToolChangeMCPToolReference object`
13721341
13731342 Reference to a single MCP tool by its server and remote name — the
13741343 same `server_name`/`name` pair `mcp_tool_use` carries.
13751344
1376 - `BetaToolChangeMCPToolsetReference object { server_name, type }`
1345 - `BetaToolChangeMCPToolsetReference object`
13771346
13781347 Reference to every tool in the named MCP server's toolset.
13791348
13801349 - `type: "tool_removal"`
13811350
1382 - `"tool_removal"`
1383
13841351 - `cache_control: optional BetaCacheControlEphemeral or null`
13851352
13861353 Create a cache control breakpoint at this content block.
13871354
1388 - `BetaFallbackBlockParam object { from, to, type, trigger }`
1355 - `BetaFallbackBlockParam object`
13891356
13901357 A `fallback` block echoed back from a prior response.
13911358
from line 1452
14851452
14861453 - `type: "fallback"`
14871454
1488 - `"fallback"`
1489
14901455 - `trigger: optional unknown`
14911456
14921457 The response block's `trigger`, echoed verbatim. Accepted and ignored by the server; any object or `null` is allowed.
from line 1478
15131478
15141479 Container identifier for reuse across requests.
15151480
1516 - `BetaContainerParams object { id, skills }`
1481 - `BetaContainerParams object`
15171482
15181483 Container parameters with skills to be loaded.
15191484
from line 1490
15251490
15261491 List of skills to load in the container
15271492
1493 maxItems: 20
1494
15281495 - `skill_id: string`
15291496
15301497 Skill ID
15311498
1499 maxLength: 64, minLength: 1
1500
15321501 - `type: "anthropic" or "custom"`
15331502
15341503 Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
from line 1510
15411510
15421511 Skill version or 'latest' for most recent version
15431512
1513 maxLength: 64, minLength: 1
1514
15441515 - `string`
15451516
15461517- `context_management: optional BetaContextManagementConfig or null`
from line 1524
15531524
15541525 List of context management edits to apply
15551526
1556 - `BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }`
1527 minItems: 0
1528
1529 - `BetaClearToolUses20250919Edit object`
15571530
15581531 - `type: "clear_tool_uses_20250919"`
15591532
1560 - `"clear_tool_uses_20250919"`
1561
15621533 - `clear_at_least: optional BetaInputTokensClearAtLeast or null`
15631534
15641535 Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.
15651536
15661537 - `type: "input_tokens"`
15671538
1568 - `"input_tokens"`
1569
15701539 - `value: number`
15711540
1541 minimum: 0
1542
15721543 - `clear_tool_inputs: optional boolean or array of string or null`
15731544
15741545 Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)
from line 1558
15871558
15881559 - `type: "tool_uses"`
15891560
1590 - `"tool_uses"`
1591
15921561 - `value: number`
15931562
1563 minimum: 0
1564
15941565 - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger`
15951566
15961567 Condition that triggers the context management strategy
15971568
1598 - `BetaInputTokensTrigger object { type, value }`
1569 - `BetaInputTokensTrigger object`
15991570
16001571 - `type: "input_tokens"`
16011572
1602 - `"input_tokens"`
1603
16041573 - `value: number`
16051574
1606 - `BetaToolUsesTrigger object { type, value }`
1575 minimum: 1
1576
1577 - `BetaToolUsesTrigger object`
16071578
16081579 - `type: "tool_uses"`
16091580
1610 - `"tool_uses"`
1611
16121581 - `value: number`
16131582
1614 - `BetaClearThinking20251015Edit object { type, keep }`
1583 minimum: 1
1584
1585 - `BetaClearThinking20251015Edit object`
16151586
16161587 - `type: "clear_thinking_20251015"`
16171588
1618 - `"clear_thinking_20251015"`
1619
16201589 - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"`
16211590
16221591 Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.
16231592
1624 - `BetaThinkingTurns object { type, value }`
1593 - `BetaThinkingTurns object`
16251594
16261595 - `type: "thinking_turns"`
16271596
1628 - `"thinking_turns"`
1629
16301597 - `value: number`
16311598
1632 - `BetaAllThinkingTurns object { type }`
1599 minimum: 1
1600
1601 - `BetaAllThinkingTurns object`
16331602
16341603 - `type: "all"`
16351604
1636 - `"all"`
1637
16381605 - `"all"`
16391606
1640 - `"all"`
1641
1642 - `BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }`
1607 - `BetaCompact20260112Edit object`
16431608
16441609 Automatically compact older context when reaching the configured trigger threshold.
16451610
16461611 - `type: "compact_20260112"`
1647
1648 - `"compact_20260112"`
16491612
16501613 - `instructions: optional string or null`
16511614
from line 1630
16671630 - `previous_message_id: optional string or null`
16681631
16691632 The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare.
1633
1634 maxLength: 256
16701635
16711636- `fallback_credit_token: optional string or BetaFallbackCreditTokenParam or null`
16721637
from line 1658
16931658
16941659 - `string`
16951660
1696 - `BetaFallbackCreditTokenParam object { token, mode }`
1661 - `BetaFallbackCreditTokenParam object`
16971662
16981663 Object form of `fallback_credit_token`: the token plus a redemption
16991664 mode.
from line 1672
17071672
17081673 The opaque `fallback_credit_token` from a prior refusal's `stop_details` — the same string the bare-string form carries.
17091674
1675 maxLength: 2048, minLength: 1
1676
17101677 - `mode: optional "strict" or "best_effort"`
17111678
17121679 How a failing token affects the retry. `strict` (the default, and the bare-string behavior): a failing redemption is a 400 and the retry is not served. `best_effort`: the retry is served either way — a token-layer failure no longer rejects the request; the retry proceeds at normal price and the outcome is reported on the response's `usage.fallback_credit`. Two failures stay hard in both modes: a malformed token, and combining `fallback_credit_token` with `fallbacks`.
from line 1722
17551722
17561723 - `type: "json_schema"`
17571724
1758 - `"json_schema"`
1759
17601725 - `task_budget: optional BetaTokenTaskBudget or null`
17611726
17621727 User-configurable total token budget across contexts.
from line 1730
17651730
17661731 Total token budget across all contexts in the session.
17671732
1733 minimum: 1024
1734
17681735 - `type: "tokens"`
17691736
17701737 The budget type. Currently only 'tokens' is supported.
17711738
1772 - `"tokens"`
1773
17741739 - `remaining: optional number or null`
17751740
17761741 Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.
17771742
1743 minimum: 0
1744
17781745 - `speed: optional "standard" or "fast" or null`
17791746
17801747 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 1752
17851752
17861753 - `thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigAdaptive or null`
17871754
1788 - `BetaThinkingConfigEnabled object { budget_tokens, type, display }`
1755 - `BetaThinkingConfigEnabled object`
17891756
17901757 - `budget_tokens: number`
17911758
from line 1762
17951762
17961763 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
17971764
1765 minimum: 1024
1766
17981767 - `type: "enabled"`
17991768
1800 - `"enabled"`
1801
18021769 - `display: optional "summarized" or "omitted" or null`
18031770
18041771 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
from line 1774
18071774
18081775 - `"omitted"`
18091776
1810 - `BetaThinkingConfigDisabled object { type }`
1777 - `BetaThinkingConfigDisabled object`
18111778
18121779 - `type: "disabled"`
18131780
1814 - `"disabled"`
1815
1816 - `BetaThinkingConfigAdaptive object { type, display }`
1781 - `BetaThinkingConfigAdaptive object`
18171782
18181783 - `type: "adaptive"`
18191784
1820 - `"adaptive"`
1821
18221785 - `display: optional "summarized" or "omitted" or null`
18231786
18241787 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
from line 1792
18291792
18301793 - `Default = "default"`
18311794
1832 - `"default"`
1833
18341795- `inference_geo: optional string or null`
18351796
18361797 Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.
from line 1800
18391800
18401801 MCP servers to be utilized in this request
18411802
1803 maxItems: 20
1804
18421805 - `name: string`
18431806
18441807 - `type: "url"`
18451808
1846 - `"url"`
1847
18481809 - `url: string`
18491810
18501811 - `authorization_token: optional string or null`
from line 1826
18651826
18661827 This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.
18671828
1829 maxLength: 512
1830
18681831- `output_config: optional BetaOutputConfig`
18691832
18701833 Configuration options for the model's output, such as the output format.
18711834
1872- `output_format: optional BetaJSONOutputFormat or null`
1873
1874 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
1875
1876 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
1877
18781835- `service_tier: optional "auto" or "standard_only"`
18791836
18801837 Determines whether to use priority capacity (if available) or standard capacity for this request.
from line 1876
19191876
19201877 - `text: string`
19211878
1879 minLength: 1
1880
19221881 - `type: "text"`
19231882
19241883 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1886
19271886
19281887 - `citations: optional array of BetaTextCitationParam or null`
19291888
1930- `temperature: optional number`
1931
1932 Amount of randomness injected into the response.
1933
1934 Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.
1935
1936 Note that even with `temperature` of `0.0`, the results will not be fully deterministic.
1937
19381889- `thinking: optional BetaThinkingConfigParam`
19391890
19401891 Configuration for enabling Claude's extended thinking.
from line 1894
19431894
19441895 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
19451896
1946 - `BetaThinkingConfigEnabled object { budget_tokens, type, display }`
1947
1948 - `BetaThinkingConfigDisabled object { type }`
1949
1950 - `BetaThinkingConfigAdaptive object { type, display }`
1897 - `BetaThinkingConfigEnabled object`
1898
1899 - `BetaThinkingConfigDisabled object`
1900
1901 - `BetaThinkingConfigAdaptive object`
19511902
19521903- `tool_choice: optional BetaToolChoice`
19531904
19541905 How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
19551906
1956 - `BetaToolChoiceAuto object { type, disable_parallel_tool_use }`
1907 - `BetaToolChoiceAuto object`
19571908
19581909 The model will automatically decide whether to use tools.
19591910
19601911 - `type: "auto"`
19611912
1962 - `"auto"`
1963
19641913 - `disable_parallel_tool_use: optional boolean`
19651914
19661915 Whether to disable parallel tool use.
19671916
19681917 Defaults to `false`. If set to `true`, the model will output at most one tool use.
19691918
1970 - `BetaToolChoiceAny object { type, disable_parallel_tool_use }`
1919 - `BetaToolChoiceAny object`
19711920
19721921 The model will use any available tools.
19731922
19741923 - `type: "any"`
19751924
1976 - `"any"`
1977
19781925 - `disable_parallel_tool_use: optional boolean`
19791926
19801927 Whether to disable parallel tool use.
19811928
19821929 Defaults to `false`. If set to `true`, the model will output exactly one tool use.
19831930
1984 - `BetaToolChoiceTool object { name, type, disable_parallel_tool_use }`
1931 - `BetaToolChoiceTool object`
19851932
19861933 The model will use the specified tool with `tool_choice.name`.
19871934
from line 1938
19911938
19921939 - `type: "tool"`
19931940
1994 - `"tool"`
1995
19961941 - `disable_parallel_tool_use: optional boolean`
19971942
19981943 Whether to disable parallel tool use.
19991944
20001945 Defaults to `false`. If set to `true`, the model will output exactly one tool use.
20011946
2002 - `BetaToolChoiceNone object { type }`
1947 - `BetaToolChoiceNone object`
20031948
20041949 The model will not be allowed to use tools.
20051950
20061951 - `type: "none"`
2007
2008 - `"none"`
20091952
20101953- `tools: optional array of BetaToolUnion`
20111954
from line 2014
20712014
20722015 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
20732016
2074 - `BetaTool object { input_schema, name, allowed_callers, 7 more }`
2075
2076 - `input_schema: object { type, properties, required }`
2017 - `BetaTool object`
2018
2019 - `input_schema: object`
20772020
20782021 [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input.
20792022
from line 2024
20812024
20822025 - `type: "object"`
20832026
2084 - `"object"`
2085
20862027 - `properties: optional map[unknown] or null`
20872028
20882029 - `required: optional array of string or null`
from line 2034
20932034
20942035 This is how the tool will be called by the model and in `tool_use` blocks.
20952036
2037 maxLength: 128, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,128}$
2038
20962039 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
20972040
20982041 - `"direct"`
from line 2072
21292072
21302073 - `type: optional "custom" or null`
21312074
2132 - `"custom"`
2133
2134 - `BetaToolBash20241022 object { name, type, allowed_callers, 4 more }`
2075 - `BetaToolBash20241022 object`
21352076
21362077 - `name: "bash"`
21372078
from line 2080
21392080
21402081 This is how the tool will be called by the model and in `tool_use` blocks.
21412082
2142 - `"bash"`
2143
21442083 - `type: "bash_20241022"`
21452084
2146 - `"bash_20241022"`
2147
21482085 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
21492086
21502087 - `"direct"`
from line 2106
21692106
21702107 When true, guarantees schema validation on tool names and inputs
21712108
2172 - `BetaToolBash20250124 object { name, type, allowed_callers, 4 more }`
2109 - `BetaToolBash20250124 object`
21732110
21742111 - `name: "bash"`
21752112
from line 2114
21772114
21782115 This is how the tool will be called by the model and in `tool_use` blocks.
21792116
2180 - `"bash"`
2181
21822117 - `type: "bash_20250124"`
21832118
2184 - `"bash_20250124"`
2185
21862119 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
21872120
21882121 - `"direct"`
from line 2140
22072140
22082141 When true, guarantees schema validation on tool names and inputs
22092142
2210 - `BetaCodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }`
2143 - `BetaCodeExecutionTool20250522 object`
22112144
22122145 - `name: "code_execution"`
22132146
from line 2148
22152148
22162149 This is how the tool will be called by the model and in `tool_use` blocks.
22172150
2218 - `"code_execution"`
2219
22202151 - `type: "code_execution_20250522"`
22212152
2222 - `"code_execution_20250522"`
2223
22242153 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
22252154
22262155 - `"direct"`
from line 2172
22432172
22442173 When true, guarantees schema validation on tool names and inputs
22452174
2246 - `BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }`
2175 - `BetaCodeExecutionTool20250825 object`
22472176
22482177 - `name: "code_execution"`
22492178
from line 2180
22512180
22522181 This is how the tool will be called by the model and in `tool_use` blocks.
22532182
2254 - `"code_execution"`
2255
22562183 - `type: "code_execution_20250825"`
22572184
2185 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2186
2187 - `"direct"`
2188
22582189 - `"code_execution_20250825"`
22592190
2191 - `"code_execution_20260120"`
2192
2193 - `"code_execution_20260521"`
2194
2195 - `cache_control: optional BetaCacheControlEphemeral or null`
2196
2197 Create a cache control breakpoint at this content block.
2198
2199 - `defer_loading: optional boolean`
2200
2201 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
2202
2203 - `strict: optional boolean`
2204
2205 When true, guarantees schema validation on tool names and inputs
2206
2207 - `BetaCodeExecutionTool20260120 object`
2208
2209 Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
2210
2211 - `name: "code_execution"`
2212
2213 Name of the tool.
2214
2215 This is how the tool will be called by the model and in `tool_use` blocks.
2216
2217 - `type: "code_execution_20260120"`
2218
22602219 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
22612220
22622221 - `"direct"`
from line 2238
22792238
22802239 When true, guarantees schema validation on tool names and inputs
22812240
2282 - `BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }`
2283
2284 Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
2241 - `BetaCodeExecutionTool20260521 object`
2242
2243 Code execution tool with REPL state persistence.
22852244
22862245 - `name: "code_execution"`
22872246
from line 2248
22892248
22902249 This is how the tool will be called by the model and in `tool_use` blocks.
22912250
2292 - `"code_execution"`
2293
2294 - `type: "code_execution_20260120"`
2251 - `type: "code_execution_20260521"`
2252
2253 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2254
2255 - `"direct"`
2256
2257 - `"code_execution_20250825"`
22952258
22962259 - `"code_execution_20260120"`
22972260
2298 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2299
2300 - `"direct"`
2301
2302 - `"code_execution_20250825"`
2303
2304 - `"code_execution_20260120"`
2305
23062261 - `"code_execution_20260521"`
23072262
23082263 - `cache_control: optional BetaCacheControlEphemeral or null`
from line 2272
23172272
23182273 When true, guarantees schema validation on tool names and inputs
23192274
2320 - `BetaCodeExecutionTool20260521 object { name, type, allowed_callers, 3 more }`
2321
2322 Code execution tool with REPL state persistence.
2323
2324 - `name: "code_execution"`
2325
2326 Name of the tool.
2327
2328 This is how the tool will be called by the model and in `tool_use` blocks.
2329
2330 - `"code_execution"`
2331
2332 - `type: "code_execution_20260521"`
2333
2334 - `"code_execution_20260521"`
2335
2336 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
2337
2338 - `"direct"`
2339
2340 - `"code_execution_20250825"`
2341
2342 - `"code_execution_20260120"`
2343
2344 - `"code_execution_20260521"`
2345
2346 - `cache_control: optional BetaCacheControlEphemeral or null`
2347
2348 Create a cache control breakpoint at this content block.
2349
2350 - `defer_loading: optional boolean`
2351
2352 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
2353
2354 - `strict: optional boolean`
2355
2356 When true, guarantees schema validation on tool names and inputs
2357
2358 - `BetaBrowserToolset20260801 object { type, allowed_callers, cache_control, configs }`
2275 - `BetaBrowserToolset20260801 object`
23592276
23602277 The browser toolset: a single `tools[]` entry (carrying no
23612278 `name`) that declares the browser tool family. The model is served
from line 2280
23632280 from its schema.
23642281
23652282 - `type: "browser_toolset_20260801"`
2366
2367 - `"browser_toolset_20260801"`
23682283
23692284 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
23702285
from line 2676
27612676
27622677 Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
27632678
2764 - `BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }`
2679 - `BetaToolComputerUse20241022 object`
27652680
27662681 - `display_height_px: number`
27672682
27682683 The height of the display in pixels.
27692684
2685 minimum: 1
2686
27702687 - `display_width_px: number`
27712688
27722689 The width of the display in pixels.
27732690
2691 minimum: 1
2692
27742693 - `name: "computer"`
27752694
27762695 Name of the tool.
27772696
27782697 This is how the tool will be called by the model and in `tool_use` blocks.
27792698
2780 - `"computer"`
2781
27822699 - `type: "computer_20241022"`
27832700
2784 - `"computer_20241022"`
2785
27862701 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
27872702
27882703 - `"direct"`
from line 2720
28052720
28062721 The X11 display number (e.g. 0, 1) for the display.
28072722
2723 minimum: 0
2724
28082725 - `input_examples: optional array of map[unknown]`
28092726
28102727 - `strict: optional boolean`
28112728
28122729 When true, guarantees schema validation on tool names and inputs
28132730
2814 - `BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }`
2731 - `BetaMemoryTool20250818 object`
28152732
28162733 - `name: "memory"`
28172734
from line 2736
28192736
28202737 This is how the tool will be called by the model and in `tool_use` blocks.
28212738
2822 - `"memory"`
2823
28242739 - `type: "memory_20250818"`
28252740
2826 - `"memory_20250818"`
2827
28282741 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
28292742
28302743 - `"direct"`
from line 2762
28492762
28502763 When true, guarantees schema validation on tool names and inputs
28512764
2852 - `BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }`
2765 - `BetaToolComputerUse20250124 object`
28532766
28542767 - `display_height_px: number`
28552768
28562769 The height of the display in pixels.
28572770
2771 minimum: 1
2772
28582773 - `display_width_px: number`
28592774
28602775 The width of the display in pixels.
28612776
2777 minimum: 1
2778
28622779 - `name: "computer"`
28632780
28642781 Name of the tool.
28652782
28662783 This is how the tool will be called by the model and in `tool_use` blocks.
28672784
2868 - `"computer"`
2869
28702785 - `type: "computer_20250124"`
28712786
2872 - `"computer_20250124"`
2873
28742787 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
28752788
28762789 - `"direct"`
from line 2806
28932806
28942807 The X11 display number (e.g. 0, 1) for the display.
28952808
2809 minimum: 0
2810
28962811 - `input_examples: optional array of map[unknown]`
28972812
28982813 - `strict: optional boolean`
28992814
29002815 When true, guarantees schema validation on tool names and inputs
29012816
2902 - `BetaToolTextEditor20241022 object { name, type, allowed_callers, 4 more }`
2817 - `BetaToolTextEditor20241022 object`
29032818
29042819 - `name: "str_replace_editor"`
29052820
from line 2822
29072822
29082823 This is how the tool will be called by the model and in `tool_use` blocks.
29092824
2910 - `"str_replace_editor"`
2911
29122825 - `type: "text_editor_20241022"`
29132826
2914 - `"text_editor_20241022"`
2915
29162827 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
29172828
29182829 - `"direct"`
from line 2848
29372848
29382849 When true, guarantees schema validation on tool names and inputs
29392850
2940 - `BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }`
2851 - `BetaToolComputerUse20251124 object`
29412852
29422853 - `display_height_px: number`
29432854
29442855 The height of the display in pixels.
29452856
2857 minimum: 1
2858
29462859 - `display_width_px: number`
29472860
29482861 The width of the display in pixels.
29492862
2863 minimum: 1
2864
29502865 - `name: "computer"`
29512866
29522867 Name of the tool.
29532868
29542869 This is how the tool will be called by the model and in `tool_use` blocks.
29552870
2956 - `"computer"`
2957
29582871 - `type: "computer_20251124"`
29592872
2960 - `"computer_20251124"`
2961
29622873 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
29632874
29642875 - `"direct"`
from line 2892
29812892
29822893 The X11 display number (e.g. 0, 1) for the display.
29832894
2895 minimum: 0
2896
29842897 - `enable_zoom: optional boolean`
29852898
29862899 Whether to enable an action to take a zoomed-in screenshot of the screen.
from line 2904
29912904
29922905 When true, guarantees schema validation on tool names and inputs
29932906
2994 - `BetaComputerToolset20260801 object { type, allowed_callers, cache_control, configs }`
2907 - `BetaComputerToolset20260801 object`
29952908
29962909 The computer toolset: a single `tools[]` entry (carrying no
29972910 `name`) that declares the computer tool family. The model is
from line 2917
30042917
30052918 - `type: "computer_toolset_20260801"`
30062919
3007 - `"computer_toolset_20260801"`
3008
30092920 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
30102921
30112922 - `"direct"`
from line 3144
32333144
32343145 Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
32353146
3236 - `BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }`
3147 - `BetaToolTextEditor20250124 object`
32373148
32383149 - `name: "str_replace_editor"`
32393150
from line 3152
32413152
32423153 This is how the tool will be called by the model and in `tool_use` blocks.
32433154
3244 - `"str_replace_editor"`
3245
32463155 - `type: "text_editor_20250124"`
32473156
3248 - `"text_editor_20250124"`
3249
32503157 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
32513158
32523159 - `"direct"`
from line 3178
32713178
32723179 When true, guarantees schema validation on tool names and inputs
32733180
3274 - `BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }`
3181 - `BetaToolTextEditor20250429 object`
32753182
32763183 - `name: "str_replace_based_edit_tool"`
32773184
from line 3186
32793186
32803187 This is how the tool will be called by the model and in `tool_use` blocks.
32813188
3282 - `"str_replace_based_edit_tool"`
3283
32843189 - `type: "text_editor_20250429"`
32853190
3286 - `"text_editor_20250429"`
3287
32883191 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
32893192
32903193 - `"direct"`
from line 3212
33093212
33103213 When true, guarantees schema validation on tool names and inputs
33113214
3312 - `BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }`
3215 - `BetaToolTextEditor20250728 object`
33133216
33143217 - `name: "str_replace_based_edit_tool"`
33153218
from line 3220
33173220
33183221 This is how the tool will be called by the model and in `tool_use` blocks.
33193222
3320 - `"str_replace_based_edit_tool"`
3321
33223223 - `type: "text_editor_20250728"`
33233224
3324 - `"text_editor_20250728"`
3325
33263225 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33273226
33283227 - `"direct"`
from line 3246
33473246
33483247 Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.
33493248
3249 minimum: 1
3250
33503251 - `strict: optional boolean`
33513252
33523253 When true, guarantees schema validation on tool names and inputs
33533254
3354 - `BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }`
3255 - `BetaWebSearchTool20250305 object`
33553256
33563257 - `name: "web_search"`
33573258
from line 3260
33593260
33603261 This is how the tool will be called by the model and in `tool_use` blocks.
33613262
3362 - `"web_search"`
3363
33643263 - `type: "web_search_20250305"`
33653264
3366 - `"web_search_20250305"`
3367
33683265 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
33693266
33703267 - `"direct"`
from line 3292
33953292
33963293 Maximum number of times the tool can be used in the API request.
33973294
3295 exclusiveMinimum: 0
3296
33983297 - `strict: optional boolean`
33993298
34003299 When true, guarantees schema validation on tool names and inputs
from line 3304
34053304
34063305 - `type: "approximate"`
34073306
3408 - `"approximate"`
3409
34103307 - `city: optional string or null`
34113308
34123309 The city of the user.
34133310
3311 maxLength: 255, minLength: 1
3312
34143313 - `country: optional string or null`
34153314
34163315 The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.
34173316
3317 maxLength: 2, minLength: 2
3318
34183319 - `region: optional string or null`
34193320
34203321 The region of the user.
34213322
3323 maxLength: 255, minLength: 1
3324
34223325 - `timezone: optional string or null`
34233326
34243327 The [IANA timezone](https://nodatime.org/TimeZones) of the user.
34253328
3426 - `BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }`
3329 maxLength: 255, minLength: 1
3330
3331 - `BetaWebFetchTool20250910 object`
34273332
34283333 - `name: "web_fetch"`
34293334
from line 3336
34313336
34323337 This is how the tool will be called by the model and in `tool_use` blocks.
34333338
3434 - `"web_fetch"`
3435
34363339 - `type: "web_fetch_20250910"`
34373340
3438 - `"web_fetch_20250910"`
3439
34403341 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
34413342
34423343 - `"direct"`
from line 3372
34713372
34723373 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
34733374
3375 exclusiveMinimum: 0
3376
34743377 - `max_uses: optional number or null`
34753378
34763379 Maximum number of times the tool can be used in the API request.
34773380
3381 exclusiveMinimum: 0
3382
34783383 - `strict: optional boolean`
34793384
34803385 When true, guarantees schema validation on tool names and inputs
34813386
3482 - `BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }`
3387 - `BetaWebSearchTool20260209 object`
34833388
34843389 - `name: "web_search"`
34853390
from line 3392
34873392
34883393 This is how the tool will be called by the model and in `tool_use` blocks.
34893394
3490 - `"web_search"`
3491
34923395 - `type: "web_search_20260209"`
34933396
3494 - `"web_search_20260209"`
3495
34963397 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
34973398
34983399 - `"direct"`
from line 3424
35233424
35243425 Maximum number of times the tool can be used in the API request.
35253426
3427 exclusiveMinimum: 0
3428
35263429 - `strict: optional boolean`
35273430
35283431 When true, guarantees schema validation on tool names and inputs
from line 3434
35313434
35323435 Parameters for the user's location. Used to provide more relevant search results.
35333436
3534 - `BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }`
3437 - `BetaWebFetchTool20260209 object`
35353438
35363439 - `name: "web_fetch"`
35373440
from line 3442
35393442
35403443 This is how the tool will be called by the model and in `tool_use` blocks.
35413444
3542 - `"web_fetch"`
3543
35443445 - `type: "web_fetch_20260209"`
35453446
3546 - `"web_fetch_20260209"`
3547
35483447 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
35493448
35503449 - `"direct"`
from line 3478
35793478
35803479 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
35813480
3481 exclusiveMinimum: 0
3482
35823483 - `max_uses: optional number or null`
35833484
35843485 Maximum number of times the tool can be used in the API request.
35853486
3487 exclusiveMinimum: 0
3488
35863489 - `strict: optional boolean`
35873490
35883491 When true, guarantees schema validation on tool names and inputs
35893492
3590 - `BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }`
3493 - `BetaWebFetchTool20260309 object`
35913494
35923495 Web fetch tool with use_cache parameter for bypassing cached content.
35933496
from line 3500
35973500
35983501 This is how the tool will be called by the model and in `tool_use` blocks.
35993502
3600 - `"web_fetch"`
3601
36023503 - `type: "web_fetch_20260309"`
36033504
3604 - `"web_fetch_20260309"`
3605
36063505 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
36073506
36083507 - `"direct"`
from line 3536
36373536
36383537 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
36393538
3539 exclusiveMinimum: 0
3540
36403541 - `max_uses: optional number or null`
36413542
36423543 Maximum number of times the tool can be used in the API request.
36433544
3545 exclusiveMinimum: 0
3546
36443547 - `strict: optional boolean`
36453548
36463549 When true, guarantees schema validation on tool names and inputs
from line 3552
36493552
36503553 Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.
36513554
3652 - `BetaWebSearchTool20260318 object { name, type, allowed_callers, 8 more }`
3555 - `BetaWebSearchTool20260318 object`
36533556
36543557 - `name: "web_search"`
36553558
from line 3560
36573560
36583561 This is how the tool will be called by the model and in `tool_use` blocks.
36593562
3660 - `"web_search"`
3661
36623563 - `type: "web_search_20260318"`
36633564
3664 - `"web_search_20260318"`
3665
36663565 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
36673566
36683567 - `"direct"`
from line 3592
36933592
36943593 Maximum number of times the tool can be used in the API request.
36953594
3595 exclusiveMinimum: 0
3596
36963597 - `response_inclusion: optional "full" or "excluded"`
36973598
36983599 How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3610
37093610
37103611 Parameters for the user's location. Used to provide more relevant search results.
37113612
3712 - `BetaWebFetchTool20260318 object { name, type, allowed_callers, 10 more }`
3613 - `BetaWebFetchTool20260318 object`
37133614
37143615 - `name: "web_fetch"`
37153616
from line 3618
37173618
37183619 This is how the tool will be called by the model and in `tool_use` blocks.
37193620
3720 - `"web_fetch"`
3721
37223621 - `type: "web_fetch_20260318"`
37233622
3724 - `"web_fetch_20260318"`
3725
37263623 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
37273624
37283625 - `"direct"`
from line 3654
37573654
37583655 Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs.
37593656
3657 exclusiveMinimum: 0
3658
37603659 - `max_uses: optional number or null`
37613660
37623661 Maximum number of times the tool can be used in the API request.
37633662
3663 exclusiveMinimum: 0
3664
37643665 - `response_inclusion: optional "full" or "excluded"`
37653666
37663667 How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3678
37773678
37783679 Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.
37793680
3780 - `BetaAdvisorTool20260301 object { model, name, type, 7 more }`
3681 - `BetaAdvisorTool20260301 object`
37813682
37823683 - `model: Model`
37833684
from line 3692
37913692
37923693 This is how the tool will be called by the model and in `tool_use` blocks.
37933694
3794 - `"advisor"`
3795
37963695 - `type: "advisor_20260301"`
37973696
3798 - `"advisor_20260301"`
3799
38003697 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
38013698
38023699 - `"direct"`
from line 3720
38233720
38243721 Bounds the advisor's total output (thinking + text) per call. When the advisor hits this cap, the returned advisor_result or advisor_redacted_result block carries stop_reason='max_tokens', and a truncation note is appended to the advice text the worker model sees (inside the encrypted blob in redacted mode). When set, the server also emits a remaining-tokens budget block in the advisor's prompt so the advisor self-shapes toward the cap. When omitted, the advisor model's default output cap applies and no budget block is emitted.
38253722
3723 minimum: 1024
3724
38263725 - `max_uses: optional number or null`
38273726
38283727 Maximum number of times the tool can be used in the API request.
38293728
3729 exclusiveMinimum: 0
3730
38303731 - `strict: optional boolean`
38313732
38323733 When true, guarantees schema validation on tool names and inputs
38333734
3834 - `BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }`
3735 - `BetaToolSearchToolBm25_20251119 object`
38353736
38363737 - `name: "tool_search_tool_bm25"`
38373738
from line 3740
38393740
38403741 This is how the tool will be called by the model and in `tool_use` blocks.
38413742
3743 - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"`
3744
3745 - `"tool_search_tool_bm25_20251119"`
3746
38423747 - `"tool_search_tool_bm25"`
38433748
3844 - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"`
3845
3846 - `"tool_search_tool_bm25_20251119"`
3847
3848 - `"tool_search_tool_bm25"`
3849
38503749 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
38513750
38523751 - `"direct"`
from line 3768
38693768
38703769 When true, guarantees schema validation on tool names and inputs
38713770
3872 - `BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }`
3771 - `BetaToolSearchToolRegex20251119 object`
38733772
38743773 - `name: "tool_search_tool_regex"`
38753774
from line 3776
38773776
38783777 This is how the tool will be called by the model and in `tool_use` blocks.
38793778
3779 - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"`
3780
3781 - `"tool_search_tool_regex_20251119"`
3782
38803783 - `"tool_search_tool_regex"`
38813784
3882 - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"`
3883
3884 - `"tool_search_tool_regex_20251119"`
3885
3886 - `"tool_search_tool_regex"`
3887
38883785 - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
38893786
38903787 - `"direct"`
from line 3804
39073804
39083805 When true, guarantees schema validation on tool names and inputs
39093806
3910 - `BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }`
3807 - `BetaMCPToolset object`
39113808
39123809 Configuration for a group of tools from an MCP server.
39133810
from line 3815
39183815
39193816 Name of the MCP server to configure tools for
39203817
3818 maxLength: 255, minLength: 1
3819
39213820 - `type: "mcp_toolset"`
39223821
3923 - `"mcp_toolset"`
3924
39253822 - `cache_control: optional BetaCacheControlEphemeral or null`
39263823
39273824 Create a cache control breakpoint at this content block.
from line 3839
39423839
39433840 - `enabled: optional boolean`
39443841
3842- `output_format: optional BetaJSONOutputFormat or null`
3843
3844 **Deprecated**
3845
3846 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
3847
3848 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
3849
3850- `temperature: optional number`
3851
3852 **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not support setting temperature. A value of 1.0 of will be accepted for backwards compatibility, all other values will be rejected with a 400 error.
3853
3854 Amount of randomness injected into the response.
3855
3856 Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks.
3857
3858 Note that even with `temperature` of `0.0`, the results will not be fully deterministic.
3859
3860 maximum: 1, minimum: 0
3861
39453862- `top_k: optional number`
39463863
3864 **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not accept top_k; any value will be rejected with a 400 error.
3865
39473866 Only sample from the top K options for each subsequent token.
39483867
39493868 Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).
39503869
39513870 Recommended for advanced use cases only.
39523871
3872 minimum: 0
3873
39533874- `top_p: optional number`
39543875
3876 **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not support setting top_p. A value >= 0.99 will be accepted for backwards compatibility, all other values will be rejected with a 400 error.
3877
39553878 Use nucleus sampling.
39563879
39573880 In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`.
39583881
39593882 Recommended for advanced use cases only.
39603883
3961### Returns
3962
3963- `BetaMessage object { id, container, content, 9 more }`
3884 maximum: 1, minimum: 0
3885
3886## Returns
3887
3888- `BetaMessage object`
39643889
39653890 - `id: string`
39663891
from line 3905
39803905
39813906 The time at which the container will expire.
39823907
3908 format: date-time
3909
39833910 - `skills: array of BetaSkill or null`
39843911
39853912 Skills loaded in the container
from line 3915
39883915
39893916 Skill ID
39903917
3918 maxLength: 64, minLength: 1
3919
39913920 - `type: "anthropic" or "custom"`
39923921
39933922 Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
from line 3928
39993928 - `version: string`
40003929
40013930 The resolved version: a skill version ID for custom skills.
3931
3932 maxLength: 64, minLength: 1
40023933
40033934 - `content: array of BetaContentBlock`
40043935
from line 3960
40293960 [{"type": "text", "text": "B)"}]
40303961 ```
40313962
4032 - `BetaTextBlock object { citations, text, type }`
3963 - `BetaTextBlock object`
40333964
40343965 - `citations: array of BetaTextCitation or null`
40353966
from line 3968
40373968
40383969 The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`.
40393970
4040 - `BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }`
3971 - `BetaCitationCharLocation object`
40413972
40423973 - `cited_text: string`
40433974
40443975 - `document_index: number`
40453976
3977 minimum: 0
3978
40463979 - `document_title: string or null`
40473980
40483981 - `end_char_index: number`
from line 3984
40513984
40523985 - `start_char_index: number`
40533986
3987 minimum: 0
3988
40543989 - `type: "char_location"`
40553990
4056 - `"char_location"`
4057
4058 - `BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }`
3991 default: char_location
3992
3993 - `BetaCitationPageLocation object`
40593994
40603995 - `cited_text: string`
40613996
40623997 - `document_index: number`
40633998
3999 minimum: 0
4000
40644001 - `document_title: string or null`
40654002
40664003 - `end_page_number: number`
from line 4006
40694006
40704007 - `start_page_number: number`
40714008
4009 minimum: 1
4010
40724011 - `type: "page_location"`
40734012
4074 - `"page_location"`
4075
4076 - `BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }`
4013 default: page_location
4014
4015 - `BetaCitationContentBlockLocation object`
40774016
40784017 - `cited_text: string`
40794018
from line 4022
40834022
40844023 - `document_index: number`
40854024
4025 minimum: 0
4026
40864027 - `document_title: string or null`
40874028
40884029 - `end_block_index: number`
from line 4038
40974038
40984039 0-based index of the first cited block in the source's `content` array.
40994040
4041 minimum: 0
4042
41004043 - `type: "content_block_location"`
41014044
4102 - `"content_block_location"`
4103
4104 - `BetaCitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }`
4045 default: content_block_location
4046
4047 - `BetaCitationsWebSearchResultLocation object`
41054048
41064049 - `cited_text: string`
41074050
from line 4052
41094052
41104053 - `title: string or null`
41114054
4055 maxLength: 512
4056
41124057 - `type: "web_search_result_location"`
41134058
4114 - `"web_search_result_location"`
4059 default: web_search_result_location
41154060
41164061 - `url: string`
41174062
4118 - `BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }`
4063 - `BetaCitationSearchResultLocation object`
41194064
41204065 - `cited_text: string`
41214066
from line 4080
41354080
41364081 Counted separately from `document_index`; server-side web search results are not included in this count.
41374082
4083 minimum: 0
4084
41384085 - `source: string`
41394086
41404087 - `start_block_index: number`
41414088
41424089 0-based index of the first cited block in the source's `content` array.
41434090
4091 minimum: 0
4092
41444093 - `title: string or null`
41454094
41464095 - `type: "search_result_location"`
41474096
4148 - `"search_result_location"`
4097 default: search_result_location
41494098
41504099 - `text: string`
41514100
4101 maxLength: 5000000, minLength: 0
4102
41524103 - `type: "text"`
41534104
4154 - `"text"`
4155
4156 - `BetaThinkingBlock object { signature, thinking, type }`
4105 default: text
4106
4107 - `BetaThinkingBlock object`
41574108
41584109 - `signature: string`
41594110
from line 4120
41694120
41704121 - `type: "thinking"`
41714122
4172 - `"thinking"`
4173
4174 - `BetaRedactedThinkingBlock object { data, type }`
4123 default: thinking
4124
4125 - `BetaRedactedThinkingBlock object`
41754126
41764127 - `data: string`
41774128
from line 4134
41834134
41844135 - `type: "redacted_thinking"`
41854136
4186 - `"redacted_thinking"`
4187
4188 - `BetaToolUseBlock object { id, input, name, 3 more }`
4137 default: redacted_thinking
4138
4139 - `BetaToolUseBlock object`
41894140
41904141 - `id: string`
41914142
4143 pattern: ^[a-zA-Z0-9_-]+$
4144
41924145 - `input: map[unknown]`
41934146
41944147 - `name: string`
41954148
4149 minLength: 1
4150
41964151 - `type: "tool_use"`
41974152
4198 - `"tool_use"`
4153 default: tool_use
41994154
42004155 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
42014156
42024157 Tool invocation directly from the model.
42034158
4204 - `BetaDirectCaller object { type }`
4159 - `BetaDirectCaller object`
42054160
42064161 Tool invocation directly from the model.
42074162
42084163 - `type: "direct"`
42094164
4210 - `"direct"`
4211
4212 - `BetaServerToolCaller object { tool_id, type }`
4165 - `BetaServerToolCaller object`
42134166
42144167 Tool invocation generated by a server-side tool.
42154168
42164169 - `tool_id: string`
42174170
4171 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4172
42184173 - `type: "code_execution_20250825"`
42194174
4220 - `"code_execution_20250825"`
4221
4222 - `BetaServerToolCaller20260120 object { tool_id, type }`
4175 - `BetaServerToolCaller20260120 object`
42234176
42244177 - `tool_id: string`
42254178
4179 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4180
42264181 - `type: "code_execution_20260120"`
42274182
4228 - `"code_execution_20260120"`
4229
42304183 - `toolset_name: optional string or null`
42314184
42324185 For a toolset member tool_use, the toolset family.
42334186
4234 - `BetaServerToolUseBlock object { id, input, name, 2 more }`
4187 maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$
4188
4189 - `BetaServerToolUseBlock object`
42354190
42364191 - `id: string`
42374192
4193 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4194
42384195 - `input: map[unknown]`
42394196
42404197 - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 4214
42574214
42584215 - `type: "server_tool_use"`
42594216
4260 - `"server_tool_use"`
4217 default: server_tool_use
42614218
42624219 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
42634220
42644221 Tool invocation directly from the model.
42654222
4266 - `BetaDirectCaller object { type }`
4223 - `BetaDirectCaller object`
42674224
42684225 Tool invocation directly from the model.
42694226
4270 - `BetaServerToolCaller object { tool_id, type }`
4227 - `BetaServerToolCaller object`
42714228
42724229 Tool invocation generated by a server-side tool.
42734230
4274 - `BetaServerToolCaller20260120 object { tool_id, type }`
4275
4276 - `BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }`
4231 - `BetaServerToolCaller20260120 object`
4232
4233 - `BetaWebSearchToolResultBlock object`
42774234
42784235 - `content: BetaWebSearchToolResultBlockContent`
42794236
4280 - `BetaWebSearchToolResultError object { error_code, type }`
4237 - `BetaWebSearchToolResultError object`
42814238
42824239 - `error_code: BetaWebSearchToolResultErrorCode`
42834240
from line 4252
42954252
42964253 - `type: "web_search_tool_result_error"`
42974254
4298 - `"web_search_tool_result_error"`
4255 default: web_search_tool_result_error
42994256
43004257 - `array of BetaWebSearchResultBlock`
43014258
from line 4264
43074264
43084265 - `type: "web_search_result"`
43094266
4310 - `"web_search_result"`
4267 default: web_search_result
43114268
43124269 - `url: string`
43134270
43144271 - `tool_use_id: string`
43154272
4273 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4274
43164275 - `type: "web_search_tool_result"`
43174276
4318 - `"web_search_tool_result"`
4277 default: web_search_tool_result
43194278
43204279 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
43214280
43224281 Tool invocation directly from the model.
43234282
4324 - `BetaDirectCaller object { type }`
4283 - `BetaDirectCaller object`
43254284
43264285 Tool invocation directly from the model.
43274286
4328 - `BetaServerToolCaller object { tool_id, type }`
4287 - `BetaServerToolCaller object`
43294288
43304289 Tool invocation generated by a server-side tool.
43314290
4332 - `BetaServerToolCaller20260120 object { tool_id, type }`
4333
4334 - `BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }`
4291 - `BetaServerToolCaller20260120 object`
4292
4293 - `BetaWebFetchToolResultBlock object`
43354294
43364295 - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock`
43374296
4338 - `BetaWebFetchToolResultErrorBlock object { error_code, type }`
4297 - `BetaWebFetchToolResultErrorBlock object`
43394298
43404299 - `error_code: BetaWebFetchToolResultErrorCode`
43414300
from line 4318
43594318
43604319 - `type: "web_fetch_tool_result_error"`
43614320
4362 - `"web_fetch_tool_result_error"`
4363
4364 - `BetaWebFetchBlock object { content, retrieved_at, type, url }`
4321 default: web_fetch_tool_result_error
4322
4323 - `BetaWebFetchBlock object`
43654324
43664325 - `content: BetaDocumentBlock`
43674326
from line 4330
43714330
43724331 - `enabled: boolean`
43734332
4333 default: false
4334
43744335 - `source: BetaBase64PDFSource or BetaPlainTextSource`
43754336
4376 - `BetaBase64PDFSource object { data, media_type, type }`
4337 - `BetaBase64PDFSource object`
43774338
43784339 - `data: string`
43794340
4341 format: byte
4342
43804343 - `media_type: "application/pdf"`
43814344
4382 - `"application/pdf"`
4383
43844345 - `type: "base64"`
43854346
4386 - `"base64"`
4387
4388 - `BetaPlainTextSource object { data, media_type, type }`
4347 - `BetaPlainTextSource object`
43894348
43904349 - `data: string`
43914350
43924351 - `media_type: "text/plain"`
43934352
4394 - `"text/plain"`
4395
43964353 - `type: "text"`
43974354
4398 - `"text"`
4399
44004355 - `title: string or null`
44014356
44024357 The title of the document
44034358
44044359 - `type: "document"`
44054360
4406 - `"document"`
4361 default: document
44074362
44084363 - `retrieved_at: string or null`
44094364
from line 4366
44114366
44124367 - `type: "web_fetch_result"`
44134368
4414 - `"web_fetch_result"`
4369 default: web_fetch_result
44154370
44164371 - `url: string`
44174372
from line 4374
44194374
44204375 - `tool_use_id: string`
44214376
4377 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4378
44224379 - `type: "web_fetch_tool_result"`
44234380
4424 - `"web_fetch_tool_result"`
4381 default: web_fetch_tool_result
44254382
44264383 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120`
44274384
44284385 Tool invocation directly from the model.
44294386
4430 - `BetaDirectCaller object { type }`
4387 - `BetaDirectCaller object`
44314388
44324389 Tool invocation directly from the model.
44334390
4434 - `BetaServerToolCaller object { tool_id, type }`
4391 - `BetaServerToolCaller object`
44354392
44364393 Tool invocation generated by a server-side tool.
44374394
4438 - `BetaServerToolCaller20260120 object { tool_id, type }`
4439
4440 - `BetaAdvisorToolResultBlock object { content, tool_use_id, type }`
4395 - `BetaServerToolCaller20260120 object`
4396
4397 - `BetaAdvisorToolResultBlock object`
44414398
44424399 - `content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock`
44434400
4444 - `BetaAdvisorToolResultError object { error_code, type }`
4401 - `BetaAdvisorToolResultError object`
44454402
44464403 - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
44474404
from line 4418
44614418
44624419 - `type: "advisor_tool_result_error"`
44634420
4464 - `"advisor_tool_result_error"`
4465
4466 - `BetaAdvisorResultBlock object { stop_reason, text, type }`
4421 default: advisor_tool_result_error
4422
4423 - `BetaAdvisorResultBlock object`
44674424
44684425 - `stop_reason: string or null`
44694426
from line 4430
44734430
44744431 - `type: "advisor_result"`
44754432
4476 - `"advisor_result"`
4477
4478 - `BetaAdvisorRedactedResultBlock object { encrypted_content, stop_reason, type }`
4433 default: advisor_result
4434
4435 - `BetaAdvisorRedactedResultBlock object`
44794436
44804437 - `encrypted_content: string`
44814438
from line 4444
44874444
44884445 - `type: "advisor_redacted_result"`
44894446
4490 - `"advisor_redacted_result"`
4447 default: advisor_redacted_result
44914448
44924449 - `tool_use_id: string`
44934450
4451 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4452
44944453 - `type: "advisor_tool_result"`
44954454
4496 - `"advisor_tool_result"`
4497
4498 - `BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }`
4455 default: advisor_tool_result
4456
4457 - `BetaCodeExecutionToolResultBlock object`
44994458
45004459 - `content: BetaCodeExecutionToolResultBlockContent`
45014460
45024461 Code execution result with encrypted stdout for PFC + web_search results.
45034462
4504 - `BetaCodeExecutionToolResultError object { error_code, type }`
4463 - `BetaCodeExecutionToolResultError object`
45054464
45064465 - `error_code: BetaCodeExecutionToolResultErrorCode`
45074466
from line 4474
45154474
45164475 - `type: "code_execution_tool_result_error"`
45174476
4518 - `"code_execution_tool_result_error"`
4519
4520 - `BetaCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
4477 default: code_execution_tool_result_error
4478
4479 - `BetaCodeExecutionResultBlock object`
45214480
45224481 - `content: array of BetaCodeExecutionOutputBlock`
45234482
from line 4484
45254484
45264485 - `type: "code_execution_output"`
45274486
4528 - `"code_execution_output"`
4487 default: code_execution_output
45294488
45304489 - `return_code: number`
45314490
from line 4494
45354494
45364495 - `type: "code_execution_result"`
45374496
4538 - `"code_execution_result"`
4539
4540 - `BetaEncryptedCodeExecutionResultBlock object { content, encrypted_stdout, return_code, 2 more }`
4497 default: code_execution_result
4498
4499 - `BetaEncryptedCodeExecutionResultBlock object`
45414500
45424501 Code execution result with encrypted stdout for PFC + web_search results.
45434502
from line 4506
45474506
45484507 - `type: "code_execution_output"`
45494508
4509 default: code_execution_output
4510
45504511 - `encrypted_stdout: string`
45514512
45524513 - `return_code: number`
from line 4516
45554516
45564517 - `type: "encrypted_code_execution_result"`
45574518
4558 - `"encrypted_code_execution_result"`
4519 default: encrypted_code_execution_result
45594520
45604521 - `tool_use_id: string`
45614522
4523 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4524
45624525 - `type: "code_execution_tool_result"`
45634526
4564 - `"code_execution_tool_result"`
4565
4566 - `BetaBashCodeExecutionToolResultBlock object { content, tool_use_id, type }`
4527 default: code_execution_tool_result
4528
4529 - `BetaBashCodeExecutionToolResultBlock object`
45674530
45684531 - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock`
45694532
4570 - `BetaBashCodeExecutionToolResultError object { error_code, type }`
4533 - `BetaBashCodeExecutionToolResultError object`
45714534
45724535 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
45734536
from line 4546
45834546
45844547 - `type: "bash_code_execution_tool_result_error"`
45854548
4586 - `"bash_code_execution_tool_result_error"`
4587
4588 - `BetaBashCodeExecutionResultBlock object { content, return_code, stderr, 2 more }`
4549 default: bash_code_execution_tool_result_error
4550
4551 - `BetaBashCodeExecutionResultBlock object`
45894552
45904553 - `content: array of BetaBashCodeExecutionOutputBlock`
45914554
from line 4556
45934556
45944557 - `type: "bash_code_execution_output"`
45954558
4596 - `"bash_code_execution_output"`
4559 default: bash_code_execution_output
45974560
45984561 - `return_code: number`
45994562
from line 4566
46034566
46044567 - `type: "bash_code_execution_result"`
46054568
4606 - `"bash_code_execution_result"`
4569 default: bash_code_execution_result
46074570
46084571 - `tool_use_id: string`
46094572
4573 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4574
46104575 - `type: "bash_code_execution_tool_result"`
46114576
4612 - `"bash_code_execution_tool_result"`
4613
4614 - `BetaTextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }`
4577 default: bash_code_execution_tool_result
4578
4579 - `BetaTextEditorCodeExecutionToolResultBlock object`
46154580
46164581 - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock`
46174582
4618 - `BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }`
4583 - `BetaTextEditorCodeExecutionToolResultError object`
46194584
46204585 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
46214586
from line 4598
46334598
46344599 - `type: "text_editor_code_execution_tool_result_error"`
46354600
4636 - `"text_editor_code_execution_tool_result_error"`
4637
4638 - `BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }`
4601 default: text_editor_code_execution_tool_result_error
4602
4603 - `BetaTextEditorCodeExecutionViewResultBlock object`
46394604
46404605 - `content: string`
46414606
from line 4620
46554620
46564621 - `type: "text_editor_code_execution_view_result"`
46574622
4658 - `"text_editor_code_execution_view_result"`
4659
4660 - `BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }`
4623 default: text_editor_code_execution_view_result
4624
4625 - `BetaTextEditorCodeExecutionCreateResultBlock object`
46614626
46624627 - `is_file_update: boolean`
46634628
46644629 - `type: "text_editor_code_execution_create_result"`
46654630
4666 - `"text_editor_code_execution_create_result"`
4667
4668 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }`
4631 default: text_editor_code_execution_create_result
4632
4633 - `BetaTextEditorCodeExecutionStrReplaceResultBlock object`
46694634
46704635 - `lines: array of string or null`
46714636
from line 4644
46794644
46804645 - `type: "text_editor_code_execution_str_replace_result"`
46814646
4682 - `"text_editor_code_execution_str_replace_result"`
4647 default: text_editor_code_execution_str_replace_result
46834648
46844649 - `tool_use_id: string`
46854650
4651 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4652
46864653 - `type: "text_editor_code_execution_tool_result"`
46874654
4688 - `"text_editor_code_execution_tool_result"`
4689
4690 - `BetaToolSearchToolResultBlock object { content, tool_use_id, type }`
4655 default: text_editor_code_execution_tool_result
4656
4657 - `BetaToolSearchToolResultBlock object`
46914658
46924659 - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock`
46934660
4694 - `BetaToolSearchToolResultError object { error_code, error_message, type }`
4661 - `BetaToolSearchToolResultError object`
46954662
46964663 - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
46974664
from line 4674
47074674
47084675 - `type: "tool_search_tool_result_error"`
47094676
4710 - `"tool_search_tool_result_error"`
4711
4712 - `BetaToolSearchToolSearchResultBlock object { tool_references, type }`
4677 default: tool_search_tool_result_error
4678
4679 - `BetaToolSearchToolSearchResultBlock object`
47134680
47144681 - `tool_references: array of BetaToolReferenceBlock`
47154682
47164683 - `tool_name: string`
47174684
4685 maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$
4686
47184687 - `type: "tool_reference"`
47194688
4720 - `"tool_reference"`
4689 default: tool_reference
47214690
47224691 - `type: "tool_search_tool_search_result"`
47234692
4724 - `"tool_search_tool_search_result"`
4693 default: tool_search_tool_search_result
47254694
47264695 - `tool_use_id: string`
47274696
4697 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
4698
47284699 - `type: "tool_search_tool_result"`
47294700
4730 - `"tool_search_tool_result"`
4731
4732 - `BetaMCPToolUseBlock object { id, input, name, 2 more }`
4701 default: tool_search_tool_result
4702
4703 - `BetaMCPToolUseBlock object`
47334704
47344705 - `id: string`
47354706
4707 pattern: ^[a-zA-Z0-9_-]+$
4708
47364709 - `input: map[unknown]`
47374710
47384711 - `name: string`
from line 4718
47454718
47464719 - `type: "mcp_tool_use"`
47474720
4748 - `"mcp_tool_use"`
4749
4750 - `BetaMCPToolResultBlock object { content, is_error, tool_use_id, type }`
4721 default: mcp_tool_use
4722
4723 - `BetaMCPToolResultBlock object`
47514724
47524725 - `content: string or array of BetaTextBlock`
47534726
from line 4736
47634736
47644737 - `text: string`
47654738
4739 maxLength: 5000000, minLength: 0
4740
47664741 - `type: "text"`
47674742
4743 default: text
4744
47684745 - `is_error: boolean`
47694746
4747 default: false
4748
47704749 - `tool_use_id: string`
47714750
4751 pattern: ^[a-zA-Z0-9_-]+$
4752
47724753 - `type: "mcp_tool_result"`
47734754
4774 - `"mcp_tool_result"`
4775
4776 - `BetaContainerUploadBlock object { file_id, type }`
4755 default: mcp_tool_result
4756
4757 - `BetaContainerUploadBlock object`
47774758
47784759 Response model for a file uploaded to the container.
47794760
from line 4762
47814762
47824763 - `type: "container_upload"`
47834764
4784 - `"container_upload"`
4785
4786 - `BetaCompactionBlock object { content, encrypted_content, type }`
4765 default: container_upload
4766
4767 - `BetaCompactionBlock object`
47874768
47884769 A compaction block returned when autocompact is triggered.
47894770
from line 4782
48014782
48024783 - `type: "compaction"`
48034784
4804 - `"compaction"`
4805
4806 - `BetaFallbackBlock object { from, to, trigger, type }`
4785 default: compaction
4786
4787 - `BetaFallbackBlock object`
48074788
48084789 Marks the point in `content` where one model's output gives way to the next.
48094790
from line 4910
49294910
49304911 - `type: "refusal"`
49314912
4932 - `"refusal"`
4913 default: refusal
49334914
49344915 - `type: "fallback"`
49354916
4936 - `"fallback"`
4917 default: fallback
49374918
49384919 - `context_management: BetaContextManagementResponse or null`
49394920
from line 4926
49454926
49464927 List of context management edits that were applied.
49474928
4948 - `BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }`
4929 - `BetaClearToolUses20250919EditResponse object`
49494930
49504931 - `cleared_input_tokens: number`
49514932
49524933 Number of input tokens cleared by this edit.
49534934
4935 minimum: 0
4936
49544937 - `cleared_tool_uses: number`
49554938
49564939 Number of tool uses that were cleared.
49574940
4941 minimum: 0
4942
49584943 - `type: "clear_tool_uses_20250919"`
49594944
49604945 The type of context management edit applied.
49614946
4962 - `"clear_tool_uses_20250919"`
4963
4964 - `BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }`
4947 default: clear_tool_uses_20250919
4948
4949 - `BetaClearThinking20251015EditResponse object`
49654950
49664951 - `cleared_input_tokens: number`
49674952
49684953 Number of input tokens cleared by this edit.
49694954
4955 minimum: 0
4956
49704957 - `cleared_thinking_turns: number`
49714958
49724959 Number of thinking turns that were cleared.
49734960
4961 minimum: 0
4962
49744963 - `type: "clear_thinking_20251015"`
49754964
49764965 The type of context management edit applied.
49774966
4978 - `"clear_thinking_20251015"`
4967 default: clear_thinking_20251015
49794968
49804969 - `diagnostics: BetaDiagnostics or null`
49814970
from line 4975
49864975
49874976 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.
49884977
4989 - `BetaCacheMissModelChanged object { cache_missed_input_tokens, type }`
4978 - `BetaCacheMissModelChanged object`
49904979
49914980 - `cache_missed_input_tokens: number`
49924981
from line 4983
49944983
49954984 - `type: "model_changed"`
49964985
4997 - `"model_changed"`
4998
4999 - `BetaCacheMissSystemChanged object { cache_missed_input_tokens, type }`
4986 default: model_changed
4987
4988 - `BetaCacheMissSystemChanged object`
50004989
50014990 - `cache_missed_input_tokens: number`
50024991
from line 4993
50044993
50054994 - `type: "system_changed"`
50064995
5007 - `"system_changed"`
5008
5009 - `BetaCacheMissToolsChanged object { cache_missed_input_tokens, type }`
4996 default: system_changed
4997
4998 - `BetaCacheMissToolsChanged object`
50104999
50115000 - `cache_missed_input_tokens: number`
50125001
from line 5003
50145003
50155004 - `type: "tools_changed"`
50165005
5017 - `"tools_changed"`
5018
5019 - `BetaCacheMissMessagesChanged object { cache_missed_input_tokens, type }`
5006 default: tools_changed
5007
5008 - `BetaCacheMissMessagesChanged object`
50205009
50215010 - `cache_missed_input_tokens: number`
50225011
from line 5013
50245013
50255014 - `type: "messages_changed"`
50265015
5027 - `"messages_changed"`
5028
5029 - `BetaCacheMissPreviousMessageNotFound object { type }`
5016 default: messages_changed
5017
5018 - `BetaCacheMissPreviousMessageNotFound object`
50305019
50315020 - `type: "previous_message_not_found"`
50325021
5033 - `"previous_message_not_found"`
5034
5035 - `BetaCacheMissUnavailable object { type }`
5022 default: previous_message_not_found
5023
5024 - `BetaCacheMissUnavailable object`
50365025
50375026 - `type: "unavailable"`
50385027
5039 - `"unavailable"`
5028 default: unavailable
50405029
50415030 - `model: Model`
50425031
from line 5039
50505039
50515040 This will always be `"assistant"`.
50525041
5053 - `"assistant"`
5042 default: assistant
50545043
50555044 - `stop_details: BetaRefusalStopDetails or null`
50565045
from line 5126
51375126
51385127 - `type: "refusal"`
51395128
5140 - `"refusal"`
5129 default: refusal
51415130
51425131 - `stop_reason: BetaStopReason or null`
51435132
from line 5172
51835172
51845173 For Messages, this is always `"message"`.
51855174
5186 - `"message"`
5175 default: message
51875176
51885177 - `usage: BetaUsage`
51895178
from line 5194
52055194
52065195 The number of input tokens used to create the 1 hour cache entry.
52075196
5197 default: 0, minimum: 0
5198
52085199 - `ephemeral_5m_input_tokens: number`
52095200
52105201 The number of input tokens used to create the 5 minute cache entry.
52115202
5203 default: 0, minimum: 0
5204
52125205 - `cache_creation_input_tokens: number or null`
52135206
52145207 The number of input tokens used to create the cache entry.
52155208
5209 minimum: 0
5210
52165211 - `cache_read_input_tokens: number or null`
52175212
52185213 The number of input tokens read from the cache.
5214
5215 minimum: 0
52195216
52205217 - `fallback_credit: BetaFallbackCreditUsage or null`
52215218
from line 5227
52305227 resulting shift is zero because there was nothing to move. `not_applied`:
52315228 no reprice was applied; the arm's `reason` says why.
52325229
5233 - `BetaFallbackCreditRedeemed object { type }`
5230 - `BetaFallbackCreditRedeemed object`
52345231
52355232 The reprice was applied: the retry is billed as if the conversation
52365233 had been on the retry model all along.
52375234
52385235 - `type: "redeemed"`
52395236
5240 - `"redeemed"`
5241
5242 - `BetaFallbackCreditNotApplied object { reason, type, remove_to_redeem }`
5237 default: redeemed
5238
5239 - `BetaFallbackCreditNotApplied object`
52435240
52445241 No reprice was applied; `reason` says why.
52455242
from line 5273
52765273
52775274 - `type: "not_applied"`
52785275
5279 - `"not_applied"`
5276 default: not_applied
52805277
52815278 - `remove_to_redeem: optional array of string or null`
52825279
from line 5294
52975294
52985295 The number of input tokens which were used.
52995296
5297 minimum: 0
5298
53005299 - `iterations: BetaIterationsUsage or null`
53015300
53025301 Per-iteration token usage breakdown.
from line 5306
53075306 - Calculate the true context window size from the last iteration
53085307 - Understand token accumulation across server-side tool use loops
53095308
5310 - `BetaMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
5309 - `BetaMessageIterationUsage object`
53115310
53125311 Token usage for a sampling iteration.
53135312
from line 5318
53195318
53205319 The number of input tokens used to create the cache entry.
53215320
5321 default: 0, minimum: 0
5322
53225323 - `cache_read_input_tokens: number`
53235324
53245325 The number of input tokens read from the cache.
53255326
5327 default: 0, minimum: 0
5328
53265329 - `input_tokens: number`
53275330
53285331 The number of input tokens which were used.
53295332
5333 minimum: 0
5334
53305335 - `model: Model`
53315336
53325337 The model that will complete your prompt.
from line 5342
53375342
53385343 The number of output tokens which were used.
53395344
5345 minimum: 0
5346
53405347 - `type: "message"`
53415348
53425349 Usage for a sampling iteration
53435350
5344 - `"message"`
5345
5346 - `BetaCompactionIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }`
5351 default: message
5352
5353 - `BetaCompactionIterationUsage object`
53475354
53485355 Token usage for a compaction iteration.
53495356
from line 5362
53555362
53565363 The number of input tokens used to create the cache entry.
53575364
5365 default: 0, minimum: 0
5366
53585367 - `cache_read_input_tokens: number`
53595368
53605369 The number of input tokens read from the cache.
53615370
5371 default: 0, minimum: 0
5372
53625373 - `input_tokens: number`
53635374
53645375 The number of input tokens which were used.
53655376
5377 minimum: 0
5378
53665379 - `output_tokens: number`
53675380
53685381 The number of output tokens which were used.
53695382
5383 minimum: 0
5384
53705385 - `type: "compaction"`
53715386
53725387 Usage for a compaction iteration
53735388
5374 - `"compaction"`
5375
5376 - `BetaAdvisorMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
5389 default: compaction
5390
5391 - `BetaAdvisorMessageIterationUsage object`
53775392
53785393 Token usage for an advisor sub-inference iteration.
53795394
from line 5400
53855400
53865401 The number of input tokens used to create the cache entry.
53875402
5403 default: 0, minimum: 0
5404
53885405 - `cache_read_input_tokens: number`
53895406
53905407 The number of input tokens read from the cache.
53915408
5409 default: 0, minimum: 0
5410
53925411 - `input_tokens: number`
53935412
53945413 The number of input tokens which were used.
53955414
5415 minimum: 0
5416
53965417 - `model: Model`
53975418
53985419 The model that will complete your prompt.
from line 5424
54035424
54045425 The number of output tokens which were used.
54055426
5427 minimum: 0
5428
54065429 - `type: "advisor_message"`
54075430
54085431 Usage for an advisor sub-inference iteration
54095432
5410 - `"advisor_message"`
5411
5412 - `BetaFallbackMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }`
5433 default: advisor_message
5434
5435 - `BetaFallbackMessageIterationUsage object`
54135436
54145437 Token usage for the fallback-model attempt of a server-side fallback request.
54155438
from line 5449
54265449
54275450 The number of input tokens used to create the cache entry.
54285451
5452 default: 0, minimum: 0
5453
54295454 - `cache_read_input_tokens: number`
54305455
54315456 The number of input tokens read from the cache.
54325457
5458 default: 0, minimum: 0
5459
54335460 - `input_tokens: number`
54345461
54355462 The number of input tokens which were used.
54365463
5464 minimum: 0
5465
54375466 - `model: Model`
54385467
54395468 The model that will complete your prompt.
from line 5473
54445473
54455474 The number of output tokens which were used.
54465475
5476 minimum: 0
5477
54475478 - `type: "fallback_message"`
54485479
54495480 Usage for the fallback-model attempt that served the response
54505481
5451 - `"fallback_message"`
5482 default: fallback_message
54525483
54535484 - `output_tokens: number`
54545485
54555486 The number of output tokens which were used.
5487
5488 minimum: 0
54565489
54575490 - `output_tokens_details: BetaOutputTokensDetails or null`
54585491
from line 5507
54745507 generation count by a small number of tokens. Always ≤ `output_tokens`;
54755508 `output_tokens - thinking_tokens` approximates the non-reasoning output.
54765509
5510 default: 0, minimum: 0
5511
54775512 - `server_tool_use: BetaServerToolUsage or null`
54785513
54795514 The number of server tool requests.
from line 5517
54825517
54835518 The number of web fetch tool requests.
54845519
5520 default: 0, minimum: 0
5521
54855522 - `web_search_requests: number`
54865523
54875524 The number of web search tool requests.
54885525
5526 default: 0, minimum: 0
5527
54895528 - `service_tier: "standard" or "priority" or "batch" or null`
54905529
54915530 If the request used the priority, standard, or batch tier.
from line 5543
55045543
55055544 - `"fast"`
55065545
5507### Example
5508
5509```http
5546- `BetaRawMessageStreamEvent = BetaRawMessageStartEvent or BetaRawMessageDeltaEvent or BetaRawMessageStopEvent or 3 more`
5547
5548 - `BetaRawMessageStartEvent object`
5549
5550 - `message: BetaMessage`
5551
5552 - `type: "message_start"`
5553
5554 default: message_start
5555
5556 - `BetaRawMessageDeltaEvent object`
5557
5558 - `context_management: BetaContextManagementResponse or null`
5559
5560 Information about context management strategies applied during the request
5561
5562 - `delta: object`
5563
5564 - `container: BetaContainer or null`
5565
5566 Information about the container used in the request (for the code execution tool)
5567
5568 - `stop_details: BetaRefusalStopDetails or null`
5569
5570 Structured information about a refusal.
5571
5572 - `stop_reason: BetaStopReason or null`
5573
5574 - `stop_sequence: string or null`
5575
5576 - `type: "message_delta"`
5577
5578 default: message_delta
5579
5580 - `usage: BetaMessageDeltaUsage`
5581
5582 Billing and rate-limit usage.
5583
5584 Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.
5585
5586 Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response.
5587
5588 For example, `output_tokens` will be non-zero, even for an empty string response from Claude.
5589
5590 Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.
5591
5592 - `cache_creation_input_tokens: number or null`
5593
5594 The cumulative number of input tokens used to create the cache entry.
5595
5596 minimum: 0
5597
5598 - `cache_read_input_tokens: number or null`
5599
5600 The cumulative number of input tokens read from the cache.
5601
5602 minimum: 0
5603
5604 - `fallback_credit: BetaFallbackCreditUsage or null`
5605
5606 Outcome of the `fallback_credit_token` presented on this request.
5607
5608 - `input_tokens: number or null`
5609
5610 The cumulative number of input tokens which were used.
5611
5612 minimum: 0
5613
5614 - `iterations: BetaIterationsUsage or null`
5615
5616 Per-iteration token usage breakdown.
5617
5618 Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to:
5619
5620 - Determine which iterations exceeded long context thresholds (>=200k tokens)
5621 - Calculate the true context window size from the last iteration
5622 - Understand token accumulation across server-side tool use loops
5623
5624 - `output_tokens: number`
5625
5626 The cumulative number of output tokens which were used.
5627
5628 - `output_tokens_details: BetaOutputTokensDetails or null`
5629
5630 Breakdown of output tokens by category.
5631
5632 `output_tokens` remains the inclusive, authoritative total used for billing.
5633 This object provides a read-only decomposition for observability — for example,
5634 how many of the billed output tokens were spent on internal reasoning that may
5635 have been summarized before being returned to you.
5636
5637 - `server_tool_use: BetaServerToolUsage or null`
5638
5639 The number of server tool requests.
5640
5641 - `BetaRawMessageStopEvent object`
5642
5643 - `type: "message_stop"`
5644
5645 default: message_stop
5646
5647 - `BetaRawContentBlockStartEvent object`
5648
5649 - `content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 14 more`
5650
5651 Response model for a file uploaded to the container.
5652
5653 - `BetaTextBlock object`
5654
5655 - `BetaThinkingBlock object`
5656
5657 - `BetaRedactedThinkingBlock object`
5658
5659 - `BetaToolUseBlock object`
5660
5661 - `BetaServerToolUseBlock object`
5662
5663 - `BetaWebSearchToolResultBlock object`
5664
5665 - `BetaWebFetchToolResultBlock object`
5666
5667 - `BetaAdvisorToolResultBlock object`
5668
5669 - `BetaCodeExecutionToolResultBlock object`
5670
5671 - `BetaBashCodeExecutionToolResultBlock object`
5672
5673 - `BetaTextEditorCodeExecutionToolResultBlock object`
5674
5675 - `BetaToolSearchToolResultBlock object`
5676
5677 - `BetaMCPToolUseBlock object`
5678
5679 - `BetaMCPToolResultBlock object`
5680
5681 - `BetaContainerUploadBlock object`
5682
5683 Response model for a file uploaded to the container.
5684
5685 - `BetaCompactionBlock object`
5686
5687 A compaction block returned when autocompact is triggered.
5688
5689 When content is None, it indicates the compaction failed to produce a valid
5690 summary (e.g., malformed output from the model). Clients may round-trip
5691 compaction blocks with null content; the server treats them as no-ops.
5692
5693 - `BetaFallbackBlock object`
5694
5695 Marks the point in `content` where one model's output gives way to the next.
5696
5697 One block appears per hop where a preceding model actually ran this turn and
5698 declined. A turn where no preceding model ran and declined has no such
5699 boundary and carries no block — the signal for whether a fallback model
5700 served the response is the presence of a `fallback_message` entry in
5701 `usage.iterations`, not this block.
5702
5703 The block is treated like a server-tool content block for streaming: it
5704 arrives via the standard `content_block_start` / `content_block_stop`
5705 pair and carries no deltas.
5706
5707 - `index: number`
5708
5709 - `type: "content_block_start"`
5710
5711 default: content_block_start
5712
5713 - `BetaRawContentBlockDeltaEvent object`
5714
5715 - `delta: BetaRawContentBlockDelta`
5716
5717 - `BetaTextDelta object`
5718
5719 - `text: string`
5720
5721 - `type: "text_delta"`
5722
5723 default: text_delta
5724
5725 - `BetaInputJSONDelta object`
5726
5727 - `partial_json: string`
5728
5729 - `type: "input_json_delta"`
5730
5731 default: input_json_delta
5732
5733 - `BetaCitationsDelta object`
5734
5735 - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more`
5736
5737 - `BetaCitationCharLocation object`
5738
5739 - `BetaCitationPageLocation object`
5740
5741 - `BetaCitationContentBlockLocation object`
5742
5743 - `BetaCitationsWebSearchResultLocation object`
5744
5745 - `BetaCitationSearchResultLocation object`
5746
5747 - `type: "citations_delta"`
5748
5749 default: citations_delta
5750
5751 - `BetaThinkingDelta object`
5752
5753 - `estimated_tokens: number or null`
5754
5755 Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the `thinking-token-count-2026-05-13` beta is set; `null` unless `thinking.display` resolves to `"omitted"` and a count is due this frame. Sum the increments across `thinking_delta` frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; `usage.output_tokens` remains authoritative.
5756
5757 - `thinking: string`
5758
5759 The incremental `thinking` text for this content block. Concatenate the `thinking` values of successive `thinking_delta` events to assemble the block's full `thinking` value.
5760
5761 - `type: "thinking_delta"`
5762
5763 default: thinking_delta
5764
5765 - `BetaSignatureDelta object`
5766
5767 - `signature: string`
5768
5769 The `signature` for this thinking block: an opaque value used to verify that the block was generated by Claude when it is passed back to the API. Delivered in a `signature_delta` event just before the block's `content_block_stop` event.
5770
5771 - `type: "signature_delta"`
5772
5773 default: signature_delta
5774
5775 - `BetaCompactionContentBlockDelta object`
5776
5777 - `content: string or null`
5778
5779 - `encrypted_content: string or null`
5780
5781 Opaque metadata from prior compaction, to be round-tripped verbatim
5782
5783 - `type: "compaction_delta"`
5784
5785 default: compaction_delta
5786
5787 - `index: number`
5788
5789 - `type: "content_block_delta"`
5790
5791 default: content_block_delta
5792
5793 - `BetaRawContentBlockStopEvent object`
5794
5795 - `index: number`
5796
5797 - `type: "content_block_stop"`
5798
5799 default: content_block_stop
5800
5801## Example
5802
5803```bash
55105804curl https://api.anthropic.com/v1/messages \
55115805 -H 'Content-Type: application/json' \
55125806 -H 'anthropic-version: 2023-06-01' \
from line 5846
55525846 }'
55535847```
55545848
5555#### Response
5849### Response (200)
55565850
55575851```json
55585852{
55595853
api/beta/models Changed · +30 / -27 lines
### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types
from line 1
1---
2title: Models
3url: https://platform.claude.com/docs/en/api/beta/models
4---
5
61# Models
72
83## List Models
94
10**get** `/v1/models`
5**GET** `/v1/models`
116
127List available models.
138
149The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first.
1510
16### Query Parameters
11### Query parameters
1712
1813- `after_id: optional string`
1914
from line 24
2924
3025 Defaults to `20`. Ranges from `1` to `1000`.
3126
32### Header Parameters
27 default: 20, maximum: 1000, minimum: 1
3328
29### Headers
30
3431- `"anthropic-beta": optional array of AnthropicBeta`
3532
3633 Optional header to specify the beta version(s) you want to use.
from line 220
223220
224221 RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.
225222
223 format: date-time
224
226225 - `display_name: string`
227226
228227 A human-readable name for the model.
from line 240
241240
242241 For Models, this is always `"model"`.
243242
244 - `"model"`
243 default: model
245244
246245- `first_id: string or null`
247246
from line 256
257256
258257### Example
259258
260```http
259```bash
261260curl https://api.anthropic.com/v1/models \
262261 -H 'anthropic-version: 2023-06-01' \
263262 -H "X-Api-Key: $ANTHROPIC_API_KEY"
264263```
265264
266#### Response
265#### Response (200)
267266
268267```json
269268{
from line 348
349348
350349## Get a Model
351350
352**get** `/v1/models/{model_id}`
351**GET** `/v1/models/{model_id}`
353352
354353Get a specific model.
355354
356355The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID.
357356
358### Path Parameters
357### Path parameters
359358
360359- `model_id: string`
361360
362361 Model identifier or alias.
363362
364### Header Parameters
363### Headers
365364
366365- `"anthropic-beta": optional array of AnthropicBeta`
367366
from line 440
441440
442441### Returns
443442
444- `BetaModelInfo object { id, allowed_fallback_models, capabilities, 5 more }`
443- `BetaModelInfo object`
445444
446445 - `id: string`
447446
from line 554
555554
556555 RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.
557556
557 format: date-time
558
558559 - `display_name: string`
559560
560561 A human-readable name for the model.
from line 574
573574
574575 For Models, this is always `"model"`.
575576
576 - `"model"`
577 default: model
577578
578579### Example
579580
580```http
581```bash
581582curl https://api.anthropic.com/v1/models/$MODEL_ID \
582583 -H 'anthropic-version: 2023-06-01' \
583584 -H "X-Api-Key: $ANTHROPIC_API_KEY"
584585```
585586
586#### Response
587#### Response (200)
587588
588589```json
589590{
from line 661
660661}
661662```
662663
663## Domain Types
664## Domain types
664665
665666### Beta Capability Support
666667
667- `BetaCapabilitySupport object { supported }`
668- `BetaCapabilitySupport object`
668669
669670 Indicates whether a capability is supported.
670671
from line 675
674675
675676### Beta Context Management Capability
676677
677- `BetaContextManagementCapability object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }`
678- `BetaContextManagementCapability object`
678679
679680 Context management capability details.
680681
from line 701
700701
701702### Beta Effort Capability
702703
703- `BetaEffortCapability object { high, low, max, 3 more }`
704- `BetaEffortCapability object`
704705
705706 Effort (reasoning_effort) capability details.
706707
from line 735
734735
735736### Beta Model Capabilities
736737
737- `BetaModelCapabilities object { batch, citations, code_execution, 6 more }`
738- `BetaModelCapabilities object`
738739
739740 Model capability information.
740741
from line 837
836837
837838### Beta Model Info
838839
839- `BetaModelInfo object { id, allowed_fallback_models, capabilities, 5 more }`
840- `BetaModelInfo object`
840841
841842 - `id: string`
842843
from line 951
950951
951952 RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.
952953
954 format: date-time
955
953956 - `display_name: string`
954957
955958 A human-readable name for the model.
from line 971
968971
969972 For Models, this is always `"model"`.
970973
971 - `"model"`
974 default: model
972975
973976### Beta Thinking Capability
974977
975- `BetaThinkingCapability object { supported, types }`
978- `BetaThinkingCapability object`
976979
977980 Thinking capability details.
978981
from line 1001
9981001
9991002### Beta Thinking Types
10001003
1001- `BetaThinkingTypes object { adaptive, enabled }`
1004- `BetaThinkingTypes object`
10021005
10031006 Supported thinking type configurations.
10041007
api/beta/models/list Changed · +15 / -16 lines
# List Models ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Models ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Models
3url: https://platform.claude.com/docs/en/api/beta/models/list
4---
1# List Models
52
6## List Models
3**GET** `/v1/models`
74
8**get** `/v1/models`
9
105List available models.
116
127The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first.
138
14### Query Parameters
9## Query parameters
1510
1611- `after_id: optional string`
1712
from line 22
2722
2823 Defaults to `20`. Ranges from `1` to `1000`.
2924
30### Header Parameters
25 default: 20, maximum: 1000, minimum: 1
3126
27## Headers
28
3229- `"anthropic-beta": optional array of AnthropicBeta`
3330
3431 Optional header to specify the beta version(s) you want to use.
from line 102
105102
106103 - `"mid-conversation-tool-changes-2026-07-01"`
107104
108### Returns
105## Returns
109106
110107- `data: array of BetaModelInfo`
111108
from line 218
221218
222219 RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.
223220
221 format: date-time
222
224223 - `display_name: string`
225224
226225 A human-readable name for the model.
from line 238
239238
240239 For Models, this is always `"model"`.
241240
242 - `"model"`
241 default: model
243242
244243- `first_id: string or null`
245244
from line 252
253252
254253 Last ID in the `data` list. Can be used as the `after_id` for the next page.
255254
256### Example
255## Example
257256
258```http
257```bash
259258curl https://api.anthropic.com/v1/models \
260259 -H 'anthropic-version: 2023-06-01' \
261260 -H "X-Api-Key: $ANTHROPIC_API_KEY"
262261```
263262
264#### Response
263### Response (200)
265264
266265```json
267266{
api/beta/models/retrieve Changed · +16 / -19 lines
# Get a Model ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get a Model ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get a Model
3url: https://platform.claude.com/docs/en/api/beta/models/retrieve
4---
1# Get a Model
52
6## Get a Model
3**GET** `/v1/models/{model_id}`
74
8**get** `/v1/models/{model_id}`
9
105Get a specific model.
116
127The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID.
138
14### Path Parameters
9## Path parameters
1510
1611- `model_id: string`
1712
1813 Model identifier or alias.
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
100- `BetaModelInfo object { id, allowed_fallback_models, capabilities, 5 more }`
95- `BetaModelInfo object`
10196
10297 - `id: string`
10398
from line 206
211206
212207 RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.
213208
209 format: date-time
210
214211 - `display_name: string`
215212
216213 A human-readable name for the model.
from line 226
229226
230227 For Models, this is always `"model"`.
231228
232 - `"model"`
229 default: model
233230
234### Example
231## Example
235232
236```http
233```bash
237234curl https://api.anthropic.com/v1/models/$MODEL_ID \
238235 -H 'anthropic-version: 2023-06-01' \
239236 -H "X-Api-Key: $ANTHROPIC_API_KEY"
240237```
241238
242#### Response
239### Response (200)
243240
244241```json
245242{
api/beta/sessions Changed · +5698 / -19015 lines
### Headers ### Body parameters #### Response (200) ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ## Sessions › Events ### List Events #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Send Events #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Stream Events #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ## Sessions › Resources ### Add Session Resource #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Session Resources #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Session Resource #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Session Resource #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Delete Session Resource #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Sessions › Threads ### List Session Threads #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Get Session Thread #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Archive Session Thread #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ## Sessions › 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) ### Header Parameters ### Body Parameters #### Response ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types # Events ## List Events ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Send Events ### Path Parameters ### Header Parameters ### Body Parameters #### Response ## Stream Events ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Domain Types ### Beta Managed Agents Agent Custom Tool Use Event ### Beta Managed Agents Agent MCP Tool Result Event ### Beta Managed Agents Agent MCP Tool Use Event ### Beta Managed Agents Agent Message Event ### Beta Managed Agents Agent Thinking Event ### Beta Managed Agents Agent Thread Context Compacted Event ### Beta Managed Agents Agent Thread Message Received Event ### Beta Managed Agents Agent Thread Message Sent Event ### Beta Managed Agents Agent Tool Result Event ### Beta Managed Agents Agent Tool Use Event ### Beta Managed Agents Base64 Document Source ### Beta Managed Agents Base64 Image Source ### Beta Managed Agents Billing Error ### Beta Managed Agents Credential Host Unreachable Error ### Beta Managed Agents Document Block ### Beta Managed Agents Event Params ### Beta Managed Agents File Document Source ### Beta Managed Agents File Image Source ### Beta Managed Agents File Rubric ### Beta Managed Agents File Rubric Params ### Beta Managed Agents Image Block ### Beta Managed Agents MCP Authentication Failed Error ### Beta Managed Agents MCP Connection Failed Error ### Beta Managed Agents Model Overloaded Error ### Beta Managed Agents Model Rate Limited Error ### Beta Managed Agents Model Request Failed Error ### Beta Managed Agents Plain Text Document Source ### Beta Managed Agents Redacted Block ### Beta Managed Agents Retry Status Exhausted ### Beta Managed Agents Retry Status Retrying ### Beta Managed Agents Retry Status Terminal ### Beta Managed Agents Search Result Block ### Beta Managed Agents Search Result Citations ### Beta Managed Agents Search Result Content ### Beta Managed Agents Send Session Events ### Beta Managed Agents Session Budget Reached ### Beta Managed Agents Session Deleted Event ### Beta Managed Agents Session End Turn ### Beta Managed Agents Session Error Event ### Beta Managed Agents Session Event ### Beta Managed Agents Session Requires Action ### Beta Managed Agents Session Retries Exhausted ### Beta Managed Agents Session Status Idle Event ### Beta Managed Agents Session Status Rescheduled Event ### Beta Managed Agents Session Status Running Event ### Beta Managed Agents Session Status Terminated Event ### Beta Managed Agents Session Thread Created Event ### Beta Managed Agents Session Thread Status Idle Event ### Beta Managed Agents Session Thread Status Rescheduled Event ### Beta Managed Agents Session Thread Status Running Event ### Beta Managed Agents Session Thread Status Terminated Event ### Beta Managed Agents Session Usage Snapshot ### Beta Managed Agents Span Model Request End Event ### Beta Managed Agents Span Model Request Start Event ### Beta Managed Agents Span Model Usage ### Beta Managed Agents Span Outcome Evaluation End Event ### Beta Managed Agents Span Outcome Evaluation Ongoing Event ### Beta Managed Agents Span Outcome Evaluation Start Event ### Beta Managed Agents Stream Session Events ### Beta Managed Agents System Message Event Params ### Beta Managed Agents Text Block ### Beta Managed Agents Text Rubric ### Beta Managed Agents Text Rubric Params ### Beta Managed Agents Unknown Error ### Beta Managed Agents URL Document Source ### Beta Managed Agents URL Image Source ### Beta Managed Agents User Custom Tool Result Event ### Beta Managed Agents User Custom Tool Result Event Params ### Beta Managed Agents User Define Outcome Event ### Beta Managed Agents User Define Outcome Event Params ### Beta Managed Agents User Interrupt Event ### Beta Managed Agents User Interrupt Event Params ### Beta Managed Agents User Message Event ### Beta Managed Agents User Message Event Params ### Beta Managed Agents User Tool Confirmation Event ### Beta Managed Agents User Tool Confirmation Event Params ### Beta Managed Agents User Tool Result Event Params # Resources ## Add Session Resource ### Path Parameters ### Header Parameters ### Body Parameters #### Response ## List Session Resources ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Get Session Resource ### Path Parameters ### Header Parameters #### Response ## Update Session Resource ### Path Parameters ### Header Parameters ### Body Parameters #### Response ## Delete Session Resource ### Path Parameters ### Header Parameters #### Response ## Domain Types ### Beta Managed Agents Delete Session Resource ### Beta Managed Agents File Resource ### Beta Managed Agents GitHub Repository Resource ### Beta Managed Agents Memory Store Resource ### Beta Managed Agents Session Resource ### Resource Retrieve Response ### Resource Update Response # Threads ## List Session Threads ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Get Session Thread ### Path Parameters ### Header Parameters #### Response ## Archive Session Thread ### Path Parameters ### Header Parameters #### Response ## Domain Types ### Beta Managed Agents Session Thread ### Beta Managed Agents Session Thread Stats ### Beta Managed Agents Session Thread Status ### Beta Managed Agents Session Thread Usage ### Beta Managed Agents Stream Session Thread Events # 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/archive Changed · +122 / -159 lines
# Archive Session ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Archive Session ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Archive Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/archive
4---
1# Archive Session
52
6## Archive Session
3**POST** `/v1/sessions/{session_id}/archive`
74
8**post** `/v1/sessions/{session_id}/archive`
9
105Archive 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/archive \
964927 -X POST \
965928 -H 'anthropic-version: 2023-06-01' \
from line 930
967930 -H "X-Api-Key: $ANTHROPIC_API_KEY"
968931```
969932
970#### Response
933### Response (200)
971934
972935```json
973936{
api/beta/sessions/create Changed · +267 / -334 lines
# Create Session ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create Session ### 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: Create Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/create
4---
5
6## Create Session
7
8**post** `/v1/sessions`
1# Create Session
2
3**POST** `/v1/sessions`
94
105Create Session
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### Body Parameters
85## Body parameters
9186
9287- `agent: string or BetaManagedAgentsAgentParams or BetaManagedAgentsAgentWithOverridesParams`
9388
from line 90
9590
9691 - `string`
9792
98 - `BetaManagedAgentsAgentParams object { id, type, version }`
93 - `BetaManagedAgentsAgentParams object`
9994
10095 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
10196
from line 98
10398
10499 The `agent` ID.
105100
101 minLength: 1, maxLength: 128
102
106103 - `type: "agent"`
107104
108 - `"agent"`
109
110105 - `version: optional number`
111106
112107 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
113108
114 - `BetaManagedAgentsAgentWithOverridesParams object { id, type, mcp_servers, 5 more }`
109 format: int32
110
111 - `BetaManagedAgentsAgentWithOverridesParams object`
115112
116113 Reference to an `agent` plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged.
117114
from line 116
119116
120117 The `agent` ID.
121118
119 minLength: 1, maxLength: 128
120
122121 - `type: "agent_with_overrides"`
123122
124 - `"agent_with_overrides"`
125
126123 - `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams`
127124
128125 Replacement MCP server list. Full replacement: the provided array becomes the MCP servers. Send an empty array to clear; omit to preserve the agent's servers.
from line 128
131128
132129 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
133130
131 minLength: 1, maxLength: 255
132
134133 - `type: "url"`
135134
136 - `"url"`
137
138135 - `url: string`
139136
140137 Endpoint URL for the MCP server.
141138
139 maxLength: 2048
140
142141 - `model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams`
143142
144143 Replacement model. Accepts the model string, e.g. `claude-opus-5`, or a `model_config` object. Omit to use the agent's model.
from line 208
209208
210209 - `string`
211210
212 - `BetaManagedAgentsModelConfigParams object { id, effort, inference_geo, speed }`
211 - `BetaManagedAgentsModelConfigParams object`
213212
214213 An object that defines additional configuration control over model use
215214
from line 236
237236
238237 - `"max"`
239238
240 - `BetaManagedAgentsEffortLow object { type }`
239 - `BetaManagedAgentsEffortLow object`
241240
242241 Low effort. Favors latency over reasoning depth.
243242
244243 - `type: "low"`
245244
246 - `"low"`
247
248 - `BetaManagedAgentsEffortMedium object { type }`
245 - `BetaManagedAgentsEffortMedium object`
249246
250247 Medium effort. Balances latency and reasoning depth.
251248
252249 - `type: "medium"`
253250
254 - `"medium"`
255
256 - `BetaManagedAgentsEffortHigh object { type }`
251 - `BetaManagedAgentsEffortHigh object`
257252
258253 High effort. Favors reasoning depth.
259254
260255 - `type: "high"`
261256
262 - `"high"`
263
264 - `BetaManagedAgentsEffortXhigh object { type }`
257 - `BetaManagedAgentsEffortXhigh object`
265258
266259 Extra-high effort. Not all models accept this level.
267260
268261 - `type: "xhigh"`
269262
270 - `"xhigh"`
271
272 - `BetaManagedAgentsEffortMax object { type }`
263 - `BetaManagedAgentsEffortMax object`
273264
274265 Maximum effort. Favors reasoning depth over latency.
275266
276267 - `type: "max"`
277268
278 - `"max"`
279
280269 - `inference_geo: optional string or null`
281270
282271 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it.
from line 282
293282
294283 Replacement skill list. Full replacement: the provided array becomes the skills. Send an empty array to clear; omit to preserve the agent's skills.
295284
296 - `BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }`
285 - `BetaManagedAgentsAnthropicSkillParams object`
297286
298287 An Anthropic-managed skill.
299288
from line 290
301290
302291 Identifier of the Anthropic skill (e.g., "xlsx").
303292
293 minLength: 1, maxLength: 64
294
304295 - `type: "anthropic"`
305296
306 - `"anthropic"`
307
308297 - `version: optional string or null`
309298
310299 Version to pin. Defaults to latest if omitted.
311300
312 - `BetaManagedAgentsCustomSkillParams object { skill_id, type, version }`
301 minLength: 1, maxLength: 64
302
303 - `BetaManagedAgentsCustomSkillParams object`
313304
314305 A user-created custom skill.
315306
from line 308
317308
318309 Tagged ID of the custom skill (e.g., "skill_01XJ5...").
319310
311 minLength: 1, maxLength: 64
312
320313 - `type: "custom"`
321314
322 - `"custom"`
323
324315 - `version: optional string or null`
325316
326317 Version to pin. Defaults to latest if omitted.
327318
319 minLength: 1, maxLength: 64
320
328321 - `system: optional string or null`
329322
330323 Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it.
331324
325 maxLength: 100000
326
332327 - `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams`
333328
334329 Replacement tool list. Full replacement: the provided array becomes the tool configuration. Send an empty array to clear; omit to preserve the agent's tools.
335330
336 - `BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }`
331 - `BetaManagedAgentsAgentToolset20260401Params object`
337332
338333 Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
339334
340335 - `type: "agent_toolset_20260401"`
341336
342 - `"agent_toolset_20260401"`
343
344337 - `configs: optional array of BetaManagedAgentsAgentToolConfigParams`
345338
346339 Per-tool configuration overrides.
347340
348 - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }`
341 - `BetaManagedAgentsBashToolConfigParams object`
349342
350343 Configuration override for the bash tool.
351344
from line 346
353346
354347 Must be "bash".
355348
356 - `"bash"`
357
358349 - `enabled: optional boolean or null`
359350
360351 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 354
363354
364355 Permission policy for tool execution.
365356
366 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
357 - `BetaManagedAgentsAlwaysAllowPolicy object`
367358
368359 Tool calls are automatically approved without user confirmation.
369360
370361 - `type: "always_allow"`
371362
372 - `"always_allow"`
373
374 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
363 - `BetaManagedAgentsAlwaysAskPolicy object`
375364
376365 Tool calls require user confirmation before execution.
377366
378367 - `type: "always_ask"`
379368
380 - `"always_ask"`
381
382369 - `type: optional "bash"`
383370
384 - `"bash"`
385
386 - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }`
371 - `BetaManagedAgentsEditToolConfigParams object`
387372
388373 Configuration override for the edit tool.
389374
from line 376
391376
392377 Must be "edit".
393378
394 - `"edit"`
395
396379 - `enabled: optional boolean or null`
397380
398381 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 384
401384
402385 Permission policy for tool execution.
403386
404 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
387 - `BetaManagedAgentsAlwaysAllowPolicy object`
405388
406389 Tool calls are automatically approved without user confirmation.
407390
408 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
391 - `BetaManagedAgentsAlwaysAskPolicy object`
409392
410393 Tool calls require user confirmation before execution.
411394
412395 - `type: optional "edit"`
413396
414 - `"edit"`
415
416 - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }`
397 - `BetaManagedAgentsReadToolConfigParams object`
417398
418399 Configuration override for the read tool.
419400
from line 402
421402
422403 Must be "read".
423404
424 - `"read"`
425
426405 - `enabled: optional boolean or null`
427406
428407 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 410
431410
432411 Permission policy for tool execution.
433412
434 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
413 - `BetaManagedAgentsAlwaysAllowPolicy object`
435414
436415 Tool calls are automatically approved without user confirmation.
437416
438 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
417 - `BetaManagedAgentsAlwaysAskPolicy object`
439418
440419 Tool calls require user confirmation before execution.
441420
442421 - `type: optional "read"`
443422
444 - `"read"`
445
446 - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }`
423 - `BetaManagedAgentsWriteToolConfigParams object`
447424
448425 Configuration override for the write tool.
449426
from line 428
451428
452429 Must be "write".
453430
454 - `"write"`
455
456431 - `enabled: optional boolean or null`
457432
458433 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 436
461436
462437 Permission policy for tool execution.
463438
464 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
439 - `BetaManagedAgentsAlwaysAllowPolicy object`
465440
466441 Tool calls are automatically approved without user confirmation.
467442
468 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
443 - `BetaManagedAgentsAlwaysAskPolicy object`
469444
470445 Tool calls require user confirmation before execution.
471446
472447 - `type: optional "write"`
473448
474 - `"write"`
475
476 - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }`
449 - `BetaManagedAgentsGlobToolConfigParams object`
477450
478451 Configuration override for the glob tool.
479452
from line 454
481454
482455 Must be "glob".
483456
484 - `"glob"`
485
486457 - `enabled: optional boolean or null`
487458
488459 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 462
491462
492463 Permission policy for tool execution.
493464
494 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
465 - `BetaManagedAgentsAlwaysAllowPolicy object`
495466
496467 Tool calls are automatically approved without user confirmation.
497468
498 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
469 - `BetaManagedAgentsAlwaysAskPolicy object`
499470
500471 Tool calls require user confirmation before execution.
501472
502473 - `type: optional "glob"`
503474
504 - `"glob"`
505
506 - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }`
475 - `BetaManagedAgentsGrepToolConfigParams object`
507476
508477 Configuration override for the grep tool.
509478
from line 480
511480
512481 Must be "grep".
513482
514 - `"grep"`
515
516483 - `enabled: optional boolean or null`
517484
518485 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 488
521488
522489 Permission policy for tool execution.
523490
524 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
491 - `BetaManagedAgentsAlwaysAllowPolicy object`
525492
526493 Tool calls are automatically approved without user confirmation.
527494
528 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
495 - `BetaManagedAgentsAlwaysAskPolicy object`
529496
530497 Tool calls require user confirmation before execution.
531498
532499 - `type: optional "grep"`
533500
534 - `"grep"`
535
536 - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
501 - `BetaManagedAgentsWebFetchToolConfigParams object`
537502
538503 Configuration override for the web_fetch tool.
539504
from line 506
541506
542507 Must be "web_fetch".
543508
544 - `"web_fetch"`
545
546509 - `allowed_domains: optional array of string`
547510
548511 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 522
559522
560523 Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
561524
525 format: int32
526
562527 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
563528
564529 Permission policy for tool execution.
565530
566 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
531 - `BetaManagedAgentsAlwaysAllowPolicy object`
567532
568533 Tool calls are automatically approved without user confirmation.
569534
570 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
535 - `BetaManagedAgentsAlwaysAskPolicy object`
571536
572537 Tool calls require user confirmation before execution.
573538
574539 - `type: optional "web_fetch"`
575540
576 - `"web_fetch"`
577
578 - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }`
541 - `BetaManagedAgentsWebSearchToolConfigParams object`
579542
580543 Configuration override for the web_search tool.
581544
from line 546
583546
584547 Must be "web_search".
585548
586 - `"web_search"`
587
588549 - `allowed_domains: optional array of string`
589550
590551 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 562
601562
602563 Permission policy for tool execution.
603564
604 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
565 - `BetaManagedAgentsAlwaysAllowPolicy object`
605566
606567 Tool calls are automatically approved without user confirmation.
607568
608 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
569 - `BetaManagedAgentsAlwaysAskPolicy object`
609570
610571 Tool calls require user confirmation before execution.
611572
612573 - `type: optional "web_search"`
613574
614 - `"web_search"`
615
616575 - `user_location: optional BetaManagedAgentsUserLocation or null`
617576
618577 Approximate user location for search result localization.
from line 580
621580
622581 Location precision. Only "approximate" is supported.
623582
624 - `"approximate"`
625
626583 - `city: optional string or null`
627584
628585 City name.
629586
587 minLength: 1, maxLength: 255
588
630589 - `country: optional string or null`
631590
632591 Two-letter ISO 3166-1 country code, uppercase.
from line 594
635594
636595 Region or state name.
637596
597 minLength: 1, maxLength: 255
598
638599 - `timezone: optional string or null`
639600
640601 IANA timezone identifier, e.g. "America/Los_Angeles".
641602
603 minLength: 1, maxLength: 255
604
642605 - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null`
643606
644607 Default configuration for all tools in a toolset.
from line 614
651614
652615 Permission policy for tool execution.
653616
654 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
617 - `BetaManagedAgentsAlwaysAllowPolicy object`
655618
656619 Tool calls are automatically approved without user confirmation.
657620
658 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
621 - `BetaManagedAgentsAlwaysAskPolicy object`
659622
660623 Tool calls require user confirmation before execution.
661624
662 - `BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }`
625 - `BetaManagedAgentsMCPToolsetParams object`
663626
664627 Configuration for tools from an MCP server defined in `mcp_servers`.
665628
from line 630
667630
668631 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
669632
633 minLength: 1, maxLength: 255
634
670635 - `type: "mcp_toolset"`
671636
672 - `"mcp_toolset"`
673
674637 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
675638
676639 Per-tool configuration overrides.
from line 642
679642
680643 Name of the MCP tool to configure. 1-128 characters.
681644
645 minLength: 1, maxLength: 128
646
682647 - `enabled: optional boolean or null`
683648
684649 Whether this tool is enabled. Overrides the `default_config` setting.
from line 652
687652
688653 Permission policy for tool execution.
689654
690 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
655 - `BetaManagedAgentsAlwaysAllowPolicy object`
691656
692657 Tool calls are automatically approved without user confirmation.
693658
694 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
659 - `BetaManagedAgentsAlwaysAskPolicy object`
695660
696661 Tool calls require user confirmation before execution.
697662
from line 672
707672
708673 Permission policy for tool execution.
709674
710 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
675 - `BetaManagedAgentsAlwaysAllowPolicy object`
711676
712677 Tool calls are automatically approved without user confirmation.
713678
714 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
679 - `BetaManagedAgentsAlwaysAskPolicy object`
715680
716681 Tool calls require user confirmation before execution.
717682
718 - `BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }`
683 - `BetaManagedAgentsCustomToolParams object`
719684
720685 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.
721686
from line 688
723688
724689 Description of what the tool does, shown to the agent to help it decide when to use the tool.
725690
691 minLength: 1
692
726693 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
727694
728695 JSON Schema for custom tool input parameters.
729696
730697 - `type: "object"`
731698
732 - `"object"`
733
734699 - `properties: optional map[unknown] or null`
735700
736701 - `required: optional array of string or null`
from line 704
739704
740705 Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
741706
707 minLength: 1, maxLength: 128
708
742709 - `type: "custom"`
743710
744 - `"custom"`
745
746711 - `version: optional number`
747712
748713 The specific `agent` version to use. Omit to use the latest version.
749714
715 format: int32
716
750717- `environment_id: string`
751718
752719 ID of the `environment` defining the container configuration for this session.
753720
721 minLength: 1, maxLength: 128
722
754723- `budget: optional BetaManagedAgentsBudgetLimit`
755724
756725 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 736
767736
768737 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.
769738
770 - `"USD"`
771
772739 - `type: "limit"`
773740
774 - `"limit"`
775
776741- `initial_events: optional array of BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParams`
777742
778743 Initial events to send to the `session` at creation, processed in order. Supports `user.message` and `user.define_outcome` events. Maximum 50 events.
779744
780 - `BetaManagedAgentsUserMessageEventParams object { content, type }`
745 - `BetaManagedAgentsUserMessageEventParams object`
781746
782747 Parameters for sending a user message to the session.
783748
from line 750
785750
786751 Array of content blocks for the user message.
787752
788 - `BetaManagedAgentsTextBlock object { text, type }`
753 - `BetaManagedAgentsTextBlock object`
789754
790755 Regular text content.
791756
from line 758
793758
794759 The text content.
795760
761 minLength: 1
762
796763 - `type: "text"`
797764
798 - `"text"`
799
800 - `BetaManagedAgentsImageBlock object { source, type }`
765 - `BetaManagedAgentsImageBlock object`
801766
802767 Image content specified directly as base64 data or as a reference via a URL.
803768
from line 770
805770
806771 Union type for image source variants.
807772
808 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
773 - `BetaManagedAgentsBase64ImageSource object`
809774
810775 Base64-encoded image data.
811776
from line 778
813778
814779 Base64-encoded image data.
815780
781 minLength: 1
782
816783 - `media_type: string`
817784
818785 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
819786
787 minLength: 1
788
820789 - `type: "base64"`
821790
822 - `"base64"`
823
824 - `BetaManagedAgentsURLImageSource object { type, url }`
791 - `BetaManagedAgentsURLImageSource object`
825792
826793 Image referenced by URL.
827794
828795 - `type: "url"`
829796
830 - `"url"`
831
832797 - `url: string`
833798
834799 URL of the image to fetch.
835800
836 - `BetaManagedAgentsFileImageSource object { file_id, type }`
801 minLength: 1
802
803 - `BetaManagedAgentsFileImageSource object`
837804
838805 Image referenced by file ID.
839806
from line 808
841808
842809 ID of a previously uploaded file.
843810
811 minLength: 1
812
844813 - `type: "file"`
845814
846 - `"file"`
847
848815 - `type: "image"`
849816
850 - `"image"`
851
852 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
817 - `BetaManagedAgentsDocumentBlock object`
853818
854819 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
855820
from line 822
857822
858823 Union type for document source variants.
859824
860 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
825 - `BetaManagedAgentsBase64DocumentSource object`
861826
862827 Base64-encoded document data.
863828
from line 830
865830
866831 Base64-encoded document data.
867832
833 minLength: 1
834
868835 - `media_type: string`
869836
870837 MIME type of the document (e.g., "application/pdf").
871838
839 minLength: 1
840
872841 - `type: "base64"`
873842
874 - `"base64"`
875
876 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
843 - `BetaManagedAgentsPlainTextDocumentSource object`
877844
878845 Plain text document content.
879846
from line 848
881848
882849 The plain text content.
883850
851 minLength: 1
852
884853 - `media_type: "text/plain"`
885854
886855 MIME type of the text content. Must be "text/plain".
887856
888 - `"text/plain"`
889
890857 - `type: "text"`
891858
892 - `"text"`
893
894 - `BetaManagedAgentsURLDocumentSource object { type, url }`
859 - `BetaManagedAgentsURLDocumentSource object`
895860
896861 Document referenced by URL.
897862
898863 - `type: "url"`
899864
900 - `"url"`
901
902865 - `url: string`
903866
904867 URL of the document to fetch.
905868
906 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
869 minLength: 1
870
871 - `BetaManagedAgentsFileDocumentSource object`
907872
908873 Document referenced by file ID.
909874
from line 876
911876
912877 ID of a previously uploaded file.
913878
879 minLength: 1
880
914881 - `type: "file"`
915882
916 - `"file"`
917
918883 - `type: "document"`
919884
920 - `"document"`
921
922885 - `context: optional string or null`
923886
924887 Additional context about the document for the model.
from line 890
927890
928891 The title of the document.
929892
930 - `BetaManagedAgentsRedactedBlock object { type }`
893 - `BetaManagedAgentsRedactedBlock object`
931894
932895 Placeholder for content withheld by Anthropic model policy.
933896
934897 - `type: "redacted"`
935898
936 - `"redacted"`
937
938899 - `type: "user.message"`
939900
940 - `"user.message"`
941
942 - `BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }`
901 - `BetaManagedAgentsUserDefineOutcomeEventParams object`
943902
944903 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
945904
from line 910
951910
952911 Rubric for grading the quality of an outcome.
953912
954 - `BetaManagedAgentsFileRubricParams object { file_id, type }`
913 - `BetaManagedAgentsFileRubricParams object`
955914
956915 Rubric referenced by a file uploaded via the Files API.
957916
from line 920
961920
962921 - `type: "file"`
963922
964 - `"file"`
965
966 - `BetaManagedAgentsTextRubricParams object { content, type }`
923 - `BetaManagedAgentsTextRubricParams object`
967924
968925 Rubric content provided inline as text.
969926
from line 928
971928
972929 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
973930
931 maxLength: 262144
932
974933 - `type: "text"`
975934
976 - `"text"`
977
978935 - `type: "user.define_outcome"`
979936
980 - `"user.define_outcome"`
981
982937 - `max_iterations: optional number or null`
983938
984939 Eval→revision cycles before giving up. Default 3, max 20.
985940
941 format: int32
942
986943- `metadata: optional map[string]`
987944
988945 Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
from line 948
991948
992949 Resources (e.g. repositories, files) to mount into the session's container.
993950
994 - `BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }`
951 - `BetaManagedAgentsGitHubRepositoryResourceParams object`
995952
996953 Mount a GitHub repository into the session's container.
997954
from line 956
999956
1000957 GitHub authorization token used to clone the repository.
1001958
959 minLength: 1, maxLength: 4096
960
1002961 - `type: "github_repository"`
1003962
1004 - `"github_repository"`
1005
1006963 - `url: string`
1007964
1008965 Github URL of the repository
1009966
967 minLength: 1, maxLength: 2048
968
1010969 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
1011970
1012971 Branch or commit to check out. Defaults to the repository's default branch.
1013972
1014 - `BetaManagedAgentsBranchCheckout object { name, type }`
973 - `BetaManagedAgentsBranchCheckout object`
1015974
1016975 - `name: string`
1017976
1018977 Branch name to check out.
1019978
979 minLength: 1, maxLength: 255
980
1020981 - `type: "branch"`
1021982
1022 - `"branch"`
1023
1024 - `BetaManagedAgentsCommitCheckout object { sha, type }`
983 - `BetaManagedAgentsCommitCheckout object`
1025984
1026985 - `sha: string`
1027986
1028987 Full commit SHA to check out.
1029988
989 minLength: 7, maxLength: 64
990
1030991 - `type: "commit"`
1031992
1032 - `"commit"`
1033
1034993 - `mount_path: optional string or null`
1035994
1036995 Mount path in the container. Defaults to `/workspace/<repo-name>`.
1037996
1038 - `BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }`
997 minLength: 1, maxLength: 4096
998
999 - `BetaManagedAgentsFileResourceParams object`
10391000
10401001 Mount a file uploaded via the Files API into the session.
10411002
from line 1004
10431004
10441005 ID of a previously uploaded file.
10451006
1007 minLength: 1, maxLength: 128
1008
10461009 - `type: "file"`
10471010
1048 - `"file"`
1049
10501011 - `mount_path: optional string or null`
10511012
10521013 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
10531014
1054 - `BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }`
1015 minLength: 1, maxLength: 4096
1016
1017 - `BetaManagedAgentsMemoryStoreResourceParam object`
10551018
10561019 Parameters for attaching a memory store to an agent session.
10571020
from line 1024
10611024
10621025 - `type: "memory_store"`
10631026
1064 - `"memory_store"`
1065
10661027 - `access: optional "read_write" or "read_only" or null`
10671028
10681029 Access mode for an attached memory store.
from line 1036
10751036
10761037 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
10771038
1039 maxLength: 4096
1040
10781041- `title: optional string or null`
10791042
10801043 Human-readable session title.
10811044
1045 maxLength: 500
1046
10821047- `vault_ids: optional array of string`
10831048
10841049 Vault IDs for stored credentials the agent can use during the session.
10851050
1086### Returns
1087
1088- `BetaManagedAgentsSession object { id, agent, archived_at, 14 more }`
1051## Returns
1052
1053- `BetaManagedAgentsSession object`
10891054
10901055 A Managed Agents `session`.
10911056
from line 1070
11051070
11061071 - `type: "url"`
11071072
1108 - `"url"`
1109
11101073 - `url: string`
11111074
11121075 - `model: BetaManagedAgentsModelConfig`
from line 1146
11831146
11841147 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
11851148
1186 - `BetaManagedAgentsEffortLow object { type }`
1149 - `BetaManagedAgentsEffortLow object`
11871150
11881151 Low effort. Favors latency over reasoning depth.
11891152
11901153 - `type: "low"`
11911154
1192 - `"low"`
1193
1194 - `BetaManagedAgentsEffortMedium object { type }`
1155 - `BetaManagedAgentsEffortMedium object`
11951156
11961157 Medium effort. Balances latency and reasoning depth.
11971158
11981159 - `type: "medium"`
11991160
1200 - `"medium"`
1201
1202 - `BetaManagedAgentsEffortHigh object { type }`
1161 - `BetaManagedAgentsEffortHigh object`
12031162
12041163 High effort. Favors reasoning depth.
12051164
12061165 - `type: "high"`
12071166
1208 - `"high"`
1209
1210 - `BetaManagedAgentsEffortXhigh object { type }`
1167 - `BetaManagedAgentsEffortXhigh object`
12111168
12121169 Extra-high effort. Not all models accept this level.
12131170
12141171 - `type: "xhigh"`
12151172
1216 - `"xhigh"`
1217
1218 - `BetaManagedAgentsEffortMax object { type }`
1173 - `BetaManagedAgentsEffortMax object`
12191174
12201175 Maximum effort. Favors reasoning depth over latency.
12211176
12221177 - `type: "max"`
12231178
1224 - `"max"`
1225
12261179 - `inference_geo: optional string`
12271180
12281181 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1196
12431196
12441197 Full `agent` definitions the coordinator may spawn as session threads.
12451198
1246 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1199 - `BetaManagedAgentsSessionThreadAgent object`
12471200
12481201 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`.
12491202
from line 1220
12671220
12681221 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
12691222
1270 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1223 - `BetaManagedAgentsAnthropicSkill object`
12711224
12721225 A resolved Anthropic-managed skill.
12731226
from line 1228
12751228
12761229 - `type: "anthropic"`
12771230
1278 - `"anthropic"`
1279
12801231 - `version: string`
12811232
1282 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1233 - `BetaManagedAgentsCustomSkill object`
12831234
12841235 A resolved user-created custom skill.
12851236
from line 1238
12871238
12881239 - `type: "custom"`
12891240
1290 - `"custom"`
1291
12921241 - `version: string`
12931242
12941243 - `system: string or null`
12951244
12961245 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
12971246
1298 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1247 - `BetaManagedAgentsAgentToolset20260401 object`
12991248
13001249 - `configs: array of BetaManagedAgentsAgentToolConfig`
13011250
1302 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1251 - `BetaManagedAgentsBashToolConfig object`
13031252
13041253 Configuration for the bash tool.
13051254
from line 1256
13071256
13081257 - `name: "bash"`
13091258
1310 - `"bash"`
1311
13121259 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
13131260
13141261 Permission policy for tool execution.
13151262
1316 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1263 - `BetaManagedAgentsAlwaysAllowPolicy object`
13171264
13181265 Tool calls are automatically approved without user confirmation.
13191266
13201267 - `type: "always_allow"`
13211268
1322 - `"always_allow"`
1323
1324 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1269 - `BetaManagedAgentsAlwaysAskPolicy object`
13251270
13261271 Tool calls require user confirmation before execution.
13271272
13281273 - `type: "always_ask"`
13291274
1330 - `"always_ask"`
1331
13321275 - `type: "bash"`
13331276
1334 - `"bash"`
1335
1336 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1277 - `BetaManagedAgentsEditToolConfig object`
13371278
13381279 Configuration for the edit tool.
13391280
from line 1282
13411282
13421283 - `name: "edit"`
13431284
1344 - `"edit"`
1345
13461285 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
13471286
13481287 Permission policy for tool execution.
13491288
1350 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1289 - `BetaManagedAgentsAlwaysAllowPolicy object`
13511290
13521291 Tool calls are automatically approved without user confirmation.
13531292
1354 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1293 - `BetaManagedAgentsAlwaysAskPolicy object`
13551294
13561295 Tool calls require user confirmation before execution.
13571296
13581297 - `type: "edit"`
13591298
1360 - `"edit"`
1361
1362 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1299 - `BetaManagedAgentsReadToolConfig object`
13631300
13641301 Configuration for the read tool.
13651302
from line 1304
13671304
13681305 - `name: "read"`
13691306
1370 - `"read"`
1371
13721307 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
13731308
13741309 Permission policy for tool execution.
13751310
1376 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1311 - `BetaManagedAgentsAlwaysAllowPolicy object`
13771312
13781313 Tool calls are automatically approved without user confirmation.
13791314
1380 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1315 - `BetaManagedAgentsAlwaysAskPolicy object`
13811316
13821317 Tool calls require user confirmation before execution.
13831318
13841319 - `type: "read"`
13851320
1386 - `"read"`
1387
1388 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1321 - `BetaManagedAgentsWriteToolConfig object`
13891322
13901323 Configuration for the write tool.
13911324
from line 1326
13931326
13941327 - `name: "write"`
13951328
1396 - `"write"`
1397
13981329 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
13991330
14001331 Permission policy for tool execution.
14011332
1402 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1333 - `BetaManagedAgentsAlwaysAllowPolicy object`
14031334
14041335 Tool calls are automatically approved without user confirmation.
14051336
1406 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1337 - `BetaManagedAgentsAlwaysAskPolicy object`
14071338
14081339 Tool calls require user confirmation before execution.
14091340
14101341 - `type: "write"`
14111342
1412 - `"write"`
1413
1414 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1343 - `BetaManagedAgentsGlobToolConfig object`
14151344
14161345 Configuration for the glob tool.
14171346
from line 1348
14191348
14201349 - `name: "glob"`
14211350
1422 - `"glob"`
1423
14241351 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
14251352
14261353 Permission policy for tool execution.
14271354
1428 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1355 - `BetaManagedAgentsAlwaysAllowPolicy object`
14291356
14301357 Tool calls are automatically approved without user confirmation.
14311358
1432 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1359 - `BetaManagedAgentsAlwaysAskPolicy object`
14331360
14341361 Tool calls require user confirmation before execution.
14351362
14361363 - `type: "glob"`
14371364
1438 - `"glob"`
1439
1440 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1365 - `BetaManagedAgentsGrepToolConfig object`
14411366
14421367 Configuration for the grep tool.
14431368
from line 1370
14451370
14461371 - `name: "grep"`
14471372
1448 - `"grep"`
1449
14501373 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
14511374
14521375 Permission policy for tool execution.
14531376
1454 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1377 - `BetaManagedAgentsAlwaysAllowPolicy object`
14551378
14561379 Tool calls are automatically approved without user confirmation.
14571380
1458 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1381 - `BetaManagedAgentsAlwaysAskPolicy object`
14591382
14601383 Tool calls require user confirmation before execution.
14611384
14621385 - `type: "grep"`
14631386
1464 - `"grep"`
1465
1466 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1387 - `BetaManagedAgentsWebFetchToolConfig object`
14671388
14681389 Configuration for the web_fetch tool.
14691390
from line 1392
14711392
14721393 - `name: "web_fetch"`
14731394
1474 - `"web_fetch"`
1475
14761395 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
14771396
14781397 Permission policy for tool execution.
14791398
1480 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1399 - `BetaManagedAgentsAlwaysAllowPolicy object`
14811400
14821401 Tool calls are automatically approved without user confirmation.
14831402
1484 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1403 - `BetaManagedAgentsAlwaysAskPolicy object`
14851404
14861405 Tool calls require user confirmation before execution.
14871406
14881407 - `type: "web_fetch"`
14891408
1490 - `"web_fetch"`
1491
14921409 - `allowed_domains: optional array of string`
14931410
14941411 - `blocked_domains: optional array of string`
14951412
14961413 - `max_content_tokens: optional number or null`
14971414
1498 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1415 format: int32
1416
1417 - `BetaManagedAgentsWebSearchToolConfig object`
14991418
15001419 Configuration for the web_search tool.
15011420
from line 1422
15031422
15041423 - `name: "web_search"`
15051424
1506 - `"web_search"`
1507
15081425 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
15091426
15101427 Permission policy for tool execution.
15111428
1512 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1429 - `BetaManagedAgentsAlwaysAllowPolicy object`
15131430
15141431 Tool calls are automatically approved without user confirmation.
15151432
1516 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1433 - `BetaManagedAgentsAlwaysAskPolicy object`
15171434
15181435 Tool calls require user confirmation before execution.
15191436
15201437 - `type: "web_search"`
15211438
1522 - `"web_search"`
1523
15241439 - `allowed_domains: optional array of string`
15251440
15261441 - `blocked_domains: optional array of string`
from line 1448
15331448
15341449 Location precision. Only "approximate" is supported.
15351450
1536 - `"approximate"`
1537
15381451 - `city: optional string or null`
15391452
15401453 City name.
15411454
1455 minLength: 1, maxLength: 255
1456
15421457 - `country: optional string or null`
15431458
15441459 Two-letter ISO 3166-1 country code, uppercase.
from line 1462
15471462
15481463 Region or state name.
15491464
1465 minLength: 1, maxLength: 255
1466
15501467 - `timezone: optional string or null`
15511468
15521469 IANA timezone identifier, e.g. "America/Los_Angeles".
15531470
1471 minLength: 1, maxLength: 255
1472
15541473 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
15551474
15561475 Resolved default configuration for agent tools.
from line 1480
15611480
15621481 Permission policy for tool execution.
15631482
1564 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1483 - `BetaManagedAgentsAlwaysAllowPolicy object`
15651484
15661485 Tool calls are automatically approved without user confirmation.
15671486
1568 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1487 - `BetaManagedAgentsAlwaysAskPolicy object`
15691488
15701489 Tool calls require user confirmation before execution.
15711490
15721491 - `type: "agent_toolset_20260401"`
15731492
1574 - `"agent_toolset_20260401"`
1575
1576 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1493 - `BetaManagedAgentsMCPToolset object`
15771494
15781495 - `configs: array of BetaManagedAgentsMCPToolConfig`
15791496
from line 1502
15851502
15861503 Permission policy for tool execution.
15871504
1588 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1505 - `BetaManagedAgentsAlwaysAllowPolicy object`
15891506
15901507 Tool calls are automatically approved without user confirmation.
15911508
1592 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1509 - `BetaManagedAgentsAlwaysAskPolicy object`
15931510
15941511 Tool calls require user confirmation before execution.
15951512
from line 1520
16031520
16041521 Permission policy for tool execution.
16051522
1606 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1523 - `BetaManagedAgentsAlwaysAllowPolicy object`
16071524
16081525 Tool calls are automatically approved without user confirmation.
16091526
1610 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1527 - `BetaManagedAgentsAlwaysAskPolicy object`
16111528
16121529 Tool calls require user confirmation before execution.
16131530
from line 1532
16151532
16161533 - `type: "mcp_toolset"`
16171534
1618 - `"mcp_toolset"`
1619
1620 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1535 - `BetaManagedAgentsCustomTool object`
16211536
16221537 A custom tool as returned in API responses.
16231538
from line 1544
16291544
16301545 - `type: "object"`
16311546
1632 - `"object"`
1633
16341547 - `properties: optional map[unknown] or null`
16351548
16361549 - `required: optional array of string or null`
from line 1552
16391552
16401553 - `type: "custom"`
16411554
1642 - `"custom"`
1643
16441555 - `type: "agent"`
16451556
1646 - `"agent"`
1647
16481557 - `version: number`
16491558
1650 - `BetaManagedAgentsAdvisor object { model, type }`
1559 format: int32
1560
1561 - `BetaManagedAgentsAdvisor object`
16511562
16521563 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
16531564
from line 1568
16571568
16581569 - `type: "advisor"`
16591570
1660 - `"advisor"`
1661
16621571 - `type: "coordinator"`
16631572
1664 - `"coordinator"`
1665
16661573 - `name: string`
16671574
16681575 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
16691576
1670 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1577 - `BetaManagedAgentsAnthropicSkill object`
16711578
16721579 A resolved Anthropic-managed skill.
16731580
1674 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1581 - `BetaManagedAgentsCustomSkill object`
16751582
16761583 A resolved user-created custom skill.
16771584
from line 1586
16791586
16801587 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
16811588
1682 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1683
1684 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1685
1686 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
1589 - `BetaManagedAgentsAgentToolset20260401 object`
1590
1591 - `BetaManagedAgentsMCPToolset object`
1592
1593 - `BetaManagedAgentsCustomTool object`
16871594
16881595 A custom tool as returned in API responses.
16891596
16901597 - `type: "agent"`
16911598
1692 - `"agent"`
1693
16941599 - `version: number`
16951600
1601 format: int32
1602
16961603 - `archived_at: string or null`
16971604
16981605 A timestamp in RFC 3339 format
16991606
1607 format: date-time
1608
17001609 - `budget: BetaManagedAgentsBudgetLimit or null`
17011610
17021611 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 1622
17131622
17141623 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.
17151624
1716 - `"USD"`
1717
17181625 - `type: "limit"`
17191626
1720 - `"limit"`
1721
17221627 - `created_at: string`
17231628
17241629 A timestamp in RFC 3339 format
17251630
1631 format: date-time
1632
17261633 - `environment_id: string`
17271634
17281635 - `metadata: map[string]`
from line 1642
17351642
17361643 A timestamp in RFC 3339 format
17371644
1645 format: date-time
1646
17381647 - `description: string`
17391648
17401649 What the agent should produce.
from line 1656
17471656
17481657 0-indexed revision cycle the outcome is currently on.
17491658
1659 format: int32
1660
17501661 - `outcome_id: string`
17511662
17521663 Server-generated outc_ ID for this outcome.
from line 1668
17571668
17581669 - `type: "outcome_evaluation"`
17591670
1760 - `"outcome_evaluation"`
1761
17621671 - `resources: array of BetaManagedAgentsSessionResource`
17631672
1764 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
1673 - `BetaManagedAgentsGitHubRepositoryResource object`
17651674
17661675 - `id: string`
17671676
from line 1678
17691678
17701679 A timestamp in RFC 3339 format
17711680
1681 format: date-time
1682
17721683 - `mount_path: string`
17731684
17741685 - `type: "github_repository"`
17751686
1776 - `"github_repository"`
1777
17781687 - `updated_at: string`
17791688
17801689 A timestamp in RFC 3339 format
17811690
1691 format: date-time
1692
17821693 - `url: string`
17831694
17841695 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
17851696
1786 - `BetaManagedAgentsBranchCheckout object { name, type }`
1697 - `BetaManagedAgentsBranchCheckout object`
17871698
17881699 - `name: string`
17891700
17901701 Branch name to check out.
17911702
1703 minLength: 1, maxLength: 255
1704
17921705 - `type: "branch"`
17931706
1794 - `"branch"`
1795
1796 - `BetaManagedAgentsCommitCheckout object { sha, type }`
1707 - `BetaManagedAgentsCommitCheckout object`
17971708
17981709 - `sha: string`
17991710
18001711 Full commit SHA to check out.
18011712
1713 minLength: 7, maxLength: 64
1714
18021715 - `type: "commit"`
18031716
1804 - `"commit"`
1805
1806 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
1717 - `BetaManagedAgentsFileResource object`
18071718
18081719 - `id: string`
18091720
from line 1722
18111722
18121723 A timestamp in RFC 3339 format
18131724
1725 format: date-time
1726
18141727 - `file_id: string`
18151728
18161729 - `mount_path: string`
18171730
18181731 - `type: "file"`
18191732
1820 - `"file"`
1821
18221733 - `updated_at: string`
18231734
18241735 A timestamp in RFC 3339 format
18251736
1826 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
1737 format: date-time
1738
1739 - `BetaManagedAgentsMemoryStoreResource object`
18271740
18281741 A memory store attached to an agent session.
18291742
from line 1746
18331746
18341747 - `type: "memory_store"`
18351748
1836 - `"memory_store"`
1837
18381749 - `access: optional "read_write" or "read_only" or null`
18391750
18401751 Access mode for an attached memory store.
from line 1762
18511762
18521763 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
18531764
1765 maxLength: 4096
1766
18541767 - `mount_path: optional string or null`
18551768
18561769 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 1780
18671780
18681781 Cumulative time in seconds the session spent in running status. Excludes idle time.
18691782
1783 format: double
1784
18701785 - `duration_seconds: optional number`
18711786
18721787 Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
18731788
1789 format: double
1790
18741791 - `status: "rescheduling" or "running" or "idle" or "terminated"`
18751792
18761793 SessionStatus enum
from line 1804
18871804
18881805 - `type: "session"`
18891806
1890 - `"session"`
1891
18921807 - `updated_at: string`
18931808
18941809 A timestamp in RFC 3339 format
18951810
1811 format: date-time
1812
18961813 - `usage: BetaManagedAgentsSessionUsage`
18971814
18981815 Cumulative token usage for a session across all turns.
from line 1818
19011818
19021819 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.
19031820
1821 format: double
1822
19041823 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
19051824
19061825 Prompt-cache creation token usage broken down by cache lifetime.
from line 1828
19091828
19101829 Tokens used to create 1-hour ephemeral cache entries.
19111830
1831 format: int32
1832
19121833 - `ephemeral_5m_input_tokens: optional number`
19131834
19141835 Tokens used to create 5-minute ephemeral cache entries.
19151836
1837 format: int32
1838
19161839 - `cache_read_input_tokens: optional number`
19171840
19181841 Total tokens read from prompt cache.
19191842
1843 format: int32
1844
19201845 - `input_tokens: optional number`
19211846
19221847 Total input tokens consumed across all turns.
19231848
1849 format: int32
1850
19241851 - `list_cost: optional BetaMonetaryAmount or null`
19251852
19261853 A monetary amount in a specific currency.
from line 1856
19291856
19301857 Total output tokens generated across all turns.
19311858
1859 format: int32
1860
19321861 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null`
19331862
19341863 Cumulative count of server-executed tool invocations, broken down by tool.
from line 1866
19371866
19381867 Number of server-executed web fetch requests.
19391868
1869 format: int32
1870
19401871 - `web_search_requests: optional number`
19411872
19421873 Number of server-executed web search requests.
19431874
1875 format: int32
1876
19441877 - `vault_ids: array of string`
19451878
19461879 Vault IDs attached to the session at creation. Empty when no vaults were supplied.
from line 1882
19491882
19501883 Deployment ID when the session was created from a deployment reference. Null otherwise.
19511884
1952### Example
1953
1954```http
1885## Example
1886
1887```bash
19551888curl https://api.anthropic.com/v1/sessions \
19561889 -H 'Content-Type: application/json' \
19571890 -H 'anthropic-version: 2023-06-01' \
from line 1897
19641897 }'
19651898```
19661899
1967#### Response
1900### Response (200)
19681901
19691902```json
19701903{
19711904
api/beta/sessions/delete Changed · +9 / -16 lines
# Delete Session ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Delete Session ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Delete Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/delete
4---
1# Delete Session
52
6## Delete Session
3**DELETE** `/v1/sessions/{session_id}`
74
8**delete** `/v1/sessions/{session_id}`
9
105Delete 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- `BetaManagedAgentsDeletedSession object { id, type }`
91- `BetaManagedAgentsDeletedSession object`
9792
9893 Confirmation that a `session` has been permanently deleted.
9994
from line 96
10196
10297 - `type: "session_deleted"`
10398
104 - `"session_deleted"`
99## Example
105100
106### Example
107
108```http
101```bash
109102curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
110103 -X DELETE \
111104 -H 'anthropic-version: 2023-06-01' \
from line 106
113106 -H "X-Api-Key: $ANTHROPIC_API_KEY"
114107```
115108
116#### Response
109### Response (200)
117110
118111```json
119112{
api/beta/sessions/events Changed · +2194 / -2579 lines
### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ## Domain types ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Domain Types
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/events/list Changed · +328 / -387 lines
# List Events ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List 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 Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/events/list
4---
5
6## List Events
7
8**get** `/v1/sessions/{session_id}/events`
1# List Events
2
3**GET** `/v1/sessions/{session_id}/events`
94
105List Events
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
16### Query Parameters
11## Query parameters
1712
1813- `"created_at[gt]": optional string`
1914
2015 Return events created after this time (exclusive). Compared against the event's `processed_at` value.
2116
17 format: date-time
18
2219- `"created_at[gte]": optional string`
2320
2421 Return events created at or after this time (inclusive). Compared against the event's `processed_at` value.
2522
23 format: date-time
24
2625- `"created_at[lt]": optional string`
2726
2827 Return events created before this time (exclusive). Compared against the event's `processed_at` value.
2928
29 format: date-time
30
3031- `"created_at[lte]": optional string`
3132
3233 Return events created at or before this time (inclusive). Compared against the event's `processed_at` value.
3334
35 format: date-time
36
3437- `limit: optional number`
3538
3639 Query parameter for limit
3740
41 format: int32
42
3843- `order: optional "asc" or "desc"`
3944
4045 Sort direction for results, ordered by the event's `processed_at`. Defaults to asc (chronological).
from line 56
5156
5257 Filter by event type. Values match the `type` field on returned events (for example, `user.message` or `agent.tool_use`). Omit to return all event types.
5358
54### Header Parameters
59## Headers
5560
5661- `"anthropic-beta": optional array of AnthropicBeta`
5762
from line 134
129134
130135 - `"mid-conversation-tool-changes-2026-07-01"`
131136
132### Returns
137## Returns
133138
134139- `data: optional array of BetaManagedAgentsSessionEvent`
135140
136141 Events for the session, ordered by `processed_at`.
137142
138 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
143 - `BetaManagedAgentsUserMessageEvent object`
139144
140145 A user message event in the session conversation.
141146
from line 152
147152
148153 Array of content blocks comprising the user message.
149154
150 - `BetaManagedAgentsTextBlock object { text, type }`
155 - `BetaManagedAgentsTextBlock object`
151156
152157 Regular text content.
153158
from line 160
155160
156161 The text content.
157162
163 minLength: 1
164
158165 - `type: "text"`
159166
160 - `"text"`
161
162 - `BetaManagedAgentsImageBlock object { source, type }`
167 - `BetaManagedAgentsImageBlock object`
163168
164169 Image content specified directly as base64 data or as a reference via a URL.
165170
from line 172
167172
168173 Union type for image source variants.
169174
170 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
175 - `BetaManagedAgentsBase64ImageSource object`
171176
172177 Base64-encoded image data.
173178
from line 180
175180
176181 Base64-encoded image data.
177182
183 minLength: 1
184
178185 - `media_type: string`
179186
180187 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
181188
189 minLength: 1
190
182191 - `type: "base64"`
183192
184 - `"base64"`
185
186 - `BetaManagedAgentsURLImageSource object { type, url }`
193 - `BetaManagedAgentsURLImageSource object`
187194
188195 Image referenced by URL.
189196
190197 - `type: "url"`
191198
192 - `"url"`
193
194199 - `url: string`
195200
196201 URL of the image to fetch.
197202
198 - `BetaManagedAgentsFileImageSource object { file_id, type }`
203 minLength: 1
204
205 - `BetaManagedAgentsFileImageSource object`
199206
200207 Image referenced by file ID.
201208
from line 210
203210
204211 ID of a previously uploaded file.
205212
213 minLength: 1
214
206215 - `type: "file"`
207216
208 - `"file"`
209
210217 - `type: "image"`
211218
212 - `"image"`
213
214 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
219 - `BetaManagedAgentsDocumentBlock object`
215220
216221 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
217222
from line 224
219224
220225 Union type for document source variants.
221226
222 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
227 - `BetaManagedAgentsBase64DocumentSource object`
223228
224229 Base64-encoded document data.
225230
from line 232
227232
228233 Base64-encoded document data.
229234
235 minLength: 1
236
230237 - `media_type: string`
231238
232239 MIME type of the document (e.g., "application/pdf").
233240
241 minLength: 1
242
234243 - `type: "base64"`
235244
236 - `"base64"`
237
238 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
245 - `BetaManagedAgentsPlainTextDocumentSource object`
239246
240247 Plain text document content.
241248
from line 250
243250
244251 The plain text content.
245252
253 minLength: 1
254
246255 - `media_type: "text/plain"`
247256
248257 MIME type of the text content. Must be "text/plain".
249258
250 - `"text/plain"`
251
252259 - `type: "text"`
253260
254 - `"text"`
255
256 - `BetaManagedAgentsURLDocumentSource object { type, url }`
261 - `BetaManagedAgentsURLDocumentSource object`
257262
258263 Document referenced by URL.
259264
260265 - `type: "url"`
261266
262 - `"url"`
263
264267 - `url: string`
265268
266269 URL of the document to fetch.
267270
268 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
271 minLength: 1
272
273 - `BetaManagedAgentsFileDocumentSource object`
269274
270275 Document referenced by file ID.
271276
from line 278
273278
274279 ID of a previously uploaded file.
275280
281 minLength: 1
282
276283 - `type: "file"`
277284
278 - `"file"`
279
280285 - `type: "document"`
281286
282 - `"document"`
283
284287 - `context: optional string or null`
285288
286289 Additional context about the document for the model.
from line 292
289292
290293 The title of the document.
291294
292 - `BetaManagedAgentsRedactedBlock object { type }`
295 - `BetaManagedAgentsRedactedBlock object`
293296
294297 Placeholder for content withheld by Anthropic model policy.
295298
296299 - `type: "redacted"`
297300
298 - `"redacted"`
299
300301 - `type: "user.message"`
301302
302 - `"user.message"`
303
304303 - `processed_at: optional string or null`
305304
306305 A timestamp in RFC 3339 format
307306
308 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
307 format: date-time
308
309 - `BetaManagedAgentsUserInterruptEvent object`
309310
310311 An interrupt event that pauses agent execution and returns control to the user.
311312
from line 316
315316
316317 - `type: "user.interrupt"`
317318
318 - `"user.interrupt"`
319
320319 - `processed_at: optional string or null`
321320
322321 A timestamp in RFC 3339 format
323322
323 format: date-time
324
324325 - `session_thread_id: optional string or null`
325326
326327 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.
327328
328 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
329 - `BetaManagedAgentsUserToolConfirmationEvent object`
329330
330331 A tool confirmation event that approves or denies a pending tool execution.
331332
from line 348
347348
348349 - `type: "user.tool_confirmation"`
349350
350 - `"user.tool_confirmation"`
351
352351 - `deny_message: optional string or null`
353352
354353 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
355354
355 maxLength: 10000
356
356357 - `processed_at: optional string or null`
357358
358359 A timestamp in RFC 3339 format
359360
361 format: date-time
362
360363 - `session_thread_id: optional string or null`
361364
362365 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.
363366
364 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
367 - `BetaManagedAgentsUserCustomToolResultEvent object`
365368
366369 Event sent by the client providing the result of a custom tool execution.
367370
from line 378
375378
376379 - `type: "user.custom_tool_result"`
377380
378 - `"user.custom_tool_result"`
379
380381 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
381382
382383 The result content returned by the tool.
383384
384 - `BetaManagedAgentsTextBlock object { text, type }`
385 - `BetaManagedAgentsTextBlock object`
385386
386387 Regular text content.
387388
388 - `BetaManagedAgentsImageBlock object { source, type }`
389 - `BetaManagedAgentsImageBlock object`
389390
390391 Image content specified directly as base64 data or as a reference via a URL.
391392
392 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
393 - `BetaManagedAgentsDocumentBlock object`
393394
394395 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
395396
396 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
397 - `BetaManagedAgentsSearchResultBlock object`
397398
398399 A block containing a web search result.
399400
from line 414
413414
414415 The text content.
415416
417 minLength: 1
418
416419 - `type: "text"`
417420
418 - `"text"`
419
420421 - `source: string`
421422
422423 The URL source of the search result.
423424
425 minLength: 1
426
424427 - `title: string`
425428
426429 The title of the search result.
427430
431 minLength: 1
432
428433 - `type: "search_result"`
429434
430 - `"search_result"`
431
432435 - `is_error: optional boolean or null`
433436
434437 Whether the tool execution resulted in an error.
from line 440
437440
438441 A timestamp in RFC 3339 format
439442
443 format: date-time
444
440445 - `session_thread_id: optional string or null`
441446
442447 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
443448
444 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
449 - `BetaManagedAgentsAgentCustomToolUseEvent object`
445450
446451 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.
447452
from line 466
461466
462467 A timestamp in RFC 3339 format
463468
469 format: date-time
470
464471 - `type: "agent.custom_tool_use"`
465472
466 - `"agent.custom_tool_use"`
467
468473 - `session_thread_id: optional string or null`
469474
470475 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.
471476
472 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
477 - `BetaManagedAgentsAgentMessageEvent object`
473478
474479 An agent response event in the session conversation.
475480
from line 486
481486
482487 Array of text blocks comprising the agent response.
483488
484 - `BetaManagedAgentsTextBlock object { text, type }`
489 - `BetaManagedAgentsTextBlock object`
485490
486491 Regular text content.
487492
488 - `BetaManagedAgentsRedactedBlock object { type }`
493 - `BetaManagedAgentsRedactedBlock object`
489494
490495 Placeholder for content withheld by Anthropic model policy.
491496
from line 498
493498
494499 A timestamp in RFC 3339 format
495500
501 format: date-time
502
496503 - `type: "agent.message"`
497504
498 - `"agent.message"`
499
500 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
505 - `BetaManagedAgentsAgentThinkingEvent object`
501506
502507 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
503508
from line 514
509514
510515 A timestamp in RFC 3339 format
511516
517 format: date-time
518
512519 - `type: "agent.thinking"`
513520
514 - `"agent.thinking"`
515
516 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
521 - `BetaManagedAgentsAgentMCPToolUseEvent object`
517522
518523 Event emitted when the agent invokes a tool provided by an MCP server.
519524
from line 542
537542
538543 A timestamp in RFC 3339 format
539544
545 format: date-time
546
540547 - `type: "agent.mcp_tool_use"`
541548
542 - `"agent.mcp_tool_use"`
543
544549 - `evaluated_permission: optional "allow" or "ask" or "deny"`
545550
546551 AgentEvaluatedPermission enum
from line 560
555560
556561 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.
557562
558 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
563 - `BetaManagedAgentsAgentMCPToolResultEvent object`
559564
560565 Event representing the result of an MCP tool execution.
561566
from line 576
571576
572577 A timestamp in RFC 3339 format
573578
579 format: date-time
580
574581 - `type: "agent.mcp_tool_result"`
575582
576 - `"agent.mcp_tool_result"`
577
578583 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
579584
580585 The result content returned by the tool.
581586
582 - `BetaManagedAgentsTextBlock object { text, type }`
587 - `BetaManagedAgentsTextBlock object`
583588
584589 Regular text content.
585590
586 - `BetaManagedAgentsImageBlock object { source, type }`
591 - `BetaManagedAgentsImageBlock object`
587592
588593 Image content specified directly as base64 data or as a reference via a URL.
589594
590 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
595 - `BetaManagedAgentsDocumentBlock object`
591596
592597 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
593598
594 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
599 - `BetaManagedAgentsSearchResultBlock object`
595600
596601 A block containing a web search result.
597602
from line 604
599604
600605 Whether the tool execution resulted in an error.
601606
602 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
607 - `BetaManagedAgentsAgentToolUseEvent object`
603608
604609 Event emitted when the agent invokes a built-in agent tool.
605610
from line 624
619624
620625 A timestamp in RFC 3339 format
621626
627 format: date-time
628
622629 - `type: "agent.tool_use"`
623630
624 - `"agent.tool_use"`
625
626631 - `evaluated_permission: optional "allow" or "ask" or "deny"`
627632
628633 AgentEvaluatedPermission enum
from line 642
637642
638643 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.
639644
640 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
645 - `BetaManagedAgentsAgentToolResultEvent object`
641646
642647 Event representing the result of an agent tool execution.
643648
from line 654
649654
650655 A timestamp in RFC 3339 format
651656
657 format: date-time
658
652659 - `tool_use_id: string`
653660
654661 The id of the `agent.tool_use` event this result corresponds to.
655662
656663 - `type: "agent.tool_result"`
657664
658 - `"agent.tool_result"`
659
660665 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
661666
662667 The result content returned by the tool.
663668
664 - `BetaManagedAgentsTextBlock object { text, type }`
669 - `BetaManagedAgentsTextBlock object`
665670
666671 Regular text content.
667672
668 - `BetaManagedAgentsImageBlock object { source, type }`
673 - `BetaManagedAgentsImageBlock object`
669674
670675 Image content specified directly as base64 data or as a reference via a URL.
671676
672 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
677 - `BetaManagedAgentsDocumentBlock object`
673678
674679 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
675680
676 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
681 - `BetaManagedAgentsSearchResultBlock object`
677682
678683 A block containing a web search result.
679684
from line 686
681686
682687 Whether the tool execution resulted in an error.
683688
684 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
689 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
685690
686691 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
687692
from line 698
693698
694699 Message content blocks.
695700
696 - `BetaManagedAgentsTextBlock object { text, type }`
701 - `BetaManagedAgentsTextBlock object`
697702
698703 Regular text content.
699704
700 - `BetaManagedAgentsImageBlock object { source, type }`
705 - `BetaManagedAgentsImageBlock object`
701706
702707 Image content specified directly as base64 data or as a reference via a URL.
703708
704 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
709 - `BetaManagedAgentsDocumentBlock object`
705710
706711 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
707712
708 - `BetaManagedAgentsRedactedBlock object { type }`
713 - `BetaManagedAgentsRedactedBlock object`
709714
710715 Placeholder for content withheld by Anthropic model policy.
711716
from line 722
717722
718723 A timestamp in RFC 3339 format
719724
725 format: date-time
726
720727 - `type: "agent.thread_message_received"`
721728
722 - `"agent.thread_message_received"`
723
724729 - `from_agent_name: optional string or null`
725730
726731 Name of the callable agent this message came from. Absent when received from the primary agent.
727732
728 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
733 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
729734
730735 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
731736
from line 742
737742
738743 Message content blocks.
739744
740 - `BetaManagedAgentsTextBlock object { text, type }`
745 - `BetaManagedAgentsTextBlock object`
741746
742747 Regular text content.
743748
744 - `BetaManagedAgentsImageBlock object { source, type }`
749 - `BetaManagedAgentsImageBlock object`
745750
746751 Image content specified directly as base64 data or as a reference via a URL.
747752
748 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
753 - `BetaManagedAgentsDocumentBlock object`
749754
750755 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
751756
752 - `BetaManagedAgentsRedactedBlock object { type }`
757 - `BetaManagedAgentsRedactedBlock object`
753758
754759 Placeholder for content withheld by Anthropic model policy.
755760
from line 762
757762
758763 A timestamp in RFC 3339 format
759764
765 format: date-time
766
760767 - `to_session_thread_id: string`
761768
762769 Public `sthr_` ID of the thread the message was sent to.
763770
764771 - `type: "agent.thread_message_sent"`
765772
766 - `"agent.thread_message_sent"`
767
768773 - `to_agent_name: optional string or null`
769774
770775 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
771776
772 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
777 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
773778
774779 Indicates that context compaction (summarization) occurred during the session.
775780
from line 786
781786
782787 A timestamp in RFC 3339 format
783788
789 format: date-time
790
784791 - `type: "agent.thread_context_compacted"`
785792
786 - `"agent.thread_context_compacted"`
787
788 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
793 - `BetaManagedAgentsSessionErrorEvent object`
789794
790795 An error event indicating a problem occurred during session execution.
791796
from line 802
797802
798803 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.
799804
800 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
805 - `BetaManagedAgentsUnknownError object`
801806
802807 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.
803808
from line 814
809814
810815 What the client should do next in response to this error.
811816
812 - `BetaManagedAgentsRetryStatusRetrying object { type }`
817 - `BetaManagedAgentsRetryStatusRetrying object`
813818
814819 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.
815820
816821 - `type: "retrying"`
817822
818 - `"retrying"`
819
820 - `BetaManagedAgentsRetryStatusExhausted object { type }`
823 - `BetaManagedAgentsRetryStatusExhausted object`
821824
822825 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
823826
824827 - `type: "exhausted"`
825828
826 - `"exhausted"`
827
828 - `BetaManagedAgentsRetryStatusTerminal object { type }`
829 - `BetaManagedAgentsRetryStatusTerminal object`
829830
830831 The session encountered a terminal error and will transition to `terminated` state.
831832
832833 - `type: "terminal"`
833834
834 - `"terminal"`
835
836835 - `type: "unknown_error"`
837836
838 - `"unknown_error"`
839
840 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
837 - `BetaManagedAgentsModelOverloadedError object`
841838
842839 The model is currently overloaded. Emitted after automatic retries are exhausted.
843840
from line 846
849846
850847 What the client should do next in response to this error.
851848
852 - `BetaManagedAgentsRetryStatusRetrying object { type }`
849 - `BetaManagedAgentsRetryStatusRetrying object`
853850
854851 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.
855852
856 - `BetaManagedAgentsRetryStatusExhausted object { type }`
853 - `BetaManagedAgentsRetryStatusExhausted object`
857854
858855 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
859856
860 - `BetaManagedAgentsRetryStatusTerminal object { type }`
857 - `BetaManagedAgentsRetryStatusTerminal object`
861858
862859 The session encountered a terminal error and will transition to `terminated` state.
863860
864861 - `type: "model_overloaded_error"`
865862
866 - `"model_overloaded_error"`
867
868 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
863 - `BetaManagedAgentsModelRateLimitedError object`
869864
870865 The model request was rate-limited.
871866
from line 872
877872
878873 What the client should do next in response to this error.
879874
880 - `BetaManagedAgentsRetryStatusRetrying object { type }`
875 - `BetaManagedAgentsRetryStatusRetrying object`
881876
882877 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.
883878
884 - `BetaManagedAgentsRetryStatusExhausted object { type }`
879 - `BetaManagedAgentsRetryStatusExhausted object`
885880
886881 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
887882
888 - `BetaManagedAgentsRetryStatusTerminal object { type }`
883 - `BetaManagedAgentsRetryStatusTerminal object`
889884
890885 The session encountered a terminal error and will transition to `terminated` state.
891886
892887 - `type: "model_rate_limited_error"`
893888
894 - `"model_rate_limited_error"`
895
896 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
889 - `BetaManagedAgentsModelRequestFailedError object`
897890
898891 A model request failed for a reason other than overload or rate-limiting.
899892
from line 898
905898
906899 What the client should do next in response to this error.
907900
908 - `BetaManagedAgentsRetryStatusRetrying object { type }`
901 - `BetaManagedAgentsRetryStatusRetrying object`
909902
910903 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.
911904
912 - `BetaManagedAgentsRetryStatusExhausted object { type }`
905 - `BetaManagedAgentsRetryStatusExhausted object`
913906
914907 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
915908
916 - `BetaManagedAgentsRetryStatusTerminal object { type }`
909 - `BetaManagedAgentsRetryStatusTerminal object`
917910
918911 The session encountered a terminal error and will transition to `terminated` state.
919912
920913 - `type: "model_request_failed_error"`
921914
922 - `"model_request_failed_error"`
923
924 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
915 - `BetaManagedAgentsMCPConnectionFailedError object`
925916
926917 Failed to connect to an MCP server.
927918
from line 928
937928
938929 What the client should do next in response to this error.
939930
940 - `BetaManagedAgentsRetryStatusRetrying object { type }`
931 - `BetaManagedAgentsRetryStatusRetrying object`
941932
942933 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.
943934
944 - `BetaManagedAgentsRetryStatusExhausted object { type }`
935 - `BetaManagedAgentsRetryStatusExhausted object`
945936
946937 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
947938
948 - `BetaManagedAgentsRetryStatusTerminal object { type }`
939 - `BetaManagedAgentsRetryStatusTerminal object`
949940
950941 The session encountered a terminal error and will transition to `terminated` state.
951942
952943 - `type: "mcp_connection_failed_error"`
953944
954 - `"mcp_connection_failed_error"`
955
956 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
945 - `BetaManagedAgentsMCPAuthenticationFailedError object`
957946
958947 Authentication to an MCP server failed.
959948
from line 958
969958
970959 What the client should do next in response to this error.
971960
972 - `BetaManagedAgentsRetryStatusRetrying object { type }`
961 - `BetaManagedAgentsRetryStatusRetrying object`
973962
974963 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.
975964
976 - `BetaManagedAgentsRetryStatusExhausted object { type }`
965 - `BetaManagedAgentsRetryStatusExhausted object`
977966
978967 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
979968
980 - `BetaManagedAgentsRetryStatusTerminal object { type }`
969 - `BetaManagedAgentsRetryStatusTerminal object`
981970
982971 The session encountered a terminal error and will transition to `terminated` state.
983972
984973 - `type: "mcp_authentication_failed_error"`
985974
986 - `"mcp_authentication_failed_error"`
987
988 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
975 - `BetaManagedAgentsBillingError object`
989976
990977 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.
991978
from line 984
997984
998985 What the client should do next in response to this error.
999986
1000 - `BetaManagedAgentsRetryStatusRetrying object { type }`
987 - `BetaManagedAgentsRetryStatusRetrying object`
1001988
1002989 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.
1003990
1004 - `BetaManagedAgentsRetryStatusExhausted object { type }`
991 - `BetaManagedAgentsRetryStatusExhausted object`
1005992
1006993 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1007994
1008 - `BetaManagedAgentsRetryStatusTerminal object { type }`
995 - `BetaManagedAgentsRetryStatusTerminal object`
1009996
1010997 The session encountered a terminal error and will transition to `terminated` state.
1011998
1012999 - `type: "billing_error"`
10131000
1014 - `"billing_error"`
1015
1016 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
1001 - `BetaManagedAgentsCredentialHostUnreachableError object`
10171002
10181003 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
10191004
from line 1014
10291014
10301015 What the client should do next in response to this error.
10311016
1032 - `BetaManagedAgentsRetryStatusRetrying object { type }`
1017 - `BetaManagedAgentsRetryStatusRetrying object`
10331018
10341019 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.
10351020
1036 - `BetaManagedAgentsRetryStatusExhausted object { type }`
1021 - `BetaManagedAgentsRetryStatusExhausted object`
10371022
10381023 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
10391024
1040 - `BetaManagedAgentsRetryStatusTerminal object { type }`
1025 - `BetaManagedAgentsRetryStatusTerminal object`
10411026
10421027 The session encountered a terminal error and will transition to `terminated` state.
10431028
10441029 - `type: "credential_host_unreachable_error"`
10451030
1046 - `"credential_host_unreachable_error"`
1047
10481031 - `vault_id: string`
10491032
10501033 ID of the vault containing the affected credential.
from line 1036
10531036
10541037 A timestamp in RFC 3339 format
10551038
1039 format: date-time
1040
10561041 - `type: "session.error"`
10571042
1058 - `"session.error"`
1059
1060 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
1043 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
10611044
10621045 Indicates the session is recovering from an error state and is rescheduled for execution.
10631046
from line 1052
10691052
10701053 A timestamp in RFC 3339 format
10711054
1055 format: date-time
1056
10721057 - `type: "session.status_rescheduled"`
10731058
1074 - `"session.status_rescheduled"`
1075
1076 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
1059 - `BetaManagedAgentsSessionStatusRunningEvent object`
10771060
10781061 Indicates the session is actively running and the agent is working.
10791062
from line 1068
10851068
10861069 A timestamp in RFC 3339 format
10871070
1071 format: date-time
1072
10881073 - `type: "session.status_running"`
10891074
1090 - `"session.status_running"`
1091
1092 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
1075 - `BetaManagedAgentsSessionStatusIdleEvent object`
10931076
10941077 Indicates the agent has paused and is awaiting user input.
10951078
from line 1084
11011084
11021085 A timestamp in RFC 3339 format
11031086
1087 format: date-time
1088
11041089 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
11051090
11061091 The agent completed its turn naturally and is ready for the next user message.
11071092
1108 - `BetaManagedAgentsSessionEndTurn object { type }`
1093 - `BetaManagedAgentsSessionEndTurn object`
11091094
11101095 The agent completed its turn naturally and is ready for the next user message.
11111096
11121097 - `type: "end_turn"`
11131098
1114 - `"end_turn"`
1115
1116 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1099 - `BetaManagedAgentsSessionRequiresAction object`
11171100
11181101 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.
11191102
from line 1106
11231106
11241107 - `type: "requires_action"`
11251108
1126 - `"requires_action"`
1127
1128 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1109 - `BetaManagedAgentsSessionRetriesExhausted object`
11291110
11301111 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
11311112
11321113 - `type: "retries_exhausted"`
11331114
1134 - `"retries_exhausted"`
1135
1136 - `BetaManagedAgentsSessionBudgetReached object { type }`
1115 - `BetaManagedAgentsSessionBudgetReached object`
11371116
11381117 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.
11391118
11401119 - `type: "budget_reached"`
11411120
1142 - `"budget_reached"`
1143
11441121 - `type: "session.status_idle"`
11451122
1146 - `"session.status_idle"`
1147
1148 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
1123 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
11491124
11501125 Indicates the session has terminated, either due to an error or completion.
11511126
from line 1132
11571132
11581133 A timestamp in RFC 3339 format
11591134
1135 format: date-time
1136
11601137 - `type: "session.status_terminated"`
11611138
1162 - `"session.status_terminated"`
1163
1164 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
1139 - `BetaManagedAgentsSessionThreadCreatedEvent object`
11651140
11661141 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.
11671142
from line 1152
11771152
11781153 A timestamp in RFC 3339 format
11791154
1155 format: date-time
1156
11801157 - `session_thread_id: string`
11811158
11821159 Public `sthr_` ID of the newly created thread.
11831160
11841161 - `type: "session.thread_created"`
11851162
1186 - `"session.thread_created"`
1187
1188 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
1163 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
11891164
11901165 Emitted when an outcome evaluation cycle begins.
11911166
from line 1172
11971172
11981173 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
11991174
1175 format: int32
1176
12001177 - `outcome_id: string`
12011178
12021179 The `outc_` ID of the outcome being evaluated.
from line 1182
12051182
12061183 A timestamp in RFC 3339 format
12071184
1185 format: date-time
1186
12081187 - `type: "span.outcome_evaluation_start"`
12091188
1210 - `"span.outcome_evaluation_start"`
1211
1212 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
1189 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
12131190
12141191 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.
12151192
from line 1202
12251202
12261203 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
12271204
1205 format: int32
1206
12281207 - `outcome_evaluation_start_id: string`
12291208
12301209 The id of the corresponding `span.outcome_evaluation_start` event.
from line 1216
12371216
12381217 A timestamp in RFC 3339 format
12391218
1219 format: date-time
1220
12401221 - `result: string`
12411222
12421223 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.
12431224
12441225 - `type: "span.outcome_evaluation_end"`
12451226
1246 - `"span.outcome_evaluation_end"`
1247
12481227 - `usage: BetaManagedAgentsSpanModelUsage`
12491228
12501229 Token usage for a single model request.
from line 1232
12531232
12541233 Tokens used to create prompt cache in this request.
12551234
1235 format: int32
1236
12561237 - `cache_read_input_tokens: number`
12571238
12581239 Tokens read from prompt cache in this request.
12591240
1241 format: int32
1242
12601243 - `input_tokens: number`
12611244
12621245 Input tokens consumed by this request.
12631246
1247 format: int32
1248
12641249 - `output_tokens: number`
12651250
12661251 Output tokens generated by this request.
12671252
1253 format: int32
1254
12681255 - `speed: optional "standard" or "fast" or null`
12691256
12701257 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 1260
12731260
12741261 - `"fast"`
12751262
1276 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
1263 - `BetaManagedAgentsSpanModelRequestStartEvent object`
12771264
12781265 Emitted when a model request is initiated by the agent.
12791266
from line 1272
12851272
12861273 A timestamp in RFC 3339 format
12871274
1275 format: date-time
1276
12881277 - `type: "span.model_request_start"`
12891278
1290 - `"span.model_request_start"`
1291
1292 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
1279 - `BetaManagedAgentsSpanModelRequestEndEvent object`
12931280
12941281 Emitted when a model request completes.
12951282
from line 1300
13131300
13141301 A timestamp in RFC 3339 format
13151302
1303 format: date-time
1304
13161305 - `type: "span.model_request_end"`
13171306
1318 - `"span.model_request_end"`
1319
1320 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
1307 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
13211308
13221309 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.
13231310
from line 1316
13291316
13301317 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
13311318
1319 format: int32
1320
13321321 - `outcome_id: string`
13331322
13341323 The `outc_` ID of the outcome being evaluated.
from line 1326
13371326
13381327 A timestamp in RFC 3339 format
13391328
1329 format: date-time
1330
13401331 - `type: "span.outcome_evaluation_ongoing"`
13411332
1342 - `"span.outcome_evaluation_ongoing"`
1343
1344 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
1333 - `BetaManagedAgentsUserDefineOutcomeEvent object`
13451334
13461335 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
13471336
from line 1346
13571346
13581347 Evaluate-then-revise cycles before giving up. Default 3, max 20.
13591348
1349 format: int32
1350
13601351 - `outcome_id: string`
13611352
13621353 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1356
13651356
13661357 A timestamp in RFC 3339 format
13671358
1359 format: date-time
1360
13681361 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
13691362
13701363 Rubric for grading the quality of an outcome.
13711364
1372 - `BetaManagedAgentsFileRubric object { file_id, type }`
1365 - `BetaManagedAgentsFileRubric object`
13731366
13741367 Rubric referenced by a file uploaded via the Files API.
13751368
from line 1372
13791372
13801373 - `type: "file"`
13811374
1382 - `"file"`
1383
1384 - `BetaManagedAgentsTextRubric object { content, type }`
1375 - `BetaManagedAgentsTextRubric object`
13851376
13861377 Rubric content provided inline as text.
13871378
from line 1382
13911382
13921383 - `type: "text"`
13931384
1394 - `"text"`
1395
13961385 - `type: "user.define_outcome"`
13971386
1398 - `"user.define_outcome"`
1399
1400 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
1387 - `BetaManagedAgentsSessionDeletedEvent object`
14011388
14021389 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
14031390
from line 1396
14091396
14101397 A timestamp in RFC 3339 format
14111398
1399 format: date-time
1400
14121401 - `type: "session.deleted"`
14131402
1414 - `"session.deleted"`
1415
1416 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
1403 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
14171404
14181405 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14191406
from line 1416
14291416
14301417 A timestamp in RFC 3339 format
14311418
1419 format: date-time
1420
14321421 - `session_thread_id: string`
14331422
14341423 Public sthr_ ID of the thread that started running.
14351424
14361425 - `type: "session.thread_status_running"`
14371426
1438 - `"session.thread_status_running"`
1439
1440 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
1427 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
14411428
14421429 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.
14431430
from line 1440
14531440
14541441 A timestamp in RFC 3339 format
14551442
1443 format: date-time
1444
14561445 - `session_thread_id: string`
14571446
14581447 Public sthr_ ID of the thread that went idle.
from line 1450
14611450
14621451 The agent completed its turn naturally and is ready for the next user message.
14631452
1464 - `BetaManagedAgentsSessionEndTurn object { type }`
1453 - `BetaManagedAgentsSessionEndTurn object`
14651454
14661455 The agent completed its turn naturally and is ready for the next user message.
14671456
1468 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1457 - `BetaManagedAgentsSessionRequiresAction object`
14691458
14701459 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.
14711460
1472 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1461 - `BetaManagedAgentsSessionRetriesExhausted object`
14731462
14741463 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
14751464
1476 - `BetaManagedAgentsSessionBudgetReached object { type }`
1465 - `BetaManagedAgentsSessionBudgetReached object`
14771466
14781467 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.
14791468
14801469 - `type: "session.thread_status_idle"`
14811470
1482 - `"session.thread_status_idle"`
1483
1484 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
1471 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
14851472
14861473 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.
14871474
from line 1484
14971484
14981485 A timestamp in RFC 3339 format
14991486
1487 format: date-time
1488
15001489 - `session_thread_id: string`
15011490
15021491 Public sthr_ ID of the thread that terminated.
15031492
15041493 - `type: "session.thread_status_terminated"`
15051494
1506 - `"session.thread_status_terminated"`
1507
1508 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
1495 - `BetaManagedAgentsUserToolResultEvent object`
15091496
15101497 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.
15111498
from line 1506
15191506
15201507 - `type: "user.tool_result"`
15211508
1522 - `"user.tool_result"`
1523
15241509 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
15251510
15261511 The result content returned by the tool.
15271512
1528 - `BetaManagedAgentsTextBlock object { text, type }`
1513 - `BetaManagedAgentsTextBlock object`
15291514
15301515 Regular text content.
15311516
1532 - `BetaManagedAgentsImageBlock object { source, type }`
1517 - `BetaManagedAgentsImageBlock object`
15331518
15341519 Image content specified directly as base64 data or as a reference via a URL.
15351520
1536 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1521 - `BetaManagedAgentsDocumentBlock object`
15371522
15381523 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
15391524
1540 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
1525 - `BetaManagedAgentsSearchResultBlock object`
15411526
15421527 A block containing a web search result.
15431528
from line 1534
15491534
15501535 A timestamp in RFC 3339 format
15511536
1537 format: date-time
1538
15521539 - `session_thread_id: optional string or null`
15531540
15541541 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
15551542
1556 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
1543 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
15571544
15581545 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.
15591546
from line 1556
15691556
15701557 A timestamp in RFC 3339 format
15711558
1559 format: date-time
1560
15721561 - `session_thread_id: string`
15731562
15741563 Public sthr_ ID of the thread that is retrying.
15751564
15761565 - `type: "session.thread_status_rescheduled"`
15771566
1578 - `"session.thread_status_rescheduled"`
1579
1580 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
1567 - `BetaManagedAgentsSessionUpdatedEvent object`
15811568
15821569 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.
15831570
from line 1576
15891576
15901577 A timestamp in RFC 3339 format
15911578
1579 format: date-time
1580
15921581 - `type: "session.updated"`
15931582
1594 - `"session.updated"`
1595
15961583 - `agent: optional BetaManagedAgentsSessionAgent or null`
15971584
15981585 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1594
16071594
16081595 - `type: "url"`
16091596
1610 - `"url"`
1611
16121597 - `url: string`
16131598
16141599 - `model: BetaManagedAgentsModelConfig`
from line 1670
16851670
16861671 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16871672
1688 - `BetaManagedAgentsEffortLow object { type }`
1673 - `BetaManagedAgentsEffortLow object`
16891674
16901675 Low effort. Favors latency over reasoning depth.
16911676
16921677 - `type: "low"`
16931678
1694 - `"low"`
1695
1696 - `BetaManagedAgentsEffortMedium object { type }`
1679 - `BetaManagedAgentsEffortMedium object`
16971680
16981681 Medium effort. Balances latency and reasoning depth.
16991682
17001683 - `type: "medium"`
17011684
1702 - `"medium"`
1703
1704 - `BetaManagedAgentsEffortHigh object { type }`
1685 - `BetaManagedAgentsEffortHigh object`
17051686
17061687 High effort. Favors reasoning depth.
17071688
17081689 - `type: "high"`
17091690
1710 - `"high"`
1711
1712 - `BetaManagedAgentsEffortXhigh object { type }`
1691 - `BetaManagedAgentsEffortXhigh object`
17131692
17141693 Extra-high effort. Not all models accept this level.
17151694
17161695 - `type: "xhigh"`
17171696
1718 - `"xhigh"`
1719
1720 - `BetaManagedAgentsEffortMax object { type }`
1697 - `BetaManagedAgentsEffortMax object`
17211698
17221699 Maximum effort. Favors reasoning depth over latency.
17231700
17241701 - `type: "max"`
17251702
1726 - `"max"`
1727
17281703 - `inference_geo: optional string`
17291704
17301705 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1720
17451720
17461721 Full `agent` definitions the coordinator may spawn as session threads.
17471722
1748 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1723 - `BetaManagedAgentsSessionThreadAgent object`
17491724
17501725 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`.
17511726
from line 1744
17691744
17701745 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17711746
1772 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1747 - `BetaManagedAgentsAnthropicSkill object`
17731748
17741749 A resolved Anthropic-managed skill.
17751750
from line 1752
17771752
17781753 - `type: "anthropic"`
17791754
1780 - `"anthropic"`
1781
17821755 - `version: string`
17831756
1784 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1757 - `BetaManagedAgentsCustomSkill object`
17851758
17861759 A resolved user-created custom skill.
17871760
from line 1762
17891762
17901763 - `type: "custom"`
17911764
1792 - `"custom"`
1793
17941765 - `version: string`
17951766
17961767 - `system: string or null`
17971768
17981769 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17991770
1800 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1771 - `BetaManagedAgentsAgentToolset20260401 object`
18011772
18021773 - `configs: array of BetaManagedAgentsAgentToolConfig`
18031774
1804 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1775 - `BetaManagedAgentsBashToolConfig object`
18051776
18061777 Configuration for the bash tool.
18071778
from line 1780
18091780
18101781 - `name: "bash"`
18111782
1812 - `"bash"`
1813
18141783 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18151784
18161785 Permission policy for tool execution.
18171786
1818 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1787 - `BetaManagedAgentsAlwaysAllowPolicy object`
18191788
18201789 Tool calls are automatically approved without user confirmation.
18211790
18221791 - `type: "always_allow"`
18231792
1824 - `"always_allow"`
1825
1826 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1793 - `BetaManagedAgentsAlwaysAskPolicy object`
18271794
18281795 Tool calls require user confirmation before execution.
18291796
18301797 - `type: "always_ask"`
18311798
1832 - `"always_ask"`
1833
18341799 - `type: "bash"`
18351800
1836 - `"bash"`
1837
1838 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1801 - `BetaManagedAgentsEditToolConfig object`
18391802
18401803 Configuration for the edit tool.
18411804
from line 1806
18431806
18441807 - `name: "edit"`
18451808
1846 - `"edit"`
1847
18481809 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18491810
18501811 Permission policy for tool execution.
18511812
1852 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1813 - `BetaManagedAgentsAlwaysAllowPolicy object`
18531814
18541815 Tool calls are automatically approved without user confirmation.
18551816
1856 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1817 - `BetaManagedAgentsAlwaysAskPolicy object`
18571818
18581819 Tool calls require user confirmation before execution.
18591820
18601821 - `type: "edit"`
18611822
1862 - `"edit"`
1863
1864 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1823 - `BetaManagedAgentsReadToolConfig object`
18651824
18661825 Configuration for the read tool.
18671826
from line 1828
18691828
18701829 - `name: "read"`
18711830
1872 - `"read"`
1873
18741831 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18751832
18761833 Permission policy for tool execution.
18771834
1878 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1835 - `BetaManagedAgentsAlwaysAllowPolicy object`
18791836
18801837 Tool calls are automatically approved without user confirmation.
18811838
1882 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1839 - `BetaManagedAgentsAlwaysAskPolicy object`
18831840
18841841 Tool calls require user confirmation before execution.
18851842
18861843 - `type: "read"`
18871844
1888 - `"read"`
1889
1890 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1845 - `BetaManagedAgentsWriteToolConfig object`
18911846
18921847 Configuration for the write tool.
18931848
from line 1850
18951850
18961851 - `name: "write"`
18971852
1898 - `"write"`
1899
19001853 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19011854
19021855 Permission policy for tool execution.
19031856
1904 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1857 - `BetaManagedAgentsAlwaysAllowPolicy object`
19051858
19061859 Tool calls are automatically approved without user confirmation.
19071860
1908 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1861 - `BetaManagedAgentsAlwaysAskPolicy object`
19091862
19101863 Tool calls require user confirmation before execution.
19111864
19121865 - `type: "write"`
19131866
1914 - `"write"`
1915
1916 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1867 - `BetaManagedAgentsGlobToolConfig object`
19171868
19181869 Configuration for the glob tool.
19191870
from line 1872
19211872
19221873 - `name: "glob"`
19231874
1924 - `"glob"`
1925
19261875 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19271876
19281877 Permission policy for tool execution.
19291878
1930 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1879 - `BetaManagedAgentsAlwaysAllowPolicy object`
19311880
19321881 Tool calls are automatically approved without user confirmation.
19331882
1934 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1883 - `BetaManagedAgentsAlwaysAskPolicy object`
19351884
19361885 Tool calls require user confirmation before execution.
19371886
19381887 - `type: "glob"`
19391888
1940 - `"glob"`
1941
1942 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1889 - `BetaManagedAgentsGrepToolConfig object`
19431890
19441891 Configuration for the grep tool.
19451892
from line 1894
19471894
19481895 - `name: "grep"`
19491896
1950 - `"grep"`
1951
19521897 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19531898
19541899 Permission policy for tool execution.
19551900
1956 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1901 - `BetaManagedAgentsAlwaysAllowPolicy object`
19571902
19581903 Tool calls are automatically approved without user confirmation.
19591904
1960 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1905 - `BetaManagedAgentsAlwaysAskPolicy object`
19611906
19621907 Tool calls require user confirmation before execution.
19631908
19641909 - `type: "grep"`
19651910
1966 - `"grep"`
1967
1968 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1911 - `BetaManagedAgentsWebFetchToolConfig object`
19691912
19701913 Configuration for the web_fetch tool.
19711914
from line 1916
19731916
19741917 - `name: "web_fetch"`
19751918
1976 - `"web_fetch"`
1977
19781919 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19791920
19801921 Permission policy for tool execution.
19811922
1982 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1923 - `BetaManagedAgentsAlwaysAllowPolicy object`
19831924
19841925 Tool calls are automatically approved without user confirmation.
19851926
1986 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1927 - `BetaManagedAgentsAlwaysAskPolicy object`
19871928
19881929 Tool calls require user confirmation before execution.
19891930
19901931 - `type: "web_fetch"`
19911932
1992 - `"web_fetch"`
1993
19941933 - `allowed_domains: optional array of string`
19951934
19961935 - `blocked_domains: optional array of string`
19971936
19981937 - `max_content_tokens: optional number or null`
19991938
2000 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1939 format: int32
1940
1941 - `BetaManagedAgentsWebSearchToolConfig object`
20011942
20021943 Configuration for the web_search tool.
20031944
from line 1946
20051946
20061947 - `name: "web_search"`
20071948
2008 - `"web_search"`
2009
20101949 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
20111950
20121951 Permission policy for tool execution.
20131952
2014 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1953 - `BetaManagedAgentsAlwaysAllowPolicy object`
20151954
20161955 Tool calls are automatically approved without user confirmation.
20171956
2018 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1957 - `BetaManagedAgentsAlwaysAskPolicy object`
20191958
20201959 Tool calls require user confirmation before execution.
20211960
20221961 - `type: "web_search"`
20231962
2024 - `"web_search"`
2025
20261963 - `allowed_domains: optional array of string`
20271964
20281965 - `blocked_domains: optional array of string`
from line 1972
20351972
20361973 Location precision. Only "approximate" is supported.
20371974
2038 - `"approximate"`
2039
20401975 - `city: optional string or null`
20411976
20421977 City name.
20431978
1979 minLength: 1, maxLength: 255
1980
20441981 - `country: optional string or null`
20451982
20461983 Two-letter ISO 3166-1 country code, uppercase.
from line 1986
20491986
20501987 Region or state name.
20511988
1989 minLength: 1, maxLength: 255
1990
20521991 - `timezone: optional string or null`
20531992
20541993 IANA timezone identifier, e.g. "America/Los_Angeles".
20551994
1995 minLength: 1, maxLength: 255
1996
20561997 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20571998
20581999 Resolved default configuration for agent tools.
from line 2004
20632004
20642005 Permission policy for tool execution.
20652006
2066 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2007 - `BetaManagedAgentsAlwaysAllowPolicy object`
20672008
20682009 Tool calls are automatically approved without user confirmation.
20692010
2070 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2011 - `BetaManagedAgentsAlwaysAskPolicy object`
20712012
20722013 Tool calls require user confirmation before execution.
20732014
20742015 - `type: "agent_toolset_20260401"`
20752016
2076 - `"agent_toolset_20260401"`
2077
2078 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2017 - `BetaManagedAgentsMCPToolset object`
20792018
20802019 - `configs: array of BetaManagedAgentsMCPToolConfig`
20812020
from line 2026
20872026
20882027 Permission policy for tool execution.
20892028
2090 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2029 - `BetaManagedAgentsAlwaysAllowPolicy object`
20912030
20922031 Tool calls are automatically approved without user confirmation.
20932032
2094 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2033 - `BetaManagedAgentsAlwaysAskPolicy object`
20952034
20962035 Tool calls require user confirmation before execution.
20972036
from line 2044
21052044
21062045 Permission policy for tool execution.
21072046
2108 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2047 - `BetaManagedAgentsAlwaysAllowPolicy object`
21092048
21102049 Tool calls are automatically approved without user confirmation.
21112050
2112 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2051 - `BetaManagedAgentsAlwaysAskPolicy object`
21132052
21142053 Tool calls require user confirmation before execution.
21152054
from line 2056
21172056
21182057 - `type: "mcp_toolset"`
21192058
2120 - `"mcp_toolset"`
2121
2122 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2059 - `BetaManagedAgentsCustomTool object`
21232060
21242061 A custom tool as returned in API responses.
21252062
from line 2068
21312068
21322069 - `type: "object"`
21332070
2134 - `"object"`
2135
21362071 - `properties: optional map[unknown] or null`
21372072
21382073 - `required: optional array of string or null`
from line 2076
21412076
21422077 - `type: "custom"`
21432078
2144 - `"custom"`
2145
21462079 - `type: "agent"`
21472080
2148 - `"agent"`
2149
21502081 - `version: number`
21512082
2152 - `BetaManagedAgentsAdvisor object { model, type }`
2083 format: int32
2084
2085 - `BetaManagedAgentsAdvisor object`
21532086
21542087 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
21552088
from line 2092
21592092
21602093 - `type: "advisor"`
21612094
2162 - `"advisor"`
2163
21642095 - `type: "coordinator"`
21652096
2166 - `"coordinator"`
2167
21682097 - `name: string`
21692098
21702099 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
21712100
2172 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2101 - `BetaManagedAgentsAnthropicSkill object`
21732102
21742103 A resolved Anthropic-managed skill.
21752104
2176 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2105 - `BetaManagedAgentsCustomSkill object`
21772106
21782107 A resolved user-created custom skill.
21792108
from line 2110
21812110
21822111 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
21832112
2184 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2185
2186 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2187
2188 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2113 - `BetaManagedAgentsAgentToolset20260401 object`
2114
2115 - `BetaManagedAgentsMCPToolset object`
2116
2117 - `BetaManagedAgentsCustomTool object`
21892118
21902119 A custom tool as returned in API responses.
21912120
21922121 - `type: "agent"`
21932122
2194 - `"agent"`
2195
21962123 - `version: number`
21972124
2125 format: int32
2126
21982127 - `budget: optional BetaManagedAgentsBudgetLimit or null`
21992128
22002129 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2140
22112140
22122141 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.
22132142
2214 - `"USD"`
2215
22162143 - `type: "limit"`
22172144
2218 - `"limit"`
2219
22202145 - `metadata: optional map[string]`
22212146
22222147 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 2150
22252150
22262151 The session's new title. Present only when the update changed it.
22272152
2228 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
2153 - `BetaManagedAgentsSystemMessageEvent object`
22292154
22302155 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
22312156
from line 2166
22412166
22422167 The text content.
22432168
2169 minLength: 1
2170
22442171 - `type: "text"`
22452172
2246 - `"text"`
2247
22482173 - `type: "system.message"`
22492174
2250 - `"system.message"`
2251
22522175 - `processed_at: optional string or null`
22532176
22542177 A timestamp in RFC 3339 format
22552178
2256 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
2179 format: date-time
2180
2181 - `BetaManagedAgentsSessionUsageEvent object`
22572182
22582183 Periodic snapshot of the session's cumulative usage and tracked list cost.
22592184
from line 2190
22652190
22662191 A timestamp in RFC 3339 format
22672192
2193 format: date-time
2194
22682195 - `type: "session.usage"`
22692196
2270 - `"session.usage"`
2271
22722197 - `usage: BetaManagedAgentsSessionUsageSnapshot`
22732198
22742199 Point-in-time snapshot of a session's cumulative usage.
from line 2202
22772202
22782203 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.
22792204
2205 format: double
2206
22802207 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
22812208
22822209 Prompt-cache creation token usage broken down by cache lifetime.
from line 2212
22852212
22862213 Tokens used to create 1-hour ephemeral cache entries.
22872214
2215 format: int32
2216
22882217 - `ephemeral_5m_input_tokens: optional number`
22892218
22902219 Tokens used to create 5-minute ephemeral cache entries.
22912220
2221 format: int32
2222
22922223 - `cache_read_input_tokens: optional number`
22932224
22942225 Total tokens read from prompt cache.
22952226
2227 format: int32
2228
22962229 - `input_tokens: optional number`
22972230
22982231 Total input tokens consumed across all turns.
22992232
2233 format: int32
2234
23002235 - `list_cost: optional BetaMonetaryAmount`
23012236
23022237 A monetary amount in a specific currency.
from line 2240
23052240
23062241 Total output tokens generated across all turns.
23072242
2243 format: int32
2244
23082245 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
23092246
23102247 Cumulative count of server-executed tool invocations, broken down by tool.
from line 2250
23132250
23142251 Number of server-executed web fetch requests.
23152252
2253 format: int32
2254
23162255 - `web_search_requests: optional number`
23172256
23182257 Number of server-executed web search requests.
23192258
2259 format: int32
2260
23202261 - `budget: optional BetaManagedAgentsBudgetLimit or null`
23212262
23222263 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2266
23252266
23262267 Opaque cursor for the next page. Null when no more results.
23272268
2328### Example
2329
2330```http
2269## Example
2270
2271```bash
23312272curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
23322273 -H 'anthropic-version: 2023-06-01' \
23332274 -H 'anthropic-beta: managed-agents-2026-04-01' \
23342275 -H "X-Api-Key: $ANTHROPIC_API_KEY"
23352276```
23362277
2337#### Response
2278### Response (200)
23382279
23392280```json
23402281{
23412282
api/beta/sessions/events/send Changed · +155 / -170 lines
# Send Events ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Send Events ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Send Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/events/send
4---
1# Send Events
52
6## Send Events
3**POST** `/v1/sessions/{session_id}/events`
74
8**post** `/v1/sessions/{session_id}/events`
9
105Send Events
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- `events: array of BetaManagedAgentsEventParams`
9792
9893 Events to send to the `session`.
9994
100 - `BetaManagedAgentsUserMessageEventParams object { content, type }`
95 - `BetaManagedAgentsUserMessageEventParams object`
10196
10297 Parameters for sending a user message to the session.
10398
from line 100
105100
106101 Array of content blocks for the user message.
107102
108 - `BetaManagedAgentsTextBlock object { text, type }`
103 - `BetaManagedAgentsTextBlock object`
109104
110105 Regular text content.
111106
from line 108
113108
114109 The text content.
115110
111 minLength: 1
112
116113 - `type: "text"`
117114
118 - `"text"`
115 - `BetaManagedAgentsImageBlock object`
119116
120 - `BetaManagedAgentsImageBlock object { source, type }`
121
122117 Image content specified directly as base64 data or as a reference via a URL.
123118
124119 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 120
125120
126121 Union type for image source variants.
127122
128 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
123 - `BetaManagedAgentsBase64ImageSource object`
129124
130125 Base64-encoded image data.
131126
from line 128
133128
134129 Base64-encoded image data.
135130
131 minLength: 1
132
136133 - `media_type: string`
137134
138135 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
139136
137 minLength: 1
138
140139 - `type: "base64"`
141140
142 - `"base64"`
141 - `BetaManagedAgentsURLImageSource object`
143142
144 - `BetaManagedAgentsURLImageSource object { type, url }`
145
146143 Image referenced by URL.
147144
148145 - `type: "url"`
149146
150 - `"url"`
151
152147 - `url: string`
153148
154149 URL of the image to fetch.
155150
156 - `BetaManagedAgentsFileImageSource object { file_id, type }`
151 minLength: 1
157152
153 - `BetaManagedAgentsFileImageSource object`
154
158155 Image referenced by file ID.
159156
160157 - `file_id: string`
from line 158
161158
162159 ID of a previously uploaded file.
163160
161 minLength: 1
162
164163 - `type: "file"`
165164
166 - `"file"`
167
168165 - `type: "image"`
169166
170 - `"image"`
167 - `BetaManagedAgentsDocumentBlock object`
171168
172 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
173
174169 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
175170
176171 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 172
177172
178173 Union type for document source variants.
179174
180 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
175 - `BetaManagedAgentsBase64DocumentSource object`
181176
182177 Base64-encoded document data.
183178
from line 180
185180
186181 Base64-encoded document data.
187182
183 minLength: 1
184
188185 - `media_type: string`
189186
190187 MIME type of the document (e.g., "application/pdf").
191188
189 minLength: 1
190
192191 - `type: "base64"`
193192
194 - `"base64"`
193 - `BetaManagedAgentsPlainTextDocumentSource object`
195194
196 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
197
198195 Plain text document content.
199196
200197 - `data: string`
from line 198
201198
202199 The plain text content.
203200
201 minLength: 1
202
204203 - `media_type: "text/plain"`
205204
206205 MIME type of the text content. Must be "text/plain".
207206
208 - `"text/plain"`
209
210207 - `type: "text"`
211208
212 - `"text"`
209 - `BetaManagedAgentsURLDocumentSource object`
213210
214 - `BetaManagedAgentsURLDocumentSource object { type, url }`
215
216211 Document referenced by URL.
217212
218213 - `type: "url"`
219214
220 - `"url"`
221
222215 - `url: string`
223216
224217 URL of the document to fetch.
225218
226 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
219 minLength: 1
227220
221 - `BetaManagedAgentsFileDocumentSource object`
222
228223 Document referenced by file ID.
229224
230225 - `file_id: string`
from line 226
231226
232227 ID of a previously uploaded file.
233228
229 minLength: 1
230
234231 - `type: "file"`
235232
236 - `"file"`
237
238233 - `type: "document"`
239234
240 - `"document"`
241
242235 - `context: optional string or null`
243236
244237 Additional context about the document for the model.
from line 240
247240
248241 The title of the document.
249242
250 - `BetaManagedAgentsRedactedBlock object { type }`
243 - `BetaManagedAgentsRedactedBlock object`
251244
252245 Placeholder for content withheld by Anthropic model policy.
253246
254247 - `type: "redacted"`
255248
256 - `"redacted"`
257
258249 - `type: "user.message"`
259250
260 - `"user.message"`
251 - `BetaManagedAgentsUserInterruptEventParams object`
261252
262 - `BetaManagedAgentsUserInterruptEventParams object { type, session_thread_id }`
263
264253 Parameters for sending an interrupt to pause the agent.
265254
266255 - `type: "user.interrupt"`
267256
268 - `"user.interrupt"`
269
270257 - `session_thread_id: optional string or null`
271258
272259 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.
273260
274 - `BetaManagedAgentsUserToolConfirmationEventParams object { result, tool_use_id, type, deny_message }`
261 - `BetaManagedAgentsUserToolConfirmationEventParams object`
275262
276263 Parameters for confirming or denying a tool execution request.
277264
from line 274
287274
288275 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
289276
277 minLength: 1, maxLength: 128
278
290279 - `type: "user.tool_confirmation"`
291280
292 - `"user.tool_confirmation"`
293
294281 - `deny_message: optional string or null`
295282
296283 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
297284
298 - `BetaManagedAgentsUserCustomToolResultEventParams object { custom_tool_use_id, type, content, is_error }`
285 maxLength: 10000
299286
287 - `BetaManagedAgentsUserCustomToolResultEventParams object`
288
300289 Parameters for providing the result of a custom tool execution.
301290
302291 - `custom_tool_use_id: string`
from line 292
303292
304293 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
305294
295 minLength: 1, maxLength: 128
296
306297 - `type: "user.custom_tool_result"`
307298
308 - `"user.custom_tool_result"`
309
310299 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
311300
312301 The result content returned by the tool.
313302
314 - `BetaManagedAgentsTextBlock object { text, type }`
303 - `BetaManagedAgentsTextBlock object`
315304
316305 Regular text content.
317306
318 - `BetaManagedAgentsImageBlock object { source, type }`
307 - `BetaManagedAgentsImageBlock object`
319308
320309 Image content specified directly as base64 data or as a reference via a URL.
321310
322 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
311 - `BetaManagedAgentsDocumentBlock object`
323312
324313 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
325314
326 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
315 - `BetaManagedAgentsSearchResultBlock object`
327316
328317 A block containing a web search result.
329318
from line 332
343332
344333 The text content.
345334
335 minLength: 1
336
346337 - `type: "text"`
347338
348 - `"text"`
349
350339 - `source: string`
351340
352341 The URL source of the search result.
353342
343 minLength: 1
344
354345 - `title: string`
355346
356347 The title of the search result.
357348
349 minLength: 1
350
358351 - `type: "search_result"`
359352
360 - `"search_result"`
361
362353 - `is_error: optional boolean or null`
363354
364355 Whether the tool execution resulted in an error.
365356
366 - `BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }`
357 - `BetaManagedAgentsUserDefineOutcomeEventParams object`
367358
368359 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
369360
from line 366
375366
376367 Rubric for grading the quality of an outcome.
377368
378 - `BetaManagedAgentsFileRubricParams object { file_id, type }`
369 - `BetaManagedAgentsFileRubricParams object`
379370
380371 Rubric referenced by a file uploaded via the Files API.
381372
from line 376
385376
386377 - `type: "file"`
387378
388 - `"file"`
379 - `BetaManagedAgentsTextRubricParams object`
389380
390 - `BetaManagedAgentsTextRubricParams object { content, type }`
391
392381 Rubric content provided inline as text.
393382
394383 - `content: string`
from line 384
395384
396385 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
397386
387 maxLength: 262144
388
398389 - `type: "text"`
399390
400 - `"text"`
401
402391 - `type: "user.define_outcome"`
403392
404 - `"user.define_outcome"`
405
406393 - `max_iterations: optional number or null`
407394
408395 Eval→revision cycles before giving up. Default 3, max 20.
409396
410 - `BetaManagedAgentsUserToolResultEventParams object { tool_use_id, type, content, is_error }`
397 format: int32
411398
399 - `BetaManagedAgentsUserToolResultEventParams object`
400
412401 Parameters for 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.
413402
414403 - `tool_use_id: string`
from line 404
415404
416405 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
417406
407 minLength: 1, maxLength: 128
408
418409 - `type: "user.tool_result"`
419410
420 - `"user.tool_result"`
421
422411 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
423412
424413 The result content returned by the tool.
425414
426 - `BetaManagedAgentsTextBlock object { text, type }`
415 - `BetaManagedAgentsTextBlock object`
427416
428417 Regular text content.
429418
430 - `BetaManagedAgentsImageBlock object { source, type }`
419 - `BetaManagedAgentsImageBlock object`
431420
432421 Image content specified directly as base64 data or as a reference via a URL.
433422
434 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
423 - `BetaManagedAgentsDocumentBlock object`
435424
436425 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
437426
438 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
427 - `BetaManagedAgentsSearchResultBlock object`
439428
440429 A block containing a web search result.
441430
from line 432
443432
444433 Whether the tool execution resulted in an error.
445434
446 - `BetaManagedAgentsSystemMessageEventParams object { content, type }`
435 - `BetaManagedAgentsSystemMessageEventParams object`
447436
448437 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.
449438
from line 444
455444
456445 The text content.
457446
447 minLength: 1
448
458449 - `type: "text"`
459450
460 - `"text"`
461
462451 - `type: "system.message"`
463452
464 - `"system.message"`
453## Returns
465454
466### Returns
455- `BetaManagedAgentsSendSessionEvents object`
467456
468- `BetaManagedAgentsSendSessionEvents object { data }`
469
470457 Events that were successfully sent to the session.
471458
472459 - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 4 more`
from line 460
473460
474461 Sent events
475462
476 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
463 - `BetaManagedAgentsUserMessageEvent object`
477464
478465 A user message event in the session conversation.
479466
from line 472
485472
486473 Array of content blocks comprising the user message.
487474
488 - `BetaManagedAgentsTextBlock object { text, type }`
475 - `BetaManagedAgentsTextBlock object`
489476
490477 Regular text content.
491478
from line 480
493480
494481 The text content.
495482
483 minLength: 1
484
496485 - `type: "text"`
497486
498 - `"text"`
487 - `BetaManagedAgentsImageBlock object`
499488
500 - `BetaManagedAgentsImageBlock object { source, type }`
501
502489 Image content specified directly as base64 data or as a reference via a URL.
503490
504491 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 492
505492
506493 Union type for image source variants.
507494
508 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
495 - `BetaManagedAgentsBase64ImageSource object`
509496
510497 Base64-encoded image data.
511498
from line 500
513500
514501 Base64-encoded image data.
515502
503 minLength: 1
504
516505 - `media_type: string`
517506
518507 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
519508
509 minLength: 1
510
520511 - `type: "base64"`
521512
522 - `"base64"`
513 - `BetaManagedAgentsURLImageSource object`
523514
524 - `BetaManagedAgentsURLImageSource object { type, url }`
525
526515 Image referenced by URL.
527516
528517 - `type: "url"`
529518
530 - `"url"`
531
532519 - `url: string`
533520
534521 URL of the image to fetch.
535522
536 - `BetaManagedAgentsFileImageSource object { file_id, type }`
523 minLength: 1
537524
525 - `BetaManagedAgentsFileImageSource object`
526
538527 Image referenced by file ID.
539528
540529 - `file_id: string`
from line 530
541530
542531 ID of a previously uploaded file.
543532
533 minLength: 1
534
544535 - `type: "file"`
545536
546 - `"file"`
547
548537 - `type: "image"`
549538
550 - `"image"`
539 - `BetaManagedAgentsDocumentBlock object`
551540
552 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
553
554541 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
555542
556543 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 544
557544
558545 Union type for document source variants.
559546
560 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
547 - `BetaManagedAgentsBase64DocumentSource object`
561548
562549 Base64-encoded document data.
563550
from line 552
565552
566553 Base64-encoded document data.
567554
555 minLength: 1
556
568557 - `media_type: string`
569558
570559 MIME type of the document (e.g., "application/pdf").
571560
561 minLength: 1
562
572563 - `type: "base64"`
573564
574 - `"base64"`
565 - `BetaManagedAgentsPlainTextDocumentSource object`
575566
576 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
577
578567 Plain text document content.
579568
580569 - `data: string`
from line 570
581570
582571 The plain text content.
583572
573 minLength: 1
574
584575 - `media_type: "text/plain"`
585576
586577 MIME type of the text content. Must be "text/plain".
587578
588 - `"text/plain"`
589
590579 - `type: "text"`
591580
592 - `"text"`
581 - `BetaManagedAgentsURLDocumentSource object`
593582
594 - `BetaManagedAgentsURLDocumentSource object { type, url }`
595
596583 Document referenced by URL.
597584
598585 - `type: "url"`
599586
600 - `"url"`
601
602587 - `url: string`
603588
604589 URL of the document to fetch.
605590
606 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
591 minLength: 1
607592
593 - `BetaManagedAgentsFileDocumentSource object`
594
608595 Document referenced by file ID.
609596
610597 - `file_id: string`
from line 598
611598
612599 ID of a previously uploaded file.
613600
601 minLength: 1
602
614603 - `type: "file"`
615604
616 - `"file"`
617
618605 - `type: "document"`
619606
620 - `"document"`
621
622607 - `context: optional string or null`
623608
624609 Additional context about the document for the model.
from line 612
627612
628613 The title of the document.
629614
630 - `BetaManagedAgentsRedactedBlock object { type }`
615 - `BetaManagedAgentsRedactedBlock object`
631616
632617 Placeholder for content withheld by Anthropic model policy.
633618
634619 - `type: "redacted"`
635620
636 - `"redacted"`
637
638621 - `type: "user.message"`
639622
640 - `"user.message"`
641
642623 - `processed_at: optional string or null`
643624
644625 A timestamp in RFC 3339 format
645626
646 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
627 format: date-time
647628
629 - `BetaManagedAgentsUserInterruptEvent object`
630
648631 An interrupt event that pauses agent execution and returns control to the user.
649632
650633 - `id: string`
from line 636
653636
654637 - `type: "user.interrupt"`
655638
656 - `"user.interrupt"`
657
658639 - `processed_at: optional string or null`
659640
660641 A timestamp in RFC 3339 format
661642
643 format: date-time
644
662645 - `session_thread_id: optional string or null`
663646
664647 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.
665648
666 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
649 - `BetaManagedAgentsUserToolConfirmationEvent object`
667650
668651 A tool confirmation event that approves or denies a pending tool execution.
669652
from line 668
685668
686669 - `type: "user.tool_confirmation"`
687670
688 - `"user.tool_confirmation"`
689
690671 - `deny_message: optional string or null`
691672
692673 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
693674
675 maxLength: 10000
676
694677 - `processed_at: optional string or null`
695678
696679 A timestamp in RFC 3339 format
697680
681 format: date-time
682
698683 - `session_thread_id: optional string or null`
699684
700685 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.
701686
702 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
687 - `BetaManagedAgentsUserCustomToolResultEvent object`
703688
704689 Event sent by the client providing the result of a custom tool execution.
705690
from line 698
713698
714699 - `type: "user.custom_tool_result"`
715700
716 - `"user.custom_tool_result"`
717
718701 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
719702
720703 The result content returned by the tool.
721704
722 - `BetaManagedAgentsTextBlock object { text, type }`
705 - `BetaManagedAgentsTextBlock object`
723706
724707 Regular text content.
725708
726 - `BetaManagedAgentsImageBlock object { source, type }`
709 - `BetaManagedAgentsImageBlock object`
727710
728711 Image content specified directly as base64 data or as a reference via a URL.
729712
730 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
713 - `BetaManagedAgentsDocumentBlock object`
731714
732715 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
733716
734 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
717 - `BetaManagedAgentsSearchResultBlock object`
735718
736719 A block containing a web search result.
737720
from line 734
751734
752735 The text content.
753736
737 minLength: 1
738
754739 - `type: "text"`
755740
756 - `"text"`
757
758741 - `source: string`
759742
760743 The URL source of the search result.
761744
745 minLength: 1
746
762747 - `title: string`
763748
764749 The title of the search result.
765750
751 minLength: 1
752
766753 - `type: "search_result"`
767754
768 - `"search_result"`
769
770755 - `is_error: optional boolean or null`
771756
772757 Whether the tool execution resulted in an error.
from line 760
775760
776761 A timestamp in RFC 3339 format
777762
763 format: date-time
764
778765 - `session_thread_id: optional string or null`
779766
780767 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
781768
782 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
769 - `BetaManagedAgentsUserDefineOutcomeEvent object`
783770
784771 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
785772
from line 782
795782
796783 Evaluate-then-revise cycles before giving up. Default 3, max 20.
797784
785 format: int32
786
798787 - `outcome_id: string`
799788
800789 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 792
803792
804793 A timestamp in RFC 3339 format
805794
795 format: date-time
796
806797 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
807798
808799 Rubric for grading the quality of an outcome.
809800
810 - `BetaManagedAgentsFileRubric object { file_id, type }`
801 - `BetaManagedAgentsFileRubric object`
811802
812803 Rubric referenced by a file uploaded via the Files API.
813804
from line 808
817808
818809 - `type: "file"`
819810
820 - `"file"`
811 - `BetaManagedAgentsTextRubric object`
821812
822 - `BetaManagedAgentsTextRubric object { content, type }`
823
824813 Rubric content provided inline as text.
825814
826815 - `content: string`
from line 818
829818
830819 - `type: "text"`
831820
832 - `"text"`
833
834821 - `type: "user.define_outcome"`
835822
836 - `"user.define_outcome"`
823 - `BetaManagedAgentsUserToolResultEvent object`
837824
838 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
839
840825 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.
841826
842827 - `id: string`
from line 834
849834
850835 - `type: "user.tool_result"`
851836
852 - `"user.tool_result"`
853
854837 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
855838
856839 The result content returned by the tool.
857840
858 - `BetaManagedAgentsTextBlock object { text, type }`
841 - `BetaManagedAgentsTextBlock object`
859842
860843 Regular text content.
861844
862 - `BetaManagedAgentsImageBlock object { source, type }`
845 - `BetaManagedAgentsImageBlock object`
863846
864847 Image content specified directly as base64 data or as a reference via a URL.
865848
866 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
849 - `BetaManagedAgentsDocumentBlock object`
867850
868851 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
869852
870 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
853 - `BetaManagedAgentsSearchResultBlock object`
871854
872855 A block containing a web search result.
873856
from line 862
879862
880863 A timestamp in RFC 3339 format
881864
865 format: date-time
866
882867 - `session_thread_id: optional string or null`
883868
884869 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
885870
886 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
871 - `BetaManagedAgentsSystemMessageEvent object`
887872
888873 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
889874
from line 884
899884
900885 The text content.
901886
887 minLength: 1
888
902889 - `type: "text"`
903890
904 - `"text"`
905
906891 - `type: "system.message"`
907892
908 - `"system.message"`
909
910893 - `processed_at: optional string or null`
911894
912895 A timestamp in RFC 3339 format
913896
914### Example
897 format: date-time
915898
916```http
899## Example
900
901```bash
917902curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
918903 -H 'Content-Type: application/json' \
919904 -H 'anthropic-version: 2023-06-01' \
from line 919
934919 }'
935920```
936921
937#### Response
922### Response (200)
938923
939924```json
940925{
api/beta/sessions/events/stream Changed · +328 / -401 lines
# Stream Events ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## Stream 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 Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/events/stream
4---
5
6## Stream Events
7
8**get** `/v1/sessions/{session_id}/events/stream`
1# Stream Events
2
3**GET** `/v1/sessions/{session_id}/events/stream`
94
105Stream Events
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
16### Query Parameters
11## Query parameters
1712
1813- `event_deltas: optional array of BetaManagedAgentsDeltaType`
1914
from line 18
2318
2419 - `"agent.thinking"`
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- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
107102
108103 Server-sent event in the session stream.
109104
110 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
105 - `BetaManagedAgentsUserMessageEvent object`
111106
112107 A user message event in the session conversation.
113108
from line 114
119114
120115 Array of content blocks comprising the user message.
121116
122 - `BetaManagedAgentsTextBlock object { text, type }`
117 - `BetaManagedAgentsTextBlock object`
123118
124119 Regular text content.
125120
from line 122
127122
128123 The text content.
129124
125 minLength: 1
126
130127 - `type: "text"`
131128
132 - `"text"`
133
134 - `BetaManagedAgentsImageBlock object { source, type }`
129 - `BetaManagedAgentsImageBlock object`
135130
136131 Image content specified directly as base64 data or as a reference via a URL.
137132
from line 134
139134
140135 Union type for image source variants.
141136
142 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
137 - `BetaManagedAgentsBase64ImageSource object`
143138
144139 Base64-encoded image data.
145140
from line 142
147142
148143 Base64-encoded image data.
149144
145 minLength: 1
146
150147 - `media_type: string`
151148
152149 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
153150
151 minLength: 1
152
154153 - `type: "base64"`
155154
156 - `"base64"`
157
158 - `BetaManagedAgentsURLImageSource object { type, url }`
155 - `BetaManagedAgentsURLImageSource object`
159156
160157 Image referenced by URL.
161158
162159 - `type: "url"`
163160
164 - `"url"`
165
166161 - `url: string`
167162
168163 URL of the image to fetch.
169164
170 - `BetaManagedAgentsFileImageSource object { file_id, type }`
165 minLength: 1
166
167 - `BetaManagedAgentsFileImageSource object`
171168
172169 Image referenced by file ID.
173170
from line 172
175172
176173 ID of a previously uploaded file.
177174
175 minLength: 1
176
178177 - `type: "file"`
179178
180 - `"file"`
181
182179 - `type: "image"`
183180
184 - `"image"`
185
186 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
181 - `BetaManagedAgentsDocumentBlock object`
187182
188183 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
189184
from line 186
191186
192187 Union type for document source variants.
193188
194 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
189 - `BetaManagedAgentsBase64DocumentSource object`
195190
196191 Base64-encoded document data.
197192
from line 194
199194
200195 Base64-encoded document data.
201196
197 minLength: 1
198
202199 - `media_type: string`
203200
204201 MIME type of the document (e.g., "application/pdf").
205202
203 minLength: 1
204
206205 - `type: "base64"`
207206
208 - `"base64"`
209
210 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
207 - `BetaManagedAgentsPlainTextDocumentSource object`
211208
212209 Plain text document content.
213210
from line 212
215212
216213 The plain text content.
217214
215 minLength: 1
216
218217 - `media_type: "text/plain"`
219218
220219 MIME type of the text content. Must be "text/plain".
221220
222 - `"text/plain"`
223
224221 - `type: "text"`
225222
226 - `"text"`
227
228 - `BetaManagedAgentsURLDocumentSource object { type, url }`
223 - `BetaManagedAgentsURLDocumentSource object`
229224
230225 Document referenced by URL.
231226
232227 - `type: "url"`
233228
234 - `"url"`
235
236229 - `url: string`
237230
238231 URL of the document to fetch.
239232
240 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
233 minLength: 1
234
235 - `BetaManagedAgentsFileDocumentSource object`
241236
242237 Document referenced by file ID.
243238
from line 240
245240
246241 ID of a previously uploaded file.
247242
243 minLength: 1
244
248245 - `type: "file"`
249246
250 - `"file"`
251
252247 - `type: "document"`
253248
254 - `"document"`
255
256249 - `context: optional string or null`
257250
258251 Additional context about the document for the model.
from line 254
261254
262255 The title of the document.
263256
264 - `BetaManagedAgentsRedactedBlock object { type }`
257 - `BetaManagedAgentsRedactedBlock object`
265258
266259 Placeholder for content withheld by Anthropic model policy.
267260
268261 - `type: "redacted"`
269262
270 - `"redacted"`
271
272263 - `type: "user.message"`
273264
274 - `"user.message"`
275
276265 - `processed_at: optional string or null`
277266
278267 A timestamp in RFC 3339 format
279268
280 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
269 format: date-time
270
271 - `BetaManagedAgentsUserInterruptEvent object`
281272
282273 An interrupt event that pauses agent execution and returns control to the user.
283274
from line 278
287278
288279 - `type: "user.interrupt"`
289280
290 - `"user.interrupt"`
291
292281 - `processed_at: optional string or null`
293282
294283 A timestamp in RFC 3339 format
295284
285 format: date-time
286
296287 - `session_thread_id: optional string or null`
297288
298289 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.
299290
300 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
291 - `BetaManagedAgentsUserToolConfirmationEvent object`
301292
302293 A tool confirmation event that approves or denies a pending tool execution.
303294
from line 310
319310
320311 - `type: "user.tool_confirmation"`
321312
322 - `"user.tool_confirmation"`
323
324313 - `deny_message: optional string or null`
325314
326315 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
327316
317 maxLength: 10000
318
328319 - `processed_at: optional string or null`
329320
330321 A timestamp in RFC 3339 format
331322
323 format: date-time
324
332325 - `session_thread_id: optional string or null`
333326
334327 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.
335328
336 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
329 - `BetaManagedAgentsUserCustomToolResultEvent object`
337330
338331 Event sent by the client providing the result of a custom tool execution.
339332
from line 340
347340
348341 - `type: "user.custom_tool_result"`
349342
350 - `"user.custom_tool_result"`
351
352343 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
353344
354345 The result content returned by the tool.
355346
356 - `BetaManagedAgentsTextBlock object { text, type }`
347 - `BetaManagedAgentsTextBlock object`
357348
358349 Regular text content.
359350
360 - `BetaManagedAgentsImageBlock object { source, type }`
351 - `BetaManagedAgentsImageBlock object`
361352
362353 Image content specified directly as base64 data or as a reference via a URL.
363354
364 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
355 - `BetaManagedAgentsDocumentBlock object`
365356
366357 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
367358
368 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
359 - `BetaManagedAgentsSearchResultBlock object`
369360
370361 A block containing a web search result.
371362
from line 376
385376
386377 The text content.
387378
379 minLength: 1
380
388381 - `type: "text"`
389382
390 - `"text"`
391
392383 - `source: string`
393384
394385 The URL source of the search result.
395386
387 minLength: 1
388
396389 - `title: string`
397390
398391 The title of the search result.
399392
393 minLength: 1
394
400395 - `type: "search_result"`
401396
402 - `"search_result"`
403
404397 - `is_error: optional boolean or null`
405398
406399 Whether the tool execution resulted in an error.
from line 402
409402
410403 A timestamp in RFC 3339 format
411404
405 format: date-time
406
412407 - `session_thread_id: optional string or null`
413408
414409 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
415410
416 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
411 - `BetaManagedAgentsAgentCustomToolUseEvent object`
417412
418413 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.
419414
from line 428
433428
434429 A timestamp in RFC 3339 format
435430
431 format: date-time
432
436433 - `type: "agent.custom_tool_use"`
437434
438 - `"agent.custom_tool_use"`
439
440435 - `session_thread_id: optional string or null`
441436
442437 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.
443438
444 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
439 - `BetaManagedAgentsAgentMessageEvent object`
445440
446441 An agent response event in the session conversation.
447442
from line 448
453448
454449 Array of text blocks comprising the agent response.
455450
456 - `BetaManagedAgentsTextBlock object { text, type }`
451 - `BetaManagedAgentsTextBlock object`
457452
458453 Regular text content.
459454
460 - `BetaManagedAgentsRedactedBlock object { type }`
455 - `BetaManagedAgentsRedactedBlock object`
461456
462457 Placeholder for content withheld by Anthropic model policy.
463458
from line 460
465460
466461 A timestamp in RFC 3339 format
467462
463 format: date-time
464
468465 - `type: "agent.message"`
469466
470 - `"agent.message"`
471
472 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
467 - `BetaManagedAgentsAgentThinkingEvent object`
473468
474469 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
475470
from line 476
481476
482477 A timestamp in RFC 3339 format
483478
479 format: date-time
480
484481 - `type: "agent.thinking"`
485482
486 - `"agent.thinking"`
487
488 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
483 - `BetaManagedAgentsAgentMCPToolUseEvent object`
489484
490485 Event emitted when the agent invokes a tool provided by an MCP server.
491486
from line 504
509504
510505 A timestamp in RFC 3339 format
511506
507 format: date-time
508
512509 - `type: "agent.mcp_tool_use"`
513510
514 - `"agent.mcp_tool_use"`
515
516511 - `evaluated_permission: optional "allow" or "ask" or "deny"`
517512
518513 AgentEvaluatedPermission enum
from line 522
527522
528523 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.
529524
530 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
525 - `BetaManagedAgentsAgentMCPToolResultEvent object`
531526
532527 Event representing the result of an MCP tool execution.
533528
from line 538
543538
544539 A timestamp in RFC 3339 format
545540
541 format: date-time
542
546543 - `type: "agent.mcp_tool_result"`
547544
548 - `"agent.mcp_tool_result"`
549
550545 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
551546
552547 The result content returned by the tool.
553548
554 - `BetaManagedAgentsTextBlock object { text, type }`
549 - `BetaManagedAgentsTextBlock object`
555550
556551 Regular text content.
557552
558 - `BetaManagedAgentsImageBlock object { source, type }`
553 - `BetaManagedAgentsImageBlock object`
559554
560555 Image content specified directly as base64 data or as a reference via a URL.
561556
562 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
557 - `BetaManagedAgentsDocumentBlock object`
563558
564559 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
565560
566 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
561 - `BetaManagedAgentsSearchResultBlock object`
567562
568563 A block containing a web search result.
569564
from line 566
571566
572567 Whether the tool execution resulted in an error.
573568
574 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
569 - `BetaManagedAgentsAgentToolUseEvent object`
575570
576571 Event emitted when the agent invokes a built-in agent tool.
577572
from line 586
591586
592587 A timestamp in RFC 3339 format
593588
589 format: date-time
590
594591 - `type: "agent.tool_use"`
595592
596 - `"agent.tool_use"`
597
598593 - `evaluated_permission: optional "allow" or "ask" or "deny"`
599594
600595 AgentEvaluatedPermission enum
from line 604
609604
610605 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.
611606
612 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
607 - `BetaManagedAgentsAgentToolResultEvent object`
613608
614609 Event representing the result of an agent tool execution.
615610
from line 616
621616
622617 A timestamp in RFC 3339 format
623618
619 format: date-time
620
624621 - `tool_use_id: string`
625622
626623 The id of the `agent.tool_use` event this result corresponds to.
627624
628625 - `type: "agent.tool_result"`
629626
630 - `"agent.tool_result"`
631
632627 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
633628
634629 The result content returned by the tool.
635630
636 - `BetaManagedAgentsTextBlock object { text, type }`
631 - `BetaManagedAgentsTextBlock object`
637632
638633 Regular text content.
639634
640 - `BetaManagedAgentsImageBlock object { source, type }`
635 - `BetaManagedAgentsImageBlock object`
641636
642637 Image content specified directly as base64 data or as a reference via a URL.
643638
644 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
639 - `BetaManagedAgentsDocumentBlock object`
645640
646641 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
647642
648 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
643 - `BetaManagedAgentsSearchResultBlock object`
649644
650645 A block containing a web search result.
651646
from line 648
653648
654649 Whether the tool execution resulted in an error.
655650
656 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
651 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
657652
658653 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
659654
from line 660
665660
666661 Message content blocks.
667662
668 - `BetaManagedAgentsTextBlock object { text, type }`
663 - `BetaManagedAgentsTextBlock object`
669664
670665 Regular text content.
671666
672 - `BetaManagedAgentsImageBlock object { source, type }`
667 - `BetaManagedAgentsImageBlock object`
673668
674669 Image content specified directly as base64 data or as a reference via a URL.
675670
676 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
671 - `BetaManagedAgentsDocumentBlock object`
677672
678673 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
679674
680 - `BetaManagedAgentsRedactedBlock object { type }`
675 - `BetaManagedAgentsRedactedBlock object`
681676
682677 Placeholder for content withheld by Anthropic model policy.
683678
from line 684
689684
690685 A timestamp in RFC 3339 format
691686
687 format: date-time
688
692689 - `type: "agent.thread_message_received"`
693690
694 - `"agent.thread_message_received"`
695
696691 - `from_agent_name: optional string or null`
697692
698693 Name of the callable agent this message came from. Absent when received from the primary agent.
699694
700 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
695 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
701696
702697 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
703698
from line 704
709704
710705 Message content blocks.
711706
712 - `BetaManagedAgentsTextBlock object { text, type }`
707 - `BetaManagedAgentsTextBlock object`
713708
714709 Regular text content.
715710
716 - `BetaManagedAgentsImageBlock object { source, type }`
711 - `BetaManagedAgentsImageBlock object`
717712
718713 Image content specified directly as base64 data or as a reference via a URL.
719714
720 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
715 - `BetaManagedAgentsDocumentBlock object`
721716
722717 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
723718
724 - `BetaManagedAgentsRedactedBlock object { type }`
719 - `BetaManagedAgentsRedactedBlock object`
725720
726721 Placeholder for content withheld by Anthropic model policy.
727722
from line 724
729724
730725 A timestamp in RFC 3339 format
731726
727 format: date-time
728
732729 - `to_session_thread_id: string`
733730
734731 Public `sthr_` ID of the thread the message was sent to.
735732
736733 - `type: "agent.thread_message_sent"`
737734
738 - `"agent.thread_message_sent"`
739
740735 - `to_agent_name: optional string or null`
741736
742737 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
743738
744 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
739 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
745740
746741 Indicates that context compaction (summarization) occurred during the session.
747742
from line 748
753748
754749 A timestamp in RFC 3339 format
755750
751 format: date-time
752
756753 - `type: "agent.thread_context_compacted"`
757754
758 - `"agent.thread_context_compacted"`
759
760 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
755 - `BetaManagedAgentsSessionErrorEvent object`
761756
762757 An error event indicating a problem occurred during session execution.
763758
from line 764
769764
770765 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.
771766
772 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
767 - `BetaManagedAgentsUnknownError object`
773768
774769 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.
775770
from line 776
781776
782777 What the client should do next in response to this error.
783778
784 - `BetaManagedAgentsRetryStatusRetrying object { type }`
779 - `BetaManagedAgentsRetryStatusRetrying object`
785780
786781 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.
787782
788783 - `type: "retrying"`
789784
790 - `"retrying"`
791
792 - `BetaManagedAgentsRetryStatusExhausted object { type }`
785 - `BetaManagedAgentsRetryStatusExhausted object`
793786
794787 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
795788
796789 - `type: "exhausted"`
797790
798 - `"exhausted"`
799
800 - `BetaManagedAgentsRetryStatusTerminal object { type }`
791 - `BetaManagedAgentsRetryStatusTerminal object`
801792
802793 The session encountered a terminal error and will transition to `terminated` state.
803794
804795 - `type: "terminal"`
805796
806 - `"terminal"`
807
808797 - `type: "unknown_error"`
809798
810 - `"unknown_error"`
811
812 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
799 - `BetaManagedAgentsModelOverloadedError object`
813800
814801 The model is currently overloaded. Emitted after automatic retries are exhausted.
815802
from line 808
821808
822809 What the client should do next in response to this error.
823810
824 - `BetaManagedAgentsRetryStatusRetrying object { type }`
811 - `BetaManagedAgentsRetryStatusRetrying object`
825812
826813 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.
827814
828 - `BetaManagedAgentsRetryStatusExhausted object { type }`
815 - `BetaManagedAgentsRetryStatusExhausted object`
829816
830817 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
831818
832 - `BetaManagedAgentsRetryStatusTerminal object { type }`
819 - `BetaManagedAgentsRetryStatusTerminal object`
833820
834821 The session encountered a terminal error and will transition to `terminated` state.
835822
836823 - `type: "model_overloaded_error"`
837824
838 - `"model_overloaded_error"`
839
840 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
825 - `BetaManagedAgentsModelRateLimitedError object`
841826
842827 The model request was rate-limited.
843828
from line 834
849834
850835 What the client should do next in response to this error.
851836
852 - `BetaManagedAgentsRetryStatusRetrying object { type }`
837 - `BetaManagedAgentsRetryStatusRetrying object`
853838
854839 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.
855840
856 - `BetaManagedAgentsRetryStatusExhausted object { type }`
841 - `BetaManagedAgentsRetryStatusExhausted object`
857842
858843 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
859844
860 - `BetaManagedAgentsRetryStatusTerminal object { type }`
845 - `BetaManagedAgentsRetryStatusTerminal object`
861846
862847 The session encountered a terminal error and will transition to `terminated` state.
863848
864849 - `type: "model_rate_limited_error"`
865850
866 - `"model_rate_limited_error"`
867
868 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
851 - `BetaManagedAgentsModelRequestFailedError object`
869852
870853 A model request failed for a reason other than overload or rate-limiting.
871854
from line 860
877860
878861 What the client should do next in response to this error.
879862
880 - `BetaManagedAgentsRetryStatusRetrying object { type }`
863 - `BetaManagedAgentsRetryStatusRetrying object`
881864
882865 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.
883866
884 - `BetaManagedAgentsRetryStatusExhausted object { type }`
867 - `BetaManagedAgentsRetryStatusExhausted object`
885868
886869 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
887870
888 - `BetaManagedAgentsRetryStatusTerminal object { type }`
871 - `BetaManagedAgentsRetryStatusTerminal object`
889872
890873 The session encountered a terminal error and will transition to `terminated` state.
891874
892875 - `type: "model_request_failed_error"`
893876
894 - `"model_request_failed_error"`
895
896 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
877 - `BetaManagedAgentsMCPConnectionFailedError object`
897878
898879 Failed to connect to an MCP server.
899880
from line 890
909890
910891 What the client should do next in response to this error.
911892
912 - `BetaManagedAgentsRetryStatusRetrying object { type }`
893 - `BetaManagedAgentsRetryStatusRetrying object`
913894
914895 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.
915896
916 - `BetaManagedAgentsRetryStatusExhausted object { type }`
897 - `BetaManagedAgentsRetryStatusExhausted object`
917898
918899 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
919900
920 - `BetaManagedAgentsRetryStatusTerminal object { type }`
901 - `BetaManagedAgentsRetryStatusTerminal object`
921902
922903 The session encountered a terminal error and will transition to `terminated` state.
923904
924905 - `type: "mcp_connection_failed_error"`
925906
926 - `"mcp_connection_failed_error"`
927
928 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
907 - `BetaManagedAgentsMCPAuthenticationFailedError object`
929908
930909 Authentication to an MCP server failed.
931910
from line 920
941920
942921 What the client should do next in response to this error.
943922
944 - `BetaManagedAgentsRetryStatusRetrying object { type }`
923 - `BetaManagedAgentsRetryStatusRetrying object`
945924
946925 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.
947926
948 - `BetaManagedAgentsRetryStatusExhausted object { type }`
927 - `BetaManagedAgentsRetryStatusExhausted object`
949928
950929 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
951930
952 - `BetaManagedAgentsRetryStatusTerminal object { type }`
931 - `BetaManagedAgentsRetryStatusTerminal object`
953932
954933 The session encountered a terminal error and will transition to `terminated` state.
955934
956935 - `type: "mcp_authentication_failed_error"`
957936
958 - `"mcp_authentication_failed_error"`
959
960 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
937 - `BetaManagedAgentsBillingError object`
961938
962939 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.
963940
from line 946
969946
970947 What the client should do next in response to this error.
971948
972 - `BetaManagedAgentsRetryStatusRetrying object { type }`
949 - `BetaManagedAgentsRetryStatusRetrying object`
973950
974951 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.
975952
976 - `BetaManagedAgentsRetryStatusExhausted object { type }`
953 - `BetaManagedAgentsRetryStatusExhausted object`
977954
978955 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
979956
980 - `BetaManagedAgentsRetryStatusTerminal object { type }`
957 - `BetaManagedAgentsRetryStatusTerminal object`
981958
982959 The session encountered a terminal error and will transition to `terminated` state.
983960
984961 - `type: "billing_error"`
985962
986 - `"billing_error"`
987
988 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
963 - `BetaManagedAgentsCredentialHostUnreachableError object`
989964
990965 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
991966
from line 976
1001976
1002977 What the client should do next in response to this error.
1003978
1004 - `BetaManagedAgentsRetryStatusRetrying object { type }`
979 - `BetaManagedAgentsRetryStatusRetrying object`
1005980
1006981 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.
1007982
1008 - `BetaManagedAgentsRetryStatusExhausted object { type }`
983 - `BetaManagedAgentsRetryStatusExhausted object`
1009984
1010985 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1011986
1012 - `BetaManagedAgentsRetryStatusTerminal object { type }`
987 - `BetaManagedAgentsRetryStatusTerminal object`
1013988
1014989 The session encountered a terminal error and will transition to `terminated` state.
1015990
1016991 - `type: "credential_host_unreachable_error"`
1017992
1018 - `"credential_host_unreachable_error"`
1019
1020993 - `vault_id: string`
1021994
1022995 ID of the vault containing the affected credential.
from line 998
1025998
1026999 A timestamp in RFC 3339 format
10271000
1001 format: date-time
1002
10281003 - `type: "session.error"`
10291004
1030 - `"session.error"`
1031
1032 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
1005 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
10331006
10341007 Indicates the session is recovering from an error state and is rescheduled for execution.
10351008
from line 1014
10411014
10421015 A timestamp in RFC 3339 format
10431016
1017 format: date-time
1018
10441019 - `type: "session.status_rescheduled"`
10451020
1046 - `"session.status_rescheduled"`
1047
1048 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
1021 - `BetaManagedAgentsSessionStatusRunningEvent object`
10491022
10501023 Indicates the session is actively running and the agent is working.
10511024
from line 1030
10571030
10581031 A timestamp in RFC 3339 format
10591032
1033 format: date-time
1034
10601035 - `type: "session.status_running"`
10611036
1062 - `"session.status_running"`
1063
1064 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
1037 - `BetaManagedAgentsSessionStatusIdleEvent object`
10651038
10661039 Indicates the agent has paused and is awaiting user input.
10671040
from line 1046
10731046
10741047 A timestamp in RFC 3339 format
10751048
1049 format: date-time
1050
10761051 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
10771052
10781053 The agent completed its turn naturally and is ready for the next user message.
10791054
1080 - `BetaManagedAgentsSessionEndTurn object { type }`
1055 - `BetaManagedAgentsSessionEndTurn object`
10811056
10821057 The agent completed its turn naturally and is ready for the next user message.
10831058
10841059 - `type: "end_turn"`
10851060
1086 - `"end_turn"`
1087
1088 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1061 - `BetaManagedAgentsSessionRequiresAction object`
10891062
10901063 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.
10911064
from line 1068
10951068
10961069 - `type: "requires_action"`
10971070
1098 - `"requires_action"`
1099
1100 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1071 - `BetaManagedAgentsSessionRetriesExhausted object`
11011072
11021073 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
11031074
11041075 - `type: "retries_exhausted"`
11051076
1106 - `"retries_exhausted"`
1107
1108 - `BetaManagedAgentsSessionBudgetReached object { type }`
1077 - `BetaManagedAgentsSessionBudgetReached object`
11091078
11101079 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.
11111080
11121081 - `type: "budget_reached"`
11131082
1114 - `"budget_reached"`
1115
11161083 - `type: "session.status_idle"`
11171084
1118 - `"session.status_idle"`
1119
1120 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
1085 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
11211086
11221087 Indicates the session has terminated, either due to an error or completion.
11231088
from line 1094
11291094
11301095 A timestamp in RFC 3339 format
11311096
1097 format: date-time
1098
11321099 - `type: "session.status_terminated"`
11331100
1134 - `"session.status_terminated"`
1135
1136 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
1101 - `BetaManagedAgentsSessionThreadCreatedEvent object`
11371102
11381103 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.
11391104
from line 1114
11491114
11501115 A timestamp in RFC 3339 format
11511116
1117 format: date-time
1118
11521119 - `session_thread_id: string`
11531120
11541121 Public `sthr_` ID of the newly created thread.
11551122
11561123 - `type: "session.thread_created"`
11571124
1158 - `"session.thread_created"`
1159
1160 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
1125 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
11611126
11621127 Emitted when an outcome evaluation cycle begins.
11631128
from line 1134
11691134
11701135 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
11711136
1137 format: int32
1138
11721139 - `outcome_id: string`
11731140
11741141 The `outc_` ID of the outcome being evaluated.
from line 1144
11771144
11781145 A timestamp in RFC 3339 format
11791146
1147 format: date-time
1148
11801149 - `type: "span.outcome_evaluation_start"`
11811150
1182 - `"span.outcome_evaluation_start"`
1183
1184 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
1151 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
11851152
11861153 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.
11871154
from line 1164
11971164
11981165 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
11991166
1167 format: int32
1168
12001169 - `outcome_evaluation_start_id: string`
12011170
12021171 The id of the corresponding `span.outcome_evaluation_start` event.
from line 1178
12091178
12101179 A timestamp in RFC 3339 format
12111180
1181 format: date-time
1182
12121183 - `result: string`
12131184
12141185 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.
12151186
12161187 - `type: "span.outcome_evaluation_end"`
12171188
1218 - `"span.outcome_evaluation_end"`
1219
12201189 - `usage: BetaManagedAgentsSpanModelUsage`
12211190
12221191 Token usage for a single model request.
from line 1194
12251194
12261195 Tokens used to create prompt cache in this request.
12271196
1197 format: int32
1198
12281199 - `cache_read_input_tokens: number`
12291200
12301201 Tokens read from prompt cache in this request.
12311202
1203 format: int32
1204
12321205 - `input_tokens: number`
12331206
12341207 Input tokens consumed by this request.
12351208
1209 format: int32
1210
12361211 - `output_tokens: number`
12371212
12381213 Output tokens generated by this request.
12391214
1215 format: int32
1216
12401217 - `speed: optional "standard" or "fast" or null`
12411218
12421219 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 1222
12451222
12461223 - `"fast"`
12471224
1248 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
1225 - `BetaManagedAgentsSpanModelRequestStartEvent object`
12491226
12501227 Emitted when a model request is initiated by the agent.
12511228
from line 1234
12571234
12581235 A timestamp in RFC 3339 format
12591236
1237 format: date-time
1238
12601239 - `type: "span.model_request_start"`
12611240
1262 - `"span.model_request_start"`
1263
1264 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
1241 - `BetaManagedAgentsSpanModelRequestEndEvent object`
12651242
12661243 Emitted when a model request completes.
12671244
from line 1262
12851262
12861263 A timestamp in RFC 3339 format
12871264
1265 format: date-time
1266
12881267 - `type: "span.model_request_end"`
12891268
1290 - `"span.model_request_end"`
1291
1292 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
1269 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
12931270
12941271 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.
12951272
from line 1278
13011278
13021279 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
13031280
1281 format: int32
1282
13041283 - `outcome_id: string`
13051284
13061285 The `outc_` ID of the outcome being evaluated.
from line 1288
13091288
13101289 A timestamp in RFC 3339 format
13111290
1291 format: date-time
1292
13121293 - `type: "span.outcome_evaluation_ongoing"`
13131294
1314 - `"span.outcome_evaluation_ongoing"`
1315
1316 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
1295 - `BetaManagedAgentsUserDefineOutcomeEvent object`
13171296
13181297 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
13191298
from line 1308
13291308
13301309 Evaluate-then-revise cycles before giving up. Default 3, max 20.
13311310
1311 format: int32
1312
13321313 - `outcome_id: string`
13331314
13341315 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1318
13371318
13381319 A timestamp in RFC 3339 format
13391320
1321 format: date-time
1322
13401323 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
13411324
13421325 Rubric for grading the quality of an outcome.
13431326
1344 - `BetaManagedAgentsFileRubric object { file_id, type }`
1327 - `BetaManagedAgentsFileRubric object`
13451328
13461329 Rubric referenced by a file uploaded via the Files API.
13471330
from line 1334
13511334
13521335 - `type: "file"`
13531336
1354 - `"file"`
1355
1356 - `BetaManagedAgentsTextRubric object { content, type }`
1337 - `BetaManagedAgentsTextRubric object`
13571338
13581339 Rubric content provided inline as text.
13591340
from line 1344
13631344
13641345 - `type: "text"`
13651346
1366 - `"text"`
1367
13681347 - `type: "user.define_outcome"`
13691348
1370 - `"user.define_outcome"`
1371
1372 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
1349 - `BetaManagedAgentsSessionDeletedEvent object`
13731350
13741351 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
13751352
from line 1358
13811358
13821359 A timestamp in RFC 3339 format
13831360
1361 format: date-time
1362
13841363 - `type: "session.deleted"`
13851364
1386 - `"session.deleted"`
1387
1388 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
1365 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
13891366
13901367 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
13911368
from line 1378
14011378
14021379 A timestamp in RFC 3339 format
14031380
1381 format: date-time
1382
14041383 - `session_thread_id: string`
14051384
14061385 Public sthr_ ID of the thread that started running.
14071386
14081387 - `type: "session.thread_status_running"`
14091388
1410 - `"session.thread_status_running"`
1411
1412 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
1389 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
14131390
14141391 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.
14151392
from line 1402
14251402
14261403 A timestamp in RFC 3339 format
14271404
1405 format: date-time
1406
14281407 - `session_thread_id: string`
14291408
14301409 Public sthr_ ID of the thread that went idle.
from line 1412
14331412
14341413 The agent completed its turn naturally and is ready for the next user message.
14351414
1436 - `BetaManagedAgentsSessionEndTurn object { type }`
1415 - `BetaManagedAgentsSessionEndTurn object`
14371416
14381417 The agent completed its turn naturally and is ready for the next user message.
14391418
1440 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1419 - `BetaManagedAgentsSessionRequiresAction object`
14411420
14421421 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.
14431422
1444 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1423 - `BetaManagedAgentsSessionRetriesExhausted object`
14451424
14461425 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
14471426
1448 - `BetaManagedAgentsSessionBudgetReached object { type }`
1427 - `BetaManagedAgentsSessionBudgetReached object`
14491428
14501429 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.
14511430
14521431 - `type: "session.thread_status_idle"`
14531432
1454 - `"session.thread_status_idle"`
1455
1456 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
1433 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
14571434
14581435 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.
14591436
from line 1446
14691446
14701447 A timestamp in RFC 3339 format
14711448
1449 format: date-time
1450
14721451 - `session_thread_id: string`
14731452
14741453 Public sthr_ ID of the thread that terminated.
14751454
14761455 - `type: "session.thread_status_terminated"`
14771456
1478 - `"session.thread_status_terminated"`
1479
1480 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
1457 - `BetaManagedAgentsUserToolResultEvent object`
14811458
14821459 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.
14831460
from line 1468
14911468
14921469 - `type: "user.tool_result"`
14931470
1494 - `"user.tool_result"`
1495
14961471 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
14971472
14981473 The result content returned by the tool.
14991474
1500 - `BetaManagedAgentsTextBlock object { text, type }`
1475 - `BetaManagedAgentsTextBlock object`
15011476
15021477 Regular text content.
15031478
1504 - `BetaManagedAgentsImageBlock object { source, type }`
1479 - `BetaManagedAgentsImageBlock object`
15051480
15061481 Image content specified directly as base64 data or as a reference via a URL.
15071482
1508 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1483 - `BetaManagedAgentsDocumentBlock object`
15091484
15101485 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
15111486
1512 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
1487 - `BetaManagedAgentsSearchResultBlock object`
15131488
15141489 A block containing a web search result.
15151490
from line 1496
15211496
15221497 A timestamp in RFC 3339 format
15231498
1499 format: date-time
1500
15241501 - `session_thread_id: optional string or null`
15251502
15261503 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
15271504
1528 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
1505 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
15291506
15301507 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.
15311508
from line 1518
15411518
15421519 A timestamp in RFC 3339 format
15431520
1521 format: date-time
1522
15441523 - `session_thread_id: string`
15451524
15461525 Public sthr_ ID of the thread that is retrying.
15471526
15481527 - `type: "session.thread_status_rescheduled"`
15491528
1550 - `"session.thread_status_rescheduled"`
1551
1552 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
1529 - `BetaManagedAgentsSessionUpdatedEvent object`
15531530
15541531 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.
15551532
from line 1538
15611538
15621539 A timestamp in RFC 3339 format
15631540
1541 format: date-time
1542
15641543 - `type: "session.updated"`
15651544
1566 - `"session.updated"`
1567
15681545 - `agent: optional BetaManagedAgentsSessionAgent or null`
15691546
15701547 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1556
15791556
15801557 - `type: "url"`
15811558
1582 - `"url"`
1583
15841559 - `url: string`
15851560
15861561 - `model: BetaManagedAgentsModelConfig`
from line 1632
16571632
16581633 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16591634
1660 - `BetaManagedAgentsEffortLow object { type }`
1635 - `BetaManagedAgentsEffortLow object`
16611636
16621637 Low effort. Favors latency over reasoning depth.
16631638
16641639 - `type: "low"`
16651640
1666 - `"low"`
1667
1668 - `BetaManagedAgentsEffortMedium object { type }`
1641 - `BetaManagedAgentsEffortMedium object`
16691642
16701643 Medium effort. Balances latency and reasoning depth.
16711644
16721645 - `type: "medium"`
16731646
1674 - `"medium"`
1675
1676 - `BetaManagedAgentsEffortHigh object { type }`
1647 - `BetaManagedAgentsEffortHigh object`
16771648
16781649 High effort. Favors reasoning depth.
16791650
16801651 - `type: "high"`
16811652
1682 - `"high"`
1683
1684 - `BetaManagedAgentsEffortXhigh object { type }`
1653 - `BetaManagedAgentsEffortXhigh object`
16851654
16861655 Extra-high effort. Not all models accept this level.
16871656
16881657 - `type: "xhigh"`
16891658
1690 - `"xhigh"`
1691
1692 - `BetaManagedAgentsEffortMax object { type }`
1659 - `BetaManagedAgentsEffortMax object`
16931660
16941661 Maximum effort. Favors reasoning depth over latency.
16951662
16961663 - `type: "max"`
16971664
1698 - `"max"`
1699
17001665 - `inference_geo: optional string`
17011666
17021667 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1682
17171682
17181683 Full `agent` definitions the coordinator may spawn as session threads.
17191684
1720 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1685 - `BetaManagedAgentsSessionThreadAgent object`
17211686
17221687 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`.
17231688
from line 1706
17411706
17421707 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17431708
1744 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1709 - `BetaManagedAgentsAnthropicSkill object`
17451710
17461711 A resolved Anthropic-managed skill.
17471712
from line 1714
17491714
17501715 - `type: "anthropic"`
17511716
1752 - `"anthropic"`
1753
17541717 - `version: string`
17551718
1756 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1719 - `BetaManagedAgentsCustomSkill object`
17571720
17581721 A resolved user-created custom skill.
17591722
from line 1724
17611724
17621725 - `type: "custom"`
17631726
1764 - `"custom"`
1765
17661727 - `version: string`
17671728
17681729 - `system: string or null`
17691730
17701731 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17711732
1772 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1733 - `BetaManagedAgentsAgentToolset20260401 object`
17731734
17741735 - `configs: array of BetaManagedAgentsAgentToolConfig`
17751736
1776 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1737 - `BetaManagedAgentsBashToolConfig object`
17771738
17781739 Configuration for the bash tool.
17791740
from line 1742
17811742
17821743 - `name: "bash"`
17831744
1784 - `"bash"`
1785
17861745 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
17871746
17881747 Permission policy for tool execution.
17891748
1790 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1749 - `BetaManagedAgentsAlwaysAllowPolicy object`
17911750
17921751 Tool calls are automatically approved without user confirmation.
17931752
17941753 - `type: "always_allow"`
17951754
1796 - `"always_allow"`
1797
1798 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1755 - `BetaManagedAgentsAlwaysAskPolicy object`
17991756
18001757 Tool calls require user confirmation before execution.
18011758
18021759 - `type: "always_ask"`
18031760
1804 - `"always_ask"`
1805
18061761 - `type: "bash"`
18071762
1808 - `"bash"`
1809
1810 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1763 - `BetaManagedAgentsEditToolConfig object`
18111764
18121765 Configuration for the edit tool.
18131766
from line 1768
18151768
18161769 - `name: "edit"`
18171770
1818 - `"edit"`
1819
18201771 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18211772
18221773 Permission policy for tool execution.
18231774
1824 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1775 - `BetaManagedAgentsAlwaysAllowPolicy object`
18251776
18261777 Tool calls are automatically approved without user confirmation.
18271778
1828 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1779 - `BetaManagedAgentsAlwaysAskPolicy object`
18291780
18301781 Tool calls require user confirmation before execution.
18311782
18321783 - `type: "edit"`
18331784
1834 - `"edit"`
1835
1836 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1785 - `BetaManagedAgentsReadToolConfig object`
18371786
18381787 Configuration for the read tool.
18391788
from line 1790
18411790
18421791 - `name: "read"`
18431792
1844 - `"read"`
1845
18461793 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18471794
18481795 Permission policy for tool execution.
18491796
1850 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1797 - `BetaManagedAgentsAlwaysAllowPolicy object`
18511798
18521799 Tool calls are automatically approved without user confirmation.
18531800
1854 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1801 - `BetaManagedAgentsAlwaysAskPolicy object`
18551802
18561803 Tool calls require user confirmation before execution.
18571804
18581805 - `type: "read"`
18591806
1860 - `"read"`
1861
1862 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1807 - `BetaManagedAgentsWriteToolConfig object`
18631808
18641809 Configuration for the write tool.
18651810
from line 1812
18671812
18681813 - `name: "write"`
18691814
1870 - `"write"`
1871
18721815 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18731816
18741817 Permission policy for tool execution.
18751818
1876 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1819 - `BetaManagedAgentsAlwaysAllowPolicy object`
18771820
18781821 Tool calls are automatically approved without user confirmation.
18791822
1880 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1823 - `BetaManagedAgentsAlwaysAskPolicy object`
18811824
18821825 Tool calls require user confirmation before execution.
18831826
18841827 - `type: "write"`
18851828
1886 - `"write"`
1887
1888 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1829 - `BetaManagedAgentsGlobToolConfig object`
18891830
18901831 Configuration for the glob tool.
18911832
from line 1834
18931834
18941835 - `name: "glob"`
18951836
1896 - `"glob"`
1897
18981837 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18991838
19001839 Permission policy for tool execution.
19011840
1902 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1841 - `BetaManagedAgentsAlwaysAllowPolicy object`
19031842
19041843 Tool calls are automatically approved without user confirmation.
19051844
1906 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1845 - `BetaManagedAgentsAlwaysAskPolicy object`
19071846
19081847 Tool calls require user confirmation before execution.
19091848
19101849 - `type: "glob"`
19111850
1912 - `"glob"`
1913
1914 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1851 - `BetaManagedAgentsGrepToolConfig object`
19151852
19161853 Configuration for the grep tool.
19171854
from line 1856
19191856
19201857 - `name: "grep"`
19211858
1922 - `"grep"`
1923
19241859 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19251860
19261861 Permission policy for tool execution.
19271862
1928 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1863 - `BetaManagedAgentsAlwaysAllowPolicy object`
19291864
19301865 Tool calls are automatically approved without user confirmation.
19311866
1932 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1867 - `BetaManagedAgentsAlwaysAskPolicy object`
19331868
19341869 Tool calls require user confirmation before execution.
19351870
19361871 - `type: "grep"`
19371872
1938 - `"grep"`
1939
1940 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1873 - `BetaManagedAgentsWebFetchToolConfig object`
19411874
19421875 Configuration for the web_fetch tool.
19431876
from line 1878
19451878
19461879 - `name: "web_fetch"`
19471880
1948 - `"web_fetch"`
1949
19501881 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19511882
19521883 Permission policy for tool execution.
19531884
1954 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1885 - `BetaManagedAgentsAlwaysAllowPolicy object`
19551886
19561887 Tool calls are automatically approved without user confirmation.
19571888
1958 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1889 - `BetaManagedAgentsAlwaysAskPolicy object`
19591890
19601891 Tool calls require user confirmation before execution.
19611892
19621893 - `type: "web_fetch"`
19631894
1964 - `"web_fetch"`
1965
19661895 - `allowed_domains: optional array of string`
19671896
19681897 - `blocked_domains: optional array of string`
19691898
19701899 - `max_content_tokens: optional number or null`
19711900
1972 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1901 format: int32
1902
1903 - `BetaManagedAgentsWebSearchToolConfig object`
19731904
19741905 Configuration for the web_search tool.
19751906
from line 1908
19771908
19781909 - `name: "web_search"`
19791910
1980 - `"web_search"`
1981
19821911 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19831912
19841913 Permission policy for tool execution.
19851914
1986 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1915 - `BetaManagedAgentsAlwaysAllowPolicy object`
19871916
19881917 Tool calls are automatically approved without user confirmation.
19891918
1990 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1919 - `BetaManagedAgentsAlwaysAskPolicy object`
19911920
19921921 Tool calls require user confirmation before execution.
19931922
19941923 - `type: "web_search"`
19951924
1996 - `"web_search"`
1997
19981925 - `allowed_domains: optional array of string`
19991926
20001927 - `blocked_domains: optional array of string`
from line 1934
20071934
20081935 Location precision. Only "approximate" is supported.
20091936
2010 - `"approximate"`
2011
20121937 - `city: optional string or null`
20131938
20141939 City name.
20151940
1941 minLength: 1, maxLength: 255
1942
20161943 - `country: optional string or null`
20171944
20181945 Two-letter ISO 3166-1 country code, uppercase.
from line 1948
20211948
20221949 Region or state name.
20231950
1951 minLength: 1, maxLength: 255
1952
20241953 - `timezone: optional string or null`
20251954
20261955 IANA timezone identifier, e.g. "America/Los_Angeles".
20271956
1957 minLength: 1, maxLength: 255
1958
20281959 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20291960
20301961 Resolved default configuration for agent tools.
from line 1966
20351966
20361967 Permission policy for tool execution.
20371968
2038 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1969 - `BetaManagedAgentsAlwaysAllowPolicy object`
20391970
20401971 Tool calls are automatically approved without user confirmation.
20411972
2042 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1973 - `BetaManagedAgentsAlwaysAskPolicy object`
20431974
20441975 Tool calls require user confirmation before execution.
20451976
20461977 - `type: "agent_toolset_20260401"`
20471978
2048 - `"agent_toolset_20260401"`
2049
2050 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1979 - `BetaManagedAgentsMCPToolset object`
20511980
20521981 - `configs: array of BetaManagedAgentsMCPToolConfig`
20531982
from line 1988
20591988
20601989 Permission policy for tool execution.
20611990
2062 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1991 - `BetaManagedAgentsAlwaysAllowPolicy object`
20631992
20641993 Tool calls are automatically approved without user confirmation.
20651994
2066 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1995 - `BetaManagedAgentsAlwaysAskPolicy object`
20671996
20681997 Tool calls require user confirmation before execution.
20691998
from line 2006
20772006
20782007 Permission policy for tool execution.
20792008
2080 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2009 - `BetaManagedAgentsAlwaysAllowPolicy object`
20812010
20822011 Tool calls are automatically approved without user confirmation.
20832012
2084 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2013 - `BetaManagedAgentsAlwaysAskPolicy object`
20852014
20862015 Tool calls require user confirmation before execution.
20872016
from line 2018
20892018
20902019 - `type: "mcp_toolset"`
20912020
2092 - `"mcp_toolset"`
2093
2094 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2021 - `BetaManagedAgentsCustomTool object`
20952022
20962023 A custom tool as returned in API responses.
20972024
from line 2030
21032030
21042031 - `type: "object"`
21052032
2106 - `"object"`
2107
21082033 - `properties: optional map[unknown] or null`
21092034
21102035 - `required: optional array of string or null`
from line 2038
21132038
21142039 - `type: "custom"`
21152040
2116 - `"custom"`
2117
21182041 - `type: "agent"`
21192042
2120 - `"agent"`
2121
21222043 - `version: number`
21232044
2124 - `BetaManagedAgentsAdvisor object { model, type }`
2045 format: int32
2046
2047 - `BetaManagedAgentsAdvisor object`
21252048
21262049 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
21272050
from line 2054
21312054
21322055 - `type: "advisor"`
21332056
2134 - `"advisor"`
2135
21362057 - `type: "coordinator"`
21372058
2138 - `"coordinator"`
2139
21402059 - `name: string`
21412060
21422061 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
21432062
2144 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2063 - `BetaManagedAgentsAnthropicSkill object`
21452064
21462065 A resolved Anthropic-managed skill.
21472066
2148 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2067 - `BetaManagedAgentsCustomSkill object`
21492068
21502069 A resolved user-created custom skill.
21512070
from line 2072
21532072
21542073 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
21552074
2156 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2157
2158 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2159
2160 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2075 - `BetaManagedAgentsAgentToolset20260401 object`
2076
2077 - `BetaManagedAgentsMCPToolset object`
2078
2079 - `BetaManagedAgentsCustomTool object`
21612080
21622081 A custom tool as returned in API responses.
21632082
21642083 - `type: "agent"`
21652084
2166 - `"agent"`
2167
21682085 - `version: number`
21692086
2087 format: int32
2088
21702089 - `budget: optional BetaManagedAgentsBudgetLimit or null`
21712090
21722091 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2102
21832102
21842103 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.
21852104
2186 - `"USD"`
2187
21882105 - `type: "limit"`
21892106
2190 - `"limit"`
2191
21922107 - `metadata: optional map[string]`
21932108
21942109 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 2112
21972112
21982113 The session's new title. Present only when the update changed it.
21992114
2200 - `BetaManagedAgentsStartEvent object { event, type }`
2115 - `BetaManagedAgentsStartEvent object`
22012116
22022117 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.
22032118
from line 2120
22052120
22062121 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.
22072122
2208 - `BetaManagedAgentsAgentMessagePreview object { id, type }`
2123 - `BetaManagedAgentsAgentMessagePreview object`
22092124
22102125 - `id: string`
22112126
from line 2128
22132128
22142129 - `type: "agent.message"`
22152130
2216 - `"agent.message"`
2217
2218 - `BetaManagedAgentsAgentThinkingPreview object { id, type }`
2131 - `BetaManagedAgentsAgentThinkingPreview object`
22192132
22202133 - `id: string`
22212134
from line 2136
22232136
22242137 - `type: "agent.thinking"`
22252138
2226 - `"agent.thinking"`
2227
22282139 - `type: "event_start"`
22292140
2230 - `"event_start"`
2231
2232 - `BetaManagedAgentsDeltaEvent object { delta, event_id, type }`
2141 - `BetaManagedAgentsDeltaEvent object`
22332142
22342143 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.
22352144
from line 2152
22432152
22442153 - `type: "content_delta"`
22452154
2246 - `"content_delta"`
2247
22482155 - `index: optional number`
22492156
22502157 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.
22512158
2159 format: uint32
2160
22522161 - `event_id: string`
22532162
22542163 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
22552164
22562165 - `type: "event_delta"`
22572166
2258 - `"event_delta"`
2259
2260 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
2167 - `BetaManagedAgentsSystemMessageEvent object`
22612168
22622169 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
22632170
from line 2180
22732180
22742181 The text content.
22752182
2183 minLength: 1
2184
22762185 - `type: "text"`
22772186
2278 - `"text"`
2279
22802187 - `type: "system.message"`
22812188
2282 - `"system.message"`
2283
22842189 - `processed_at: optional string or null`
22852190
22862191 A timestamp in RFC 3339 format
22872192
2288 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
2193 format: date-time
2194
2195 - `BetaManagedAgentsSessionUsageEvent object`
22892196
22902197 Periodic snapshot of the session's cumulative usage and tracked list cost.
22912198
from line 2204
22972204
22982205 A timestamp in RFC 3339 format
22992206
2207 format: date-time
2208
23002209 - `type: "session.usage"`
23012210
2302 - `"session.usage"`
2303
23042211 - `usage: BetaManagedAgentsSessionUsageSnapshot`
23052212
23062213 Point-in-time snapshot of a session's cumulative usage.
from line 2216
23092216
23102217 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.
23112218
2219 format: double
2220
23122221 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
23132222
23142223 Prompt-cache creation token usage broken down by cache lifetime.
from line 2226
23172226
23182227 Tokens used to create 1-hour ephemeral cache entries.
23192228
2229 format: int32
2230
23202231 - `ephemeral_5m_input_tokens: optional number`
23212232
23222233 Tokens used to create 5-minute ephemeral cache entries.
23232234
2235 format: int32
2236
23242237 - `cache_read_input_tokens: optional number`
23252238
23262239 Total tokens read from prompt cache.
23272240
2241 format: int32
2242
23282243 - `input_tokens: optional number`
23292244
23302245 Total input tokens consumed across all turns.
23312246
2247 format: int32
2248
23322249 - `list_cost: optional BetaMonetaryAmount`
23332250
23342251 A monetary amount in a specific currency.
from line 2254
23372254
23382255 Total output tokens generated across all turns.
23392256
2257 format: int32
2258
23402259 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
23412260
23422261 Cumulative count of server-executed tool invocations, broken down by tool.
from line 2264
23452264
23462265 Number of server-executed web fetch requests.
23472266
2267 format: int32
2268
23482269 - `web_search_requests: optional number`
23492270
23502271 Number of server-executed web search requests.
23512272
2273 format: int32
2274
23522275 - `budget: optional BetaManagedAgentsBudgetLimit or null`
23532276
23542277 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
23552278
2356### Example
2357
2358```http
2279- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
2280
2281 Server-sent event in the session stream.
2282
2283## Example
2284
2285```bash
23592286curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \
23602287 -H 'anthropic-version: 2023-06-01' \
23612288 -H 'anthropic-beta: managed-agents-2026-04-01' \
23622289 -H "X-Api-Key: $ANTHROPIC_API_KEY"
23632290```
23642291
2365#### Response
2292### Response (200)
23662293
23672294```json
23682295{
23692296
api/beta/sessions/list Changed · +132 / -157 lines
# List Sessions ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Sessions ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Sessions
3url: https://platform.claude.com/docs/en/api/beta/sessions/list
4---
1# List Sessions
52
6## List Sessions
3**GET** `/v1/sessions`
74
8**get** `/v1/sessions`
9
105List Sessions
116
12### Query Parameters
7## Query parameters
138
149- `agent_id: optional string`
1510
from line 14
1914
2015 Filter by agent version. Only applies when agent_id is also set.
2116
17 format: int32
18
2219- `"created_at[gt]": optional string`
2320
2421 Return sessions created after this time (exclusive).
2522
23 format: date-time
24
2625- `"created_at[gte]": optional string`
2726
2827 Return sessions created at or after this time (inclusive).
2928
29 format: date-time
30
3031- `"created_at[lt]": optional string`
3132
3233 Return sessions created before this time (exclusive).
3334
35 format: date-time
36
3437- `"created_at[lte]": optional string`
3538
3639 Return sessions created at or before this time (inclusive).
3740
41 format: date-time
42
3843- `deployment_id: optional string`
3944
4045 Filter sessions created by this deployment ID.
from line 52
4752
4853 Maximum number of results to return.
4954
55 format: int32
56
5057- `memory_store_id: optional string`
5158
5259 Filter sessions whose resources contain a memory_store with this memory store ID.
from line 82
7582
7683 - `"terminated"`
7784
78### Header Parameters
85## Headers
7986
8087- `"anthropic-beta": optional array of AnthropicBeta`
8188
from line 160
153160
154161 - `"mid-conversation-tool-changes-2026-07-01"`
155162
156### Returns
163## Returns
157164
158165- `data: optional array of BetaManagedAgentsSession`
159166
from line 182
175182
176183 - `type: "url"`
177184
178 - `"url"`
179
180185 - `url: string`
181186
182187 - `model: BetaManagedAgentsModelConfig`
from line 258
253258
254259 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
255260
256 - `BetaManagedAgentsEffortLow object { type }`
261 - `BetaManagedAgentsEffortLow object`
257262
258263 Low effort. Favors latency over reasoning depth.
259264
260265 - `type: "low"`
261266
262 - `"low"`
267 - `BetaManagedAgentsEffortMedium object`
263268
264 - `BetaManagedAgentsEffortMedium object { type }`
265
266269 Medium effort. Balances latency and reasoning depth.
267270
268271 - `type: "medium"`
269272
270 - `"medium"`
273 - `BetaManagedAgentsEffortHigh object`
271274
272 - `BetaManagedAgentsEffortHigh object { type }`
273
274275 High effort. Favors reasoning depth.
275276
276277 - `type: "high"`
277278
278 - `"high"`
279 - `BetaManagedAgentsEffortXhigh object`
279280
280 - `BetaManagedAgentsEffortXhigh object { type }`
281
282281 Extra-high effort. Not all models accept this level.
283282
284283 - `type: "xhigh"`
285284
286 - `"xhigh"`
285 - `BetaManagedAgentsEffortMax object`
287286
288 - `BetaManagedAgentsEffortMax object { type }`
289
290287 Maximum effort. Favors reasoning depth over latency.
291288
292289 - `type: "max"`
293290
294 - `"max"`
295
296291 - `inference_geo: optional string`
297292
298293 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 308
313308
314309 Full `agent` definitions the coordinator may spawn as session threads.
315310
316 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
311 - `BetaManagedAgentsSessionThreadAgent object`
317312
318313 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`.
319314
from line 332
337332
338333 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
339334
340 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
335 - `BetaManagedAgentsAnthropicSkill object`
341336
342337 A resolved Anthropic-managed skill.
343338
from line 340
345340
346341 - `type: "anthropic"`
347342
348 - `"anthropic"`
349
350343 - `version: string`
351344
352 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
345 - `BetaManagedAgentsCustomSkill object`
353346
354347 A resolved user-created custom skill.
355348
from line 350
357350
358351 - `type: "custom"`
359352
360 - `"custom"`
361
362353 - `version: string`
363354
364355 - `system: string or null`
from line 356
365356
366357 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
367358
368 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
359 - `BetaManagedAgentsAgentToolset20260401 object`
369360
370361 - `configs: array of BetaManagedAgentsAgentToolConfig`
371362
372 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
363 - `BetaManagedAgentsBashToolConfig object`
373364
374365 Configuration for the bash tool.
375366
from line 368
377368
378369 - `name: "bash"`
379370
380 - `"bash"`
381
382371 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
383372
384373 Permission policy for tool execution.
385374
386 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
375 - `BetaManagedAgentsAlwaysAllowPolicy object`
387376
388377 Tool calls are automatically approved without user confirmation.
389378
390379 - `type: "always_allow"`
391380
392 - `"always_allow"`
381 - `BetaManagedAgentsAlwaysAskPolicy object`
393382
394 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
395
396383 Tool calls require user confirmation before execution.
397384
398385 - `type: "always_ask"`
399386
400 - `"always_ask"`
401
402387 - `type: "bash"`
403388
404 - `"bash"`
389 - `BetaManagedAgentsEditToolConfig object`
405390
406 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
407
408391 Configuration for the edit tool.
409392
410393 - `enabled: boolean`
from line 394
411394
412395 - `name: "edit"`
413396
414 - `"edit"`
415
416397 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
417398
418399 Permission policy for tool execution.
419400
420 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
401 - `BetaManagedAgentsAlwaysAllowPolicy object`
421402
422403 Tool calls are automatically approved without user confirmation.
423404
424 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
405 - `BetaManagedAgentsAlwaysAskPolicy object`
425406
426407 Tool calls require user confirmation before execution.
427408
428409 - `type: "edit"`
429410
430 - `"edit"`
411 - `BetaManagedAgentsReadToolConfig object`
431412
432 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
433
434413 Configuration for the read tool.
435414
436415 - `enabled: boolean`
from line 416
437416
438417 - `name: "read"`
439418
440 - `"read"`
441
442419 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
443420
444421 Permission policy for tool execution.
445422
446 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
423 - `BetaManagedAgentsAlwaysAllowPolicy object`
447424
448425 Tool calls are automatically approved without user confirmation.
449426
450 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
427 - `BetaManagedAgentsAlwaysAskPolicy object`
451428
452429 Tool calls require user confirmation before execution.
453430
454431 - `type: "read"`
455432
456 - `"read"`
433 - `BetaManagedAgentsWriteToolConfig object`
457434
458 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
459
460435 Configuration for the write tool.
461436
462437 - `enabled: boolean`
from line 438
463438
464439 - `name: "write"`
465440
466 - `"write"`
467
468441 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
469442
470443 Permission policy for tool execution.
471444
472 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
445 - `BetaManagedAgentsAlwaysAllowPolicy object`
473446
474447 Tool calls are automatically approved without user confirmation.
475448
476 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
449 - `BetaManagedAgentsAlwaysAskPolicy object`
477450
478451 Tool calls require user confirmation before execution.
479452
480453 - `type: "write"`
481454
482 - `"write"`
455 - `BetaManagedAgentsGlobToolConfig object`
483456
484 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
485
486457 Configuration for the glob tool.
487458
488459 - `enabled: boolean`
from line 460
489460
490461 - `name: "glob"`
491462
492 - `"glob"`
493
494463 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
495464
496465 Permission policy for tool execution.
497466
498 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
467 - `BetaManagedAgentsAlwaysAllowPolicy object`
499468
500469 Tool calls are automatically approved without user confirmation.
501470
502 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
471 - `BetaManagedAgentsAlwaysAskPolicy object`
503472
504473 Tool calls require user confirmation before execution.
505474
506475 - `type: "glob"`
507476
508 - `"glob"`
477 - `BetaManagedAgentsGrepToolConfig object`
509478
510 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
511
512479 Configuration for the grep tool.
513480
514481 - `enabled: boolean`
from line 482
515482
516483 - `name: "grep"`
517484
518 - `"grep"`
519
520485 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
521486
522487 Permission policy for tool execution.
523488
524 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
489 - `BetaManagedAgentsAlwaysAllowPolicy object`
525490
526491 Tool calls are automatically approved without user confirmation.
527492
528 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
493 - `BetaManagedAgentsAlwaysAskPolicy object`
529494
530495 Tool calls require user confirmation before execution.
531496
532497 - `type: "grep"`
533498
534 - `"grep"`
499 - `BetaManagedAgentsWebFetchToolConfig object`
535500
536 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
537
538501 Configuration for the web_fetch tool.
539502
540503 - `enabled: boolean`
from line 504
541504
542505 - `name: "web_fetch"`
543506
544 - `"web_fetch"`
545
546507 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
547508
548509 Permission policy for tool execution.
549510
550 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
511 - `BetaManagedAgentsAlwaysAllowPolicy object`
551512
552513 Tool calls are automatically approved without user confirmation.
553514
554 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
515 - `BetaManagedAgentsAlwaysAskPolicy object`
555516
556517 Tool calls require user confirmation before execution.
557518
558519 - `type: "web_fetch"`
559520
560 - `"web_fetch"`
561
562521 - `allowed_domains: optional array of string`
563522
564523 - `blocked_domains: optional array of string`
from line 524
565524
566525 - `max_content_tokens: optional number or null`
567526
568 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
527 format: int32
569528
529 - `BetaManagedAgentsWebSearchToolConfig object`
530
570531 Configuration for the web_search tool.
571532
572533 - `enabled: boolean`
from line 534
573534
574535 - `name: "web_search"`
575536
576 - `"web_search"`
577
578537 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
579538
580539 Permission policy for tool execution.
581540
582 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
541 - `BetaManagedAgentsAlwaysAllowPolicy object`
583542
584543 Tool calls are automatically approved without user confirmation.
585544
586 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
545 - `BetaManagedAgentsAlwaysAskPolicy object`
587546
588547 Tool calls require user confirmation before execution.
589548
590549 - `type: "web_search"`
591550
592 - `"web_search"`
593
594551 - `allowed_domains: optional array of string`
595552
596553 - `blocked_domains: optional array of string`
from line 560
603560
604561 Location precision. Only "approximate" is supported.
605562
606 - `"approximate"`
607
608563 - `city: optional string or null`
609564
610565 City name.
611566
567 minLength: 1, maxLength: 255
568
612569 - `country: optional string or null`
613570
614571 Two-letter ISO 3166-1 country code, uppercase.
from line 574
617574
618575 Region or state name.
619576
577 minLength: 1, maxLength: 255
578
620579 - `timezone: optional string or null`
621580
622581 IANA timezone identifier, e.g. "America/Los_Angeles".
623582
583 minLength: 1, maxLength: 255
584
624585 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
625586
626587 Resolved default configuration for agent tools.
from line 592
631592
632593 Permission policy for tool execution.
633594
634 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
595 - `BetaManagedAgentsAlwaysAllowPolicy object`
635596
636597 Tool calls are automatically approved without user confirmation.
637598
638 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
599 - `BetaManagedAgentsAlwaysAskPolicy object`
639600
640601 Tool calls require user confirmation before execution.
641602
642603 - `type: "agent_toolset_20260401"`
643604
644 - `"agent_toolset_20260401"`
605 - `BetaManagedAgentsMCPToolset object`
645606
646 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
647
648607 - `configs: array of BetaManagedAgentsMCPToolConfig`
649608
650609 - `enabled: boolean`
from line 614
655614
656615 Permission policy for tool execution.
657616
658 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
617 - `BetaManagedAgentsAlwaysAllowPolicy object`
659618
660619 Tool calls are automatically approved without user confirmation.
661620
662 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
621 - `BetaManagedAgentsAlwaysAskPolicy object`
663622
664623 Tool calls require user confirmation before execution.
665624
from line 632
673632
674633 Permission policy for tool execution.
675634
676 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
635 - `BetaManagedAgentsAlwaysAllowPolicy object`
677636
678637 Tool calls are automatically approved without user confirmation.
679638
680 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
639 - `BetaManagedAgentsAlwaysAskPolicy object`
681640
682641 Tool calls require user confirmation before execution.
683642
from line 644
685644
686645 - `type: "mcp_toolset"`
687646
688 - `"mcp_toolset"`
647 - `BetaManagedAgentsCustomTool object`
689648
690 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
691
692649 A custom tool as returned in API responses.
693650
694651 - `description: string`
from line 656
699656
700657 - `type: "object"`
701658
702 - `"object"`
703
704659 - `properties: optional map[unknown] or null`
705660
706661 - `required: optional array of string or null`
from line 664
709664
710665 - `type: "custom"`
711666
712 - `"custom"`
713
714667 - `type: "agent"`
715668
716 - `"agent"`
717
718669 - `version: number`
719670
720 - `BetaManagedAgentsAdvisor object { model, type }`
671 format: int32
721672
673 - `BetaManagedAgentsAdvisor object`
674
722675 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
723676
724677 - `model: string`
from line 680
727680
728681 - `type: "advisor"`
729682
730 - `"advisor"`
731
732683 - `type: "coordinator"`
733684
734 - `"coordinator"`
735
736685 - `name: string`
737686
738687 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
739688
740 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
689 - `BetaManagedAgentsAnthropicSkill object`
741690
742691 A resolved Anthropic-managed skill.
743692
744 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
693 - `BetaManagedAgentsCustomSkill object`
745694
746695 A resolved user-created custom skill.
747696
from line 698
749698
750699 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
751700
752 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
701 - `BetaManagedAgentsAgentToolset20260401 object`
753702
754 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
703 - `BetaManagedAgentsMCPToolset object`
755704
756 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
705 - `BetaManagedAgentsCustomTool object`
757706
758707 A custom tool as returned in API responses.
759708
760709 - `type: "agent"`
761710
762 - `"agent"`
763
764711 - `version: number`
765712
713 format: int32
714
766715 - `archived_at: string or null`
767716
768717 A timestamp in RFC 3339 format
769718
719 format: date-time
720
770721 - `budget: BetaManagedAgentsBudgetLimit or null`
771722
772723 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 734
783734
784735 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.
785736
786 - `"USD"`
787
788737 - `type: "limit"`
789738
790 - `"limit"`
791
792739 - `created_at: string`
793740
794741 A timestamp in RFC 3339 format
795742
743 format: date-time
744
796745 - `environment_id: string`
797746
798747 - `metadata: map[string]`
from line 754
805754
806755 A timestamp in RFC 3339 format
807756
757 format: date-time
758
808759 - `description: string`
809760
810761 What the agent should produce.
from line 768
817768
818769 0-indexed revision cycle the outcome is currently on.
819770
771 format: int32
772
820773 - `outcome_id: string`
821774
822775 Server-generated outc_ ID for this outcome.
from line 780
827780
828781 - `type: "outcome_evaluation"`
829782
830 - `"outcome_evaluation"`
831
832783 - `resources: array of BetaManagedAgentsSessionResource`
833784
834 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
785 - `BetaManagedAgentsGitHubRepositoryResource object`
835786
836787 - `id: string`
837788
from line 790
839790
840791 A timestamp in RFC 3339 format
841792
793 format: date-time
794
842795 - `mount_path: string`
843796
844797 - `type: "github_repository"`
845798
846 - `"github_repository"`
847
848799 - `updated_at: string`
849800
850801 A timestamp in RFC 3339 format
851802
803 format: date-time
804
852805 - `url: string`
853806
854807 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
855808
856 - `BetaManagedAgentsBranchCheckout object { name, type }`
809 - `BetaManagedAgentsBranchCheckout object`
857810
858811 - `name: string`
859812
860813 Branch name to check out.
861814
815 minLength: 1, maxLength: 255
816
862817 - `type: "branch"`
863818
864 - `"branch"`
819 - `BetaManagedAgentsCommitCheckout object`
865820
866 - `BetaManagedAgentsCommitCheckout object { sha, type }`
867
868821 - `sha: string`
869822
870823 Full commit SHA to check out.
871824
825 minLength: 7, maxLength: 64
826
872827 - `type: "commit"`
873828
874 - `"commit"`
829 - `BetaManagedAgentsFileResource object`
875830
876 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
877
878831 - `id: string`
879832
880833 - `created_at: string`
from line 834
881834
882835 A timestamp in RFC 3339 format
883836
837 format: date-time
838
884839 - `file_id: string`
885840
886841 - `mount_path: string`
from line 842
887842
888843 - `type: "file"`
889844
890 - `"file"`
891
892845 - `updated_at: string`
893846
894847 A timestamp in RFC 3339 format
895848
896 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
849 format: date-time
897850
851 - `BetaManagedAgentsMemoryStoreResource object`
852
898853 A memory store attached to an agent session.
899854
900855 - `memory_store_id: string`
from line 858
903858
904859 - `type: "memory_store"`
905860
906 - `"memory_store"`
907
908861 - `access: optional "read_write" or "read_only" or null`
909862
910863 Access mode for an attached memory store.
from line 874
921874
922875 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
923876
877 maxLength: 4096
878
924879 - `mount_path: optional string or null`
925880
926881 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 892
937892
938893 Cumulative time in seconds the session spent in running status. Excludes idle time.
939894
895 format: double
896
940897 - `duration_seconds: optional number`
941898
942899 Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
943900
901 format: double
902
944903 - `status: "rescheduling" or "running" or "idle" or "terminated"`
945904
946905 SessionStatus enum
from line 916
957916
958917 - `type: "session"`
959918
960 - `"session"`
961
962919 - `updated_at: string`
963920
964921 A timestamp in RFC 3339 format
965922
923 format: date-time
924
966925 - `usage: BetaManagedAgentsSessionUsage`
967926
968927 Cumulative token usage for a session across all turns.
from line 930
971930
972931 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.
973932
933 format: double
934
974935 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
975936
976937 Prompt-cache creation token usage broken down by cache lifetime.
from line 940
979940
980941 Tokens used to create 1-hour ephemeral cache entries.
981942
943 format: int32
944
982945 - `ephemeral_5m_input_tokens: optional number`
983946
984947 Tokens used to create 5-minute ephemeral cache entries.
985948
949 format: int32
950
986951 - `cache_read_input_tokens: optional number`
987952
988953 Total tokens read from prompt cache.
989954
955 format: int32
956
990957 - `input_tokens: optional number`
991958
992959 Total input tokens consumed across all turns.
993960
961 format: int32
962
994963 - `list_cost: optional BetaMonetaryAmount or null`
995964
996965 A monetary amount in a specific currency.
from line 968
999968
1000969 Total output tokens generated across all turns.
1001970
971 format: int32
972
1002973 - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null`
1003974
1004975 Cumulative count of server-executed tool invocations, broken down by tool.
from line 978
1007978
1008979 Number of server-executed web fetch requests.
1009980
981 format: int32
982
1010983 - `web_search_requests: optional number`
1011984
1012985 Number of server-executed web search requests.
1013986
987 format: int32
988
1014989 - `vault_ids: array of string`
1015990
1016991 Vault IDs attached to the session at creation. Empty when no vaults were supplied.
from line 1002
10271002
10281003 Opaque cursor for the previous page. Null when on the first page. Pass as the `page` parameter to navigate backward.
10291004
1030### Example
1005## Example
10311006
1032```http
1007```bash
10331008curl https://api.anthropic.com/v1/sessions \
10341009 -H 'anthropic-version: 2023-06-01' \
10351010 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 1011
10361011 -H "X-Api-Key: $ANTHROPIC_API_KEY"
10371012```
10381013
1039#### Response
1014### Response (200)
10401015
10411016```json
10421017{
api/beta/sessions/resources Changed · +177 / -150 lines
### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types
from line 1
1---
2title: Resources
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources
4---
5
61# Resources
72
83## Add Session Resource
94
10**post** `/v1/sessions/{session_id}/resources`
5**POST** `/v1/sessions/{session_id}/resources`
116
127Add Session Resource
138
14### Path Parameters
9### Path parameters
1510
1611- `session_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- `file_id: string`
9994
10095 ID of a previously uploaded file.
10196
97 minLength: 1, maxLength: 128
98
10299- `type: "file"`
103100
104 - `"file"`
105
106101- `mount_path: optional string or null`
107102
108103 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
109104
105 minLength: 1, maxLength: 4096
106
110107### Returns
111108
112- `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
109- `BetaManagedAgentsFileResource object`
113110
114111 - `id: string`
115112
from line 114
117114
118115 A timestamp in RFC 3339 format
119116
117 format: date-time
118
120119 - `file_id: string`
121120
122121 - `mount_path: string`
from line 122
123122
124123 - `type: "file"`
125124
126 - `"file"`
127
128125 - `updated_at: string`
129126
130127 A timestamp in RFC 3339 format
131128
129 format: date-time
130
132131### Example
133132
134```http
133```bash
135134curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \
136135 -H 'Content-Type: application/json' \
137136 -H 'anthropic-version: 2023-06-01' \
from line 143
144143 }'
145144```
146145
147#### Response
146#### Response (200)
148147
149148```json
150149{
from line 158
159158
160159## List Session Resources
161160
162**get** `/v1/sessions/{session_id}/resources`
161**GET** `/v1/sessions/{session_id}/resources`
163162
164163List Session Resources
165164
166### Path Parameters
165### Path parameters
167166
168167- `session_id: string`
169168
170### Query Parameters
169### Query parameters
171170
172171- `limit: optional number`
173172
174173 Maximum number of resources to return per page (max 1000). If omitted, returns all resources.
175174
175 format: int32
176
176177- `page: optional string`
177178
178179 Opaque cursor from a previous response's next_page field.
179180
180### Header Parameters
181### Headers
181182
182183- `"anthropic-beta": optional array of AnthropicBeta`
183184
from line 262
261262
262263 Resources for the session, ordered by `created_at`.
263264
264 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
265 - `BetaManagedAgentsGitHubRepositoryResource object`
265266
266267 - `id: string`
267268
from line 270
269270
270271 A timestamp in RFC 3339 format
271272
273 format: date-time
274
272275 - `mount_path: string`
273276
274277 - `type: "github_repository"`
275278
276 - `"github_repository"`
277
278279 - `updated_at: string`
279280
280281 A timestamp in RFC 3339 format
281282
283 format: date-time
284
282285 - `url: string`
283286
284287 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
285288
286 - `BetaManagedAgentsBranchCheckout object { name, type }`
289 - `BetaManagedAgentsBranchCheckout object`
287290
288291 - `name: string`
289292
290293 Branch name to check out.
291294
295 minLength: 1, maxLength: 255
296
292297 - `type: "branch"`
293298
294 - `"branch"`
299 - `BetaManagedAgentsCommitCheckout object`
295300
296 - `BetaManagedAgentsCommitCheckout object { sha, type }`
297
298301 - `sha: string`
299302
300303 Full commit SHA to check out.
301304
305 minLength: 7, maxLength: 64
306
302307 - `type: "commit"`
303308
304 - `"commit"`
309 - `BetaManagedAgentsFileResource object`
305310
306 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
307
308311 - `id: string`
309312
310313 - `created_at: string`
from line 314
311314
312315 A timestamp in RFC 3339 format
313316
317 format: date-time
318
314319 - `file_id: string`
315320
316321 - `mount_path: string`
from line 322
317322
318323 - `type: "file"`
319324
320 - `"file"`
321
322325 - `updated_at: string`
323326
324327 A timestamp in RFC 3339 format
325328
326 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
329 format: date-time
327330
331 - `BetaManagedAgentsMemoryStoreResource object`
332
328333 A memory store attached to an agent session.
329334
330335 - `memory_store_id: string`
from line 338
333338
334339 - `type: "memory_store"`
335340
336 - `"memory_store"`
337
338341 - `access: optional "read_write" or "read_only" or null`
339342
340343 Access mode for an attached memory store.
from line 354
351354
352355 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
353356
357 maxLength: 4096
358
354359 - `mount_path: optional string or null`
355360
356361 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 370
365370
366371### Example
367372
368```http
373```bash
369374curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \
370375 -H 'anthropic-version: 2023-06-01' \
371376 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 377
372377 -H "X-Api-Key: $ANTHROPIC_API_KEY"
373378```
374379
375#### Response
380#### Response (200)
376381
377382```json
378383{
from line 409
404409
405410## Get Session Resource
406411
407**get** `/v1/sessions/{session_id}/resources/{resource_id}`
412**GET** `/v1/sessions/{session_id}/resources/{resource_id}`
408413
409414Get Session Resource
410415
411### Path Parameters
416### Path parameters
412417
413418- `session_id: string`
414419
415420- `resource_id: string`
416421
417### Header Parameters
422### Headers
418423
419424- `"anthropic-beta": optional array of AnthropicBeta`
420425
from line 499
494499
495500### Returns
496501
497- `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
502- `BetaManagedAgentsGitHubRepositoryResource object`
498503
499504 - `id: string`
500505
from line 507
502507
503508 A timestamp in RFC 3339 format
504509
510 format: date-time
511
505512 - `mount_path: string`
506513
507514 - `type: "github_repository"`
508515
509 - `"github_repository"`
510
511516 - `updated_at: string`
512517
513518 A timestamp in RFC 3339 format
514519
520 format: date-time
521
515522 - `url: string`
516523
517524 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
518525
519 - `BetaManagedAgentsBranchCheckout object { name, type }`
526 - `BetaManagedAgentsBranchCheckout object`
520527
521528 - `name: string`
522529
523530 Branch name to check out.
524531
532 minLength: 1, maxLength: 255
533
525534 - `type: "branch"`
526535
527 - `"branch"`
536 - `BetaManagedAgentsCommitCheckout object`
528537
529 - `BetaManagedAgentsCommitCheckout object { sha, type }`
530
531538 - `sha: string`
532539
533540 Full commit SHA to check out.
534541
542 minLength: 7, maxLength: 64
543
535544 - `type: "commit"`
536545
537 - `"commit"`
546- `BetaManagedAgentsFileResource object`
538547
539- `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
540
541548 - `id: string`
542549
543550 - `created_at: string`
from line 551
544551
545552 A timestamp in RFC 3339 format
546553
554 format: date-time
555
547556 - `file_id: string`
548557
549558 - `mount_path: string`
from line 559
550559
551560 - `type: "file"`
552561
553 - `"file"`
554
555562 - `updated_at: string`
556563
557564 A timestamp in RFC 3339 format
558565
559- `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
566 format: date-time
560567
568- `BetaManagedAgentsMemoryStoreResource object`
569
561570 A memory store attached to an agent session.
562571
563572 - `memory_store_id: string`
from line 575
566575
567576 - `type: "memory_store"`
568577
569 - `"memory_store"`
570
571578 - `access: optional "read_write" or "read_only" or null`
572579
573580 Access mode for an attached memory store.
from line 591
584591
585592 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
586593
594 maxLength: 4096
595
587596 - `mount_path: optional string or null`
588597
589598 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 603
594603
595604### Example
596605
597```http
606```bash
598607curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
599608 -H 'anthropic-version: 2023-06-01' \
600609 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 610
601610 -H "X-Api-Key: $ANTHROPIC_API_KEY"
602611```
603612
604#### Response
613#### Response (200)
605614
606615```json
607616{
from line 629
620629
621630## Update Session Resource
622631
623**post** `/v1/sessions/{session_id}/resources/{resource_id}`
632**POST** `/v1/sessions/{session_id}/resources/{resource_id}`
624633
625634Update Session Resource
626635
627### Path Parameters
636### Path parameters
628637
629638- `session_id: string`
630639
631640- `resource_id: string`
632641
633### Header Parameters
642### Headers
634643
635644- `"anthropic-beta": optional array of AnthropicBeta`
636645
from line 717
708717
709718 - `"mid-conversation-tool-changes-2026-07-01"`
710719
711### Body Parameters
720### Body parameters
712721
713722- `authorization_token: string`
714723
715724 New authorization token for the resource. Currently only `github_repository` resources support token rotation.
716725
726 minLength: 1, maxLength: 4096
727
717728### Returns
718729
719- `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
730- `BetaManagedAgentsGitHubRepositoryResource object`
720731
721732 - `id: string`
722733
from line 735
724735
725736 A timestamp in RFC 3339 format
726737
738 format: date-time
739
727740 - `mount_path: string`
728741
729742 - `type: "github_repository"`
730743
731 - `"github_repository"`
732
733744 - `updated_at: string`
734745
735746 A timestamp in RFC 3339 format
736747
748 format: date-time
749
737750 - `url: string`
738751
739752 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
740753
741 - `BetaManagedAgentsBranchCheckout object { name, type }`
754 - `BetaManagedAgentsBranchCheckout object`
742755
743756 - `name: string`
744757
745758 Branch name to check out.
746759
760 minLength: 1, maxLength: 255
761
747762 - `type: "branch"`
748763
749 - `"branch"`
764 - `BetaManagedAgentsCommitCheckout object`
750765
751 - `BetaManagedAgentsCommitCheckout object { sha, type }`
752
753766 - `sha: string`
754767
755768 Full commit SHA to check out.
756769
770 minLength: 7, maxLength: 64
771
757772 - `type: "commit"`
758773
759 - `"commit"`
774- `BetaManagedAgentsFileResource object`
760775
761- `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
762
763776 - `id: string`
764777
765778 - `created_at: string`
from line 779
766779
767780 A timestamp in RFC 3339 format
768781
782 format: date-time
783
769784 - `file_id: string`
770785
771786 - `mount_path: string`
from line 787
772787
773788 - `type: "file"`
774789
775 - `"file"`
776
777790 - `updated_at: string`
778791
779792 A timestamp in RFC 3339 format
780793
781- `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
794 format: date-time
782795
796- `BetaManagedAgentsMemoryStoreResource object`
797
783798 A memory store attached to an agent session.
784799
785800 - `memory_store_id: string`
from line 803
788803
789804 - `type: "memory_store"`
790805
791 - `"memory_store"`
792
793806 - `access: optional "read_write" or "read_only" or null`
794807
795808 Access mode for an attached memory store.
from line 819
806819
807820 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
808821
822 maxLength: 4096
823
809824 - `mount_path: optional string or null`
810825
811826 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 831
816831
817832### Example
818833
819```http
834```bash
820835curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
821836 -H 'Content-Type: application/json' \
822837 -H 'anthropic-version: 2023-06-01' \
from line 842
827842 }'
828843```
829844
830#### Response
845#### Response (200)
831846
832847```json
833848{
from line 861
846861
847862## Delete Session Resource
848863
849**delete** `/v1/sessions/{session_id}/resources/{resource_id}`
864**DELETE** `/v1/sessions/{session_id}/resources/{resource_id}`
850865
851866Delete Session Resource
852867
853### Path Parameters
868### Path parameters
854869
855870- `session_id: string`
856871
857872- `resource_id: string`
858873
859### Header Parameters
874### Headers
860875
861876- `"anthropic-beta": optional array of AnthropicBeta`
862877
from line 951
936951
937952### Returns
938953
939- `BetaManagedAgentsDeleteSessionResource object { id, type }`
954- `BetaManagedAgentsDeleteSessionResource object`
940955
941956 Confirmation of resource deletion.
942957
from line 959
944959
945960 - `type: "session_resource_deleted"`
946961
947 - `"session_resource_deleted"`
948
949962### Example
950963
951```http
964```bash
952965curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
953966 -X DELETE \
954967 -H 'anthropic-version: 2023-06-01' \
from line 969
956969 -H "X-Api-Key: $ANTHROPIC_API_KEY"
957970```
958971
959#### Response
972#### Response (200)
960973
961974```json
962975{
from line 978
965978}
966979```
967980
968## Domain Types
981## Domain types
969982
970983### Beta Managed Agents Delete Session Resource
971984
972- `BetaManagedAgentsDeleteSessionResource object { id, type }`
985- `BetaManagedAgentsDeleteSessionResource object`
973986
974987 Confirmation of resource deletion.
975988
from line 990
977990
978991 - `type: "session_resource_deleted"`
979992
980 - `"session_resource_deleted"`
981
982993### Beta Managed Agents File Resource
983994
984- `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
995- `BetaManagedAgentsFileResource object`
985996
986997 - `id: string`
987998
from line 1000
9891000
9901001 A timestamp in RFC 3339 format
9911002
1003 format: date-time
1004
9921005 - `file_id: string`
9931006
9941007 - `mount_path: string`
from line 1008
9951008
9961009 - `type: "file"`
9971010
998 - `"file"`
999
10001011 - `updated_at: string`
10011012
10021013 A timestamp in RFC 3339 format
10031014
1015 format: date-time
1016
10041017### Beta Managed Agents GitHub Repository Resource
10051018
1006- `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
1019- `BetaManagedAgentsGitHubRepositoryResource object`
10071020
10081021 - `id: string`
10091022
from line 1024
10111024
10121025 A timestamp in RFC 3339 format
10131026
1027 format: date-time
1028
10141029 - `mount_path: string`
10151030
10161031 - `type: "github_repository"`
10171032
1018 - `"github_repository"`
1019
10201033 - `updated_at: string`
10211034
10221035 A timestamp in RFC 3339 format
10231036
1037 format: date-time
1038
10241039 - `url: string`
10251040
10261041 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
10271042
1028 - `BetaManagedAgentsBranchCheckout object { name, type }`
1043 - `BetaManagedAgentsBranchCheckout object`
10291044
10301045 - `name: string`
10311046
10321047 Branch name to check out.
10331048
1049 minLength: 1, maxLength: 255
1050
10341051 - `type: "branch"`
10351052
1036 - `"branch"`
1053 - `BetaManagedAgentsCommitCheckout object`
10371054
1038 - `BetaManagedAgentsCommitCheckout object { sha, type }`
1039
10401055 - `sha: string`
10411056
10421057 Full commit SHA to check out.
10431058
1059 minLength: 7, maxLength: 64
1060
10441061 - `type: "commit"`
10451062
1046 - `"commit"`
1047
10481063### Beta Managed Agents Memory Store Resource
10491064
1050- `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
1065- `BetaManagedAgentsMemoryStoreResource object`
10511066
10521067 A memory store attached to an agent session.
10531068
from line 1072
10571072
10581073 - `type: "memory_store"`
10591074
1060 - `"memory_store"`
1061
10621075 - `access: optional "read_write" or "read_only" or null`
10631076
10641077 Access mode for an attached memory store.
from line 1088
10751088
10761089 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
10771090
1091 maxLength: 4096
1092
10781093 - `mount_path: optional string or null`
10791094
10801095 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 1104
10891104
10901105 A memory store attached to an agent session.
10911106
1092 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
1107 - `BetaManagedAgentsGitHubRepositoryResource object`
10931108
10941109 - `id: string`
10951110
from line 1112
10971112
10981113 A timestamp in RFC 3339 format
10991114
1115 format: date-time
1116
11001117 - `mount_path: string`
11011118
11021119 - `type: "github_repository"`
11031120
1104 - `"github_repository"`
1105
11061121 - `updated_at: string`
11071122
11081123 A timestamp in RFC 3339 format
11091124
1125 format: date-time
1126
11101127 - `url: string`
11111128
11121129 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
11131130
1114 - `BetaManagedAgentsBranchCheckout object { name, type }`
1131 - `BetaManagedAgentsBranchCheckout object`
11151132
11161133 - `name: string`
11171134
11181135 Branch name to check out.
11191136
1137 minLength: 1, maxLength: 255
1138
11201139 - `type: "branch"`
11211140
1122 - `"branch"`
1141 - `BetaManagedAgentsCommitCheckout object`
11231142
1124 - `BetaManagedAgentsCommitCheckout object { sha, type }`
1125
11261143 - `sha: string`
11271144
11281145 Full commit SHA to check out.
11291146
1147 minLength: 7, maxLength: 64
1148
11301149 - `type: "commit"`
11311150
1132 - `"commit"`
1151 - `BetaManagedAgentsFileResource object`
11331152
1134 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
1135
11361153 - `id: string`
11371154
11381155 - `created_at: string`
from line 1156
11391156
11401157 A timestamp in RFC 3339 format
11411158
1159 format: date-time
1160
11421161 - `file_id: string`
11431162
11441163 - `mount_path: string`
from line 1164
11451164
11461165 - `type: "file"`
11471166
1148 - `"file"`
1149
11501167 - `updated_at: string`
11511168
11521169 A timestamp in RFC 3339 format
11531170
1154 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
1171 format: date-time
11551172
1173 - `BetaManagedAgentsMemoryStoreResource object`
1174
11561175 A memory store attached to an agent session.
11571176
11581177 - `memory_store_id: string`
from line 1180
11611180
11621181 - `type: "memory_store"`
11631182
1164 - `"memory_store"`
1165
11661183 - `access: optional "read_write" or "read_only" or null`
11671184
11681185 Access mode for an attached memory store.
from line 1196
11791196
11801197 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
11811198
1199 maxLength: 4096
1200
11821201 - `mount_path: optional string or null`
11831202
11841203 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 1212
11931212
11941213 The requested session resource.
11951214
1196 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
1215 - `BetaManagedAgentsGitHubRepositoryResource object`
11971216
11981217 - `id: string`
11991218
from line 1220
12011220
12021221 A timestamp in RFC 3339 format
12031222
1223 format: date-time
1224
12041225 - `mount_path: string`
12051226
12061227 - `type: "github_repository"`
12071228
1208 - `"github_repository"`
1209
12101229 - `updated_at: string`
12111230
12121231 A timestamp in RFC 3339 format
12131232
1233 format: date-time
1234
12141235 - `url: string`
12151236
12161237 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
12171238
1218 - `BetaManagedAgentsBranchCheckout object { name, type }`
1239 - `BetaManagedAgentsBranchCheckout object`
12191240
12201241 - `name: string`
12211242
12221243 Branch name to check out.
12231244
1245 minLength: 1, maxLength: 255
1246
12241247 - `type: "branch"`
12251248
1226 - `"branch"`
1249 - `BetaManagedAgentsCommitCheckout object`
12271250
1228 - `BetaManagedAgentsCommitCheckout object { sha, type }`
1229
12301251 - `sha: string`
12311252
12321253 Full commit SHA to check out.
12331254
1255 minLength: 7, maxLength: 64
1256
12341257 - `type: "commit"`
12351258
1236 - `"commit"`
1259 - `BetaManagedAgentsFileResource object`
12371260
1238 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
1239
12401261 - `id: string`
12411262
12421263 - `created_at: string`
from line 1264
12431264
12441265 A timestamp in RFC 3339 format
12451266
1267 format: date-time
1268
12461269 - `file_id: string`
12471270
12481271 - `mount_path: string`
from line 1272
12491272
12501273 - `type: "file"`
12511274
1252 - `"file"`
1253
12541275 - `updated_at: string`
12551276
12561277 A timestamp in RFC 3339 format
12571278
1258 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
1279 format: date-time
12591280
1281 - `BetaManagedAgentsMemoryStoreResource object`
1282
12601283 A memory store attached to an agent session.
12611284
12621285 - `memory_store_id: string`
from line 1288
12651288
12661289 - `type: "memory_store"`
12671290
1268 - `"memory_store"`
1269
12701291 - `access: optional "read_write" or "read_only" or null`
12711292
12721293 Access mode for an attached memory store.
from line 1304
12831304
12841305 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
12851306
1307 maxLength: 4096
1308
12861309 - `mount_path: optional string or null`
12871310
12881311 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 1320
12971320
12981321 The updated session resource.
12991322
1300 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
1323 - `BetaManagedAgentsGitHubRepositoryResource object`
13011324
13021325 - `id: string`
13031326
from line 1328
13051328
13061329 A timestamp in RFC 3339 format
13071330
1331 format: date-time
1332
13081333 - `mount_path: string`
13091334
13101335 - `type: "github_repository"`
13111336
1312 - `"github_repository"`
1313
13141337 - `updated_at: string`
13151338
13161339 A timestamp in RFC 3339 format
13171340
1341 format: date-time
1342
13181343 - `url: string`
13191344
13201345 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
13211346
1322 - `BetaManagedAgentsBranchCheckout object { name, type }`
1347 - `BetaManagedAgentsBranchCheckout object`
13231348
13241349 - `name: string`
13251350
13261351 Branch name to check out.
13271352
1353 minLength: 1, maxLength: 255
1354
13281355 - `type: "branch"`
13291356
1330 - `"branch"`
1357 - `BetaManagedAgentsCommitCheckout object`
13311358
1332 - `BetaManagedAgentsCommitCheckout object { sha, type }`
1333
13341359 - `sha: string`
13351360
13361361 Full commit SHA to check out.
13371362
1363 minLength: 7, maxLength: 64
1364
13381365 - `type: "commit"`
13391366
1340 - `"commit"`
1367 - `BetaManagedAgentsFileResource object`
13411368
1342 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
1343
13441369 - `id: string`
13451370
13461371 - `created_at: string`
from line 1372
13471372
13481373 A timestamp in RFC 3339 format
13491374
1375 format: date-time
1376
13501377 - `file_id: string`
13511378
13521379 - `mount_path: string`
from line 1380
13531380
13541381 - `type: "file"`
13551382
1356 - `"file"`
1357
13581383 - `updated_at: string`
13591384
13601385 A timestamp in RFC 3339 format
13611386
1362 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
1387 format: date-time
13631388
1389 - `BetaManagedAgentsMemoryStoreResource object`
1390
13641391 A memory store attached to an agent session.
13651392
13661393 - `memory_store_id: string`
from line 1396
13691396
13701397 - `type: "memory_store"`
13711398
1372 - `"memory_store"`
1373
13741399 - `access: optional "read_write" or "read_only" or null`
13751400
13761401 Access mode for an attached memory store.
from line 1411
13861411 - `instructions: optional string or null`
13871412
13881413 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
1414
1415 maxLength: 4096
13891416
13901417 - `mount_path: optional string or null`
13911418
api/beta/sessions/resources/add Changed · +18 / -19 lines
# Add Session Resource ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Add Session Resource ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Add Session Resource
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/add
4---
1# Add Session Resource
52
6## Add Session Resource
3**POST** `/v1/sessions/{session_id}/resources`
74
8**post** `/v1/sessions/{session_id}/resources`
9
105Add Session Resource
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- `file_id: string`
9792
9893 ID of a previously uploaded file.
9994
95 minLength: 1, maxLength: 128
96
10097- `type: "file"`
10198
102 - `"file"`
103
10499- `mount_path: optional string or null`
105100
106101 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
107102
108### Returns
103 minLength: 1, maxLength: 4096
109104
110- `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
105## Returns
111106
107- `BetaManagedAgentsFileResource object`
108
112109 - `id: string`
113110
114111 - `created_at: string`
from line 112
115112
116113 A timestamp in RFC 3339 format
117114
115 format: date-time
116
118117 - `file_id: string`
119118
120119 - `mount_path: string`
from line 120
121120
122121 - `type: "file"`
123122
124 - `"file"`
125
126123 - `updated_at: string`
127124
128125 A timestamp in RFC 3339 format
129126
130### Example
127 format: date-time
131128
132```http
129## Example
130
131```bash
133132curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \
134133 -H 'Content-Type: application/json' \
135134 -H 'anthropic-version: 2023-06-01' \
from line 141
142141 }'
143142```
144143
145#### Response
144### Response (200)
146145
147146```json
148147{
api/beta/sessions/resources/delete Changed · +9 / -16 lines
# Delete Session Resource ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Delete Session Resource ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Delete Session Resource
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/delete
4---
1# Delete Session Resource
52
6## Delete Session Resource
3**DELETE** `/v1/sessions/{session_id}/resources/{resource_id}`
74
8**delete** `/v1/sessions/{session_id}/resources/{resource_id}`
9
105Delete 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- `BetaManagedAgentsDeleteSessionResource object { id, type }`
93- `BetaManagedAgentsDeleteSessionResource object`
9994
10095 Confirmation of resource deletion.
10196
from line 98
10398
10499 - `type: "session_resource_deleted"`
105100
106 - `"session_resource_deleted"`
101## Example
107102
108### Example
109
110```http
103```bash
111104curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
112105 -X DELETE \
113106 -H 'anthropic-version: 2023-06-01' \
from line 108
115108 -H "X-Api-Key: $ANTHROPIC_API_KEY"
116109```
117110
118#### Response
111### Response (200)
119112
120113```json
121114{
api/beta/sessions/resources/list Changed · +32 / -31 lines
# List Session Resources ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Session Resources ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Session Resources
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/list
4---
1# List Session Resources
52
6## List Session Resources
3**GET** `/v1/sessions/{session_id}/resources`
74
8**get** `/v1/sessions/{session_id}/resources`
9
105List Session Resources
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 number of resources to return per page (max 1000). If omitted, returns all resources.
2116
17 format: int32
18
2219- `page: optional string`
2320
2421 Opaque cursor from a previous response's next_page field.
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: array of BetaManagedAgentsSessionResource`
107104
108105 Resources for the session, ordered by `created_at`.
109106
110 - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }`
107 - `BetaManagedAgentsGitHubRepositoryResource object`
111108
112109 - `id: string`
113110
from line 112
115112
116113 A timestamp in RFC 3339 format
117114
115 format: date-time
116
118117 - `mount_path: string`
119118
120119 - `type: "github_repository"`
121120
122 - `"github_repository"`
123
124121 - `updated_at: string`
125122
126123 A timestamp in RFC 3339 format
127124
125 format: date-time
126
128127 - `url: string`
129128
130129 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
131130
132 - `BetaManagedAgentsBranchCheckout object { name, type }`
131 - `BetaManagedAgentsBranchCheckout object`
133132
134133 - `name: string`
135134
136135 Branch name to check out.
137136
137 minLength: 1, maxLength: 255
138
138139 - `type: "branch"`
139140
140 - `"branch"`
141 - `BetaManagedAgentsCommitCheckout object`
141142
142 - `BetaManagedAgentsCommitCheckout object { sha, type }`
143
144143 - `sha: string`
145144
146145 Full commit SHA to check out.
147146
147 minLength: 7, maxLength: 64
148
148149 - `type: "commit"`
149150
150 - `"commit"`
151 - `BetaManagedAgentsFileResource object`
151152
152 - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }`
153
154153 - `id: string`
155154
156155 - `created_at: string`
from line 156
157156
158157 A timestamp in RFC 3339 format
159158
159 format: date-time
160
160161 - `file_id: string`
161162
162163 - `mount_path: string`
from line 164
163164
164165 - `type: "file"`
165166
166 - `"file"`
167
168167 - `updated_at: string`
169168
170169 A timestamp in RFC 3339 format
171170
172 - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }`
171 format: date-time
173172
173 - `BetaManagedAgentsMemoryStoreResource object`
174
174175 A memory store attached to an agent session.
175176
176177 - `memory_store_id: string`
from line 180
179180
180181 - `type: "memory_store"`
181182
182 - `"memory_store"`
183
184183 - `access: optional "read_write" or "read_only" or null`
185184
186185 Access mode for an attached memory store.
from line 196
197196
198197 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
199198
199 maxLength: 4096
200
200201 - `mount_path: optional string or null`
201202
202203 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 210
209210
210211 Opaque cursor for the next page. Null when no more results.
211212
212### Example
213## Example
213214
214```http
215```bash
215216curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \
216217 -H 'anthropic-version: 2023-06-01' \
217218 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 219
218219 -H "X-Api-Key: $ANTHROPIC_API_KEY"
219220```
220221
221#### Response
222### Response (200)
222223
223224```json
224225{