List Session Thread Events changedapi/beta/sessions/threads/events/list
Nearest release: v2.1.245, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+320added
Lines−387removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits26to this page, all time
# List Session Thread Events ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Session Thread Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The whole hunk
from line 1, old and new numbered
/
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: List Session Thread Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/events/list
4---
5
6## List Session Thread Events
7
8**get** `/v1/sessions/{session_id}/threads/{thread_id}/events`
1# List Session Thread Events
2
3**GET** `/v1/sessions/{session_id}/threads/{thread_id}/events`
94
105List Session Thread Events
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
1611- `thread_id: string`
1712
18### Query Parameters
13## Query parameters
1914
2015- `limit: optional number`
2116
2217 Query parameter for limit
2318
19 format: int32
20
2421- `page: optional string`
2522
2623 Query parameter for page
2724
28### Header Parameters
25## Headers
2926
3027- `"anthropic-beta": optional array of AnthropicBeta`
3128
from line 100
103100
104101 - `"mid-conversation-tool-changes-2026-07-01"`
105102
106### Returns
103## Returns
107104
108105- `data: optional array of BetaManagedAgentsSessionEvent`
109106
110107 Events for the thread, ordered by `processed_at`.
111108
112 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
109 - `BetaManagedAgentsUserMessageEvent object`
113110
114111 A user message event in the session conversation.
115112
from line 118
121118
122119 Array of content blocks comprising the user message.
123120
124 - `BetaManagedAgentsTextBlock object { text, type }`
121 - `BetaManagedAgentsTextBlock object`
125122
126123 Regular text content.
127124
from line 126
129126
130127 The text content.
131128
129 minLength: 1
130
132131 - `type: "text"`
133132
134 - `"text"`
135
136 - `BetaManagedAgentsImageBlock object { source, type }`
133 - `BetaManagedAgentsImageBlock object`
137134
138135 Image content specified directly as base64 data or as a reference via a URL.
139136
from line 138
141138
142139 Union type for image source variants.
143140
144 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
141 - `BetaManagedAgentsBase64ImageSource object`
145142
146143 Base64-encoded image data.
147144
from line 146
149146
150147 Base64-encoded image data.
151148
149 minLength: 1
150
152151 - `media_type: string`
153152
154153 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
155154
155 minLength: 1
156
156157 - `type: "base64"`
157158
158 - `"base64"`
159
160 - `BetaManagedAgentsURLImageSource object { type, url }`
159 - `BetaManagedAgentsURLImageSource object`
161160
162161 Image referenced by URL.
163162
164163 - `type: "url"`
165164
166 - `"url"`
167
168165 - `url: string`
169166
170167 URL of the image to fetch.
171168
172 - `BetaManagedAgentsFileImageSource object { file_id, type }`
169 minLength: 1
170
171 - `BetaManagedAgentsFileImageSource object`
173172
174173 Image referenced by file ID.
175174
from line 176
177176
178177 ID of a previously uploaded file.
179178
179 minLength: 1
180
180181 - `type: "file"`
181182
182 - `"file"`
183
184183 - `type: "image"`
185184
186 - `"image"`
187
188 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
185 - `BetaManagedAgentsDocumentBlock object`
189186
190187 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
191188
from line 190
193190
194191 Union type for document source variants.
195192
196 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
193 - `BetaManagedAgentsBase64DocumentSource object`
197194
198195 Base64-encoded document data.
199196
from line 198
201198
202199 Base64-encoded document data.
203200
201 minLength: 1
202
204203 - `media_type: string`
205204
206205 MIME type of the document (e.g., "application/pdf").
207206
207 minLength: 1
208
208209 - `type: "base64"`
209210
210 - `"base64"`
211
212 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
211 - `BetaManagedAgentsPlainTextDocumentSource object`
213212
214213 Plain text document content.
215214
from line 216
217216
218217 The plain text content.
219218
219 minLength: 1
220
220221 - `media_type: "text/plain"`
221222
222223 MIME type of the text content. Must be "text/plain".
223224
224 - `"text/plain"`
225
226225 - `type: "text"`
227226
228 - `"text"`
229
230 - `BetaManagedAgentsURLDocumentSource object { type, url }`
227 - `BetaManagedAgentsURLDocumentSource object`
231228
232229 Document referenced by URL.
233230
234231 - `type: "url"`
235232
236 - `"url"`
237
238233 - `url: string`
239234
240235 URL of the document to fetch.
241236
242 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
237 minLength: 1
238
239 - `BetaManagedAgentsFileDocumentSource object`
243240
244241 Document referenced by file ID.
245242
from line 244
247244
248245 ID of a previously uploaded file.
249246
247 minLength: 1
248
250249 - `type: "file"`
251250
252 - `"file"`
253
254251 - `type: "document"`
255252
256 - `"document"`
257
258253 - `context: optional string or null`
259254
260255 Additional context about the document for the model.
from line 258
263258
264259 The title of the document.
265260
266 - `BetaManagedAgentsRedactedBlock object { type }`
261 - `BetaManagedAgentsRedactedBlock object`
267262
268263 Placeholder for content withheld by Anthropic model policy.
269264
270265 - `type: "redacted"`
271266
272 - `"redacted"`
273
274267 - `type: "user.message"`
275268
276 - `"user.message"`
277
278269 - `processed_at: optional string or null`
279270
280271 A timestamp in RFC 3339 format
281272
282 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
273 format: date-time
274
275 - `BetaManagedAgentsUserInterruptEvent object`
283276
284277 An interrupt event that pauses agent execution and returns control to the user.
285278
from line 282
289282
290283 - `type: "user.interrupt"`
291284
292 - `"user.interrupt"`
293
294285 - `processed_at: optional string or null`
295286
296287 A timestamp in RFC 3339 format
297288
289 format: date-time
290
298291 - `session_thread_id: optional string or null`
299292
300293 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
301294
302 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
295 - `BetaManagedAgentsUserToolConfirmationEvent object`
303296
304297 A tool confirmation event that approves or denies a pending tool execution.
305298
from line 314
321314
322315 - `type: "user.tool_confirmation"`
323316
324 - `"user.tool_confirmation"`
325
326317 - `deny_message: optional string or null`
327318
328319 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
329320
321 maxLength: 10000
322
330323 - `processed_at: optional string or null`
331324
332325 A timestamp in RFC 3339 format
333326
327 format: date-time
328
334329 - `session_thread_id: optional string or null`
335330
336331 When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.
337332
338 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
333 - `BetaManagedAgentsUserCustomToolResultEvent object`
339334
340335 Event sent by the client providing the result of a custom tool execution.
341336
from line 344
349344
350345 - `type: "user.custom_tool_result"`
351346
352 - `"user.custom_tool_result"`
353
354347 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
355348
356349 The result content returned by the tool.
357350
358 - `BetaManagedAgentsTextBlock object { text, type }`
351 - `BetaManagedAgentsTextBlock object`
359352
360353 Regular text content.
361354
362 - `BetaManagedAgentsImageBlock object { source, type }`
355 - `BetaManagedAgentsImageBlock object`
363356
364357 Image content specified directly as base64 data or as a reference via a URL.
365358
366 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
359 - `BetaManagedAgentsDocumentBlock object`
367360
368361 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
369362
370 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
363 - `BetaManagedAgentsSearchResultBlock object`
371364
372365 A block containing a web search result.
373366
from line 380
387380
388381 The text content.
389382
383 minLength: 1
384
390385 - `type: "text"`
391386
392 - `"text"`
393
394387 - `source: string`
395388
396389 The URL source of the search result.
397390
391 minLength: 1
392
398393 - `title: string`
399394
400395 The title of the search result.
401396
397 minLength: 1
398
402399 - `type: "search_result"`
403400
404 - `"search_result"`
405
406401 - `is_error: optional boolean or null`
407402
408403 Whether the tool execution resulted in an error.
from line 406
411406
412407 A timestamp in RFC 3339 format
413408
409 format: date-time
410
414411 - `session_thread_id: optional string or null`
415412
416413 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
417414
418 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
415 - `BetaManagedAgentsAgentCustomToolUseEvent object`
419416
420417 Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.
421418
from line 432
435432
436433 A timestamp in RFC 3339 format
437434
435 format: date-time
436
438437 - `type: "agent.custom_tool_use"`
439438
440 - `"agent.custom_tool_use"`
441
442439 - `session_thread_id: optional string or null`
443440
444441 When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.
445442
446 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
443 - `BetaManagedAgentsAgentMessageEvent object`
447444
448445 An agent response event in the session conversation.
449446
from line 452
455452
456453 Array of text blocks comprising the agent response.
457454
458 - `BetaManagedAgentsTextBlock object { text, type }`
455 - `BetaManagedAgentsTextBlock object`
459456
460457 Regular text content.
461458
462 - `BetaManagedAgentsRedactedBlock object { type }`
459 - `BetaManagedAgentsRedactedBlock object`
463460
464461 Placeholder for content withheld by Anthropic model policy.
465462
from line 464
467464
468465 A timestamp in RFC 3339 format
469466
467 format: date-time
468
470469 - `type: "agent.message"`
471470
472 - `"agent.message"`
473
474 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
471 - `BetaManagedAgentsAgentThinkingEvent object`
475472
476473 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
477474
from line 480
483480
484481 A timestamp in RFC 3339 format
485482
483 format: date-time
484
486485 - `type: "agent.thinking"`
487486
488 - `"agent.thinking"`
489
490 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
487 - `BetaManagedAgentsAgentMCPToolUseEvent object`
491488
492489 Event emitted when the agent invokes a tool provided by an MCP server.
493490
from line 508
511508
512509 A timestamp in RFC 3339 format
513510
511 format: date-time
512
514513 - `type: "agent.mcp_tool_use"`
515514
516 - `"agent.mcp_tool_use"`
517
518515 - `evaluated_permission: optional "allow" or "ask" or "deny"`
519516
520517 AgentEvaluatedPermission enum
from line 526
529526
530527 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
531528
532 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
529 - `BetaManagedAgentsAgentMCPToolResultEvent object`
533530
534531 Event representing the result of an MCP tool execution.
535532
from line 542
545542
546543 A timestamp in RFC 3339 format
547544
545 format: date-time
546
548547 - `type: "agent.mcp_tool_result"`
549548
550 - `"agent.mcp_tool_result"`
551
552549 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
553550
554551 The result content returned by the tool.
555552
556 - `BetaManagedAgentsTextBlock object { text, type }`
553 - `BetaManagedAgentsTextBlock object`
557554
558555 Regular text content.
559556
560 - `BetaManagedAgentsImageBlock object { source, type }`
557 - `BetaManagedAgentsImageBlock object`
561558
562559 Image content specified directly as base64 data or as a reference via a URL.
563560
564 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
561 - `BetaManagedAgentsDocumentBlock object`
565562
566563 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
567564
568 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
565 - `BetaManagedAgentsSearchResultBlock object`
569566
570567 A block containing a web search result.
571568
from line 570
573570
574571 Whether the tool execution resulted in an error.
575572
576 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
573 - `BetaManagedAgentsAgentToolUseEvent object`
577574
578575 Event emitted when the agent invokes a built-in agent tool.
579576
from line 590
593590
594591 A timestamp in RFC 3339 format
595592
593 format: date-time
594
596595 - `type: "agent.tool_use"`
597596
598 - `"agent.tool_use"`
599
600597 - `evaluated_permission: optional "allow" or "ask" or "deny"`
601598
602599 AgentEvaluatedPermission enum
from line 608
611608
612609 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
613610
614 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
611 - `BetaManagedAgentsAgentToolResultEvent object`
615612
616613 Event representing the result of an agent tool execution.
617614
from line 620
623620
624621 A timestamp in RFC 3339 format
625622
623 format: date-time
624
626625 - `tool_use_id: string`
627626
628627 The id of the `agent.tool_use` event this result corresponds to.
629628
630629 - `type: "agent.tool_result"`
631630
632 - `"agent.tool_result"`
633
634631 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
635632
636633 The result content returned by the tool.
637634
638 - `BetaManagedAgentsTextBlock object { text, type }`
635 - `BetaManagedAgentsTextBlock object`
639636
640637 Regular text content.
641638
642 - `BetaManagedAgentsImageBlock object { source, type }`
639 - `BetaManagedAgentsImageBlock object`
643640
644641 Image content specified directly as base64 data or as a reference via a URL.
645642
646 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
643 - `BetaManagedAgentsDocumentBlock object`
647644
648645 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
649646
650 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
647 - `BetaManagedAgentsSearchResultBlock object`
651648
652649 A block containing a web search result.
653650
from line 652
655652
656653 Whether the tool execution resulted in an error.
657654
658 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
655 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
659656
660657 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
661658
from line 664
667664
668665 Message content blocks.
669666
670 - `BetaManagedAgentsTextBlock object { text, type }`
667 - `BetaManagedAgentsTextBlock object`
671668
672669 Regular text content.
673670
674 - `BetaManagedAgentsImageBlock object { source, type }`
671 - `BetaManagedAgentsImageBlock object`
675672
676673 Image content specified directly as base64 data or as a reference via a URL.
677674
678 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
675 - `BetaManagedAgentsDocumentBlock object`
679676
680677 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
681678
682 - `BetaManagedAgentsRedactedBlock object { type }`
679 - `BetaManagedAgentsRedactedBlock object`
683680
684681 Placeholder for content withheld by Anthropic model policy.
685682
from line 688
691688
692689 A timestamp in RFC 3339 format
693690
691 format: date-time
692
694693 - `type: "agent.thread_message_received"`
695694
696 - `"agent.thread_message_received"`
697
698695 - `from_agent_name: optional string or null`
699696
700697 Name of the callable agent this message came from. Absent when received from the primary agent.
701698
702 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
699 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
703700
704701 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
705702
from line 708
711708
712709 Message content blocks.
713710
714 - `BetaManagedAgentsTextBlock object { text, type }`
711 - `BetaManagedAgentsTextBlock object`
715712
716713 Regular text content.
717714
718 - `BetaManagedAgentsImageBlock object { source, type }`
715 - `BetaManagedAgentsImageBlock object`
719716
720717 Image content specified directly as base64 data or as a reference via a URL.
721718
722 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
719 - `BetaManagedAgentsDocumentBlock object`
723720
724721 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
725722
726 - `BetaManagedAgentsRedactedBlock object { type }`
723 - `BetaManagedAgentsRedactedBlock object`
727724
728725 Placeholder for content withheld by Anthropic model policy.
729726
from line 728
731728
732729 A timestamp in RFC 3339 format
733730
731 format: date-time
732
734733 - `to_session_thread_id: string`
735734
736735 Public `sthr_` ID of the thread the message was sent to.
737736
738737 - `type: "agent.thread_message_sent"`
739738
740 - `"agent.thread_message_sent"`
741
742739 - `to_agent_name: optional string or null`
743740
744741 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
745742
746 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
743 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
747744
748745 Indicates that context compaction (summarization) occurred during the session.
749746
from line 752
755752
756753 A timestamp in RFC 3339 format
757754
755 format: date-time
756
758757 - `type: "agent.thread_context_compacted"`
759758
760 - `"agent.thread_context_compacted"`
761
762 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
759 - `BetaManagedAgentsSessionErrorEvent object`
763760
764761 An error event indicating a problem occurred during session execution.
765762
from line 768
771768
772769 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
773770
774 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
771 - `BetaManagedAgentsUnknownError object`
775772
776773 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
777774
from line 780
783780
784781 What the client should do next in response to this error.
785782
786 - `BetaManagedAgentsRetryStatusRetrying object { type }`
783 - `BetaManagedAgentsRetryStatusRetrying object`
787784
788785 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
789786
790787 - `type: "retrying"`
791788
792 - `"retrying"`
793
794 - `BetaManagedAgentsRetryStatusExhausted object { type }`
789 - `BetaManagedAgentsRetryStatusExhausted object`
795790
796791 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
797792
798793 - `type: "exhausted"`
799794
800 - `"exhausted"`
801
802 - `BetaManagedAgentsRetryStatusTerminal object { type }`
795 - `BetaManagedAgentsRetryStatusTerminal object`
803796
804797 The session encountered a terminal error and will transition to `terminated` state.
805798
806799 - `type: "terminal"`
807800
808 - `"terminal"`
809
810801 - `type: "unknown_error"`
811802
812 - `"unknown_error"`
813
814 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
803 - `BetaManagedAgentsModelOverloadedError object`
815804
816805 The model is currently overloaded. Emitted after automatic retries are exhausted.
817806
from line 812
823812
824813 What the client should do next in response to this error.
825814
826 - `BetaManagedAgentsRetryStatusRetrying object { type }`
815 - `BetaManagedAgentsRetryStatusRetrying object`
827816
828817 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
829818
830 - `BetaManagedAgentsRetryStatusExhausted object { type }`
819 - `BetaManagedAgentsRetryStatusExhausted object`
831820
832821 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
833822
834 - `BetaManagedAgentsRetryStatusTerminal object { type }`
823 - `BetaManagedAgentsRetryStatusTerminal object`
835824
836825 The session encountered a terminal error and will transition to `terminated` state.
837826
838827 - `type: "model_overloaded_error"`
839828
840 - `"model_overloaded_error"`
841
842 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
829 - `BetaManagedAgentsModelRateLimitedError object`
843830
844831 The model request was rate-limited.
845832
from line 838
851838
852839 What the client should do next in response to this error.
853840
854 - `BetaManagedAgentsRetryStatusRetrying object { type }`
841 - `BetaManagedAgentsRetryStatusRetrying object`
855842
856843 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
857844
858 - `BetaManagedAgentsRetryStatusExhausted object { type }`
845 - `BetaManagedAgentsRetryStatusExhausted object`
859846
860847 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
861848
862 - `BetaManagedAgentsRetryStatusTerminal object { type }`
849 - `BetaManagedAgentsRetryStatusTerminal object`
863850
864851 The session encountered a terminal error and will transition to `terminated` state.
865852
866853 - `type: "model_rate_limited_error"`
867854
868 - `"model_rate_limited_error"`
869
870 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
855 - `BetaManagedAgentsModelRequestFailedError object`
871856
872857 A model request failed for a reason other than overload or rate-limiting.
873858
from line 864
879864
880865 What the client should do next in response to this error.
881866
882 - `BetaManagedAgentsRetryStatusRetrying object { type }`
867 - `BetaManagedAgentsRetryStatusRetrying object`
883868
884869 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
885870
886 - `BetaManagedAgentsRetryStatusExhausted object { type }`
871 - `BetaManagedAgentsRetryStatusExhausted object`
887872
888873 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
889874
890 - `BetaManagedAgentsRetryStatusTerminal object { type }`
875 - `BetaManagedAgentsRetryStatusTerminal object`
891876
892877 The session encountered a terminal error and will transition to `terminated` state.
893878
894879 - `type: "model_request_failed_error"`
895880
896 - `"model_request_failed_error"`
897
898 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
881 - `BetaManagedAgentsMCPConnectionFailedError object`
899882
900883 Failed to connect to an MCP server.
901884
from line 894
911894
912895 What the client should do next in response to this error.
913896
914 - `BetaManagedAgentsRetryStatusRetrying object { type }`
897 - `BetaManagedAgentsRetryStatusRetrying object`
915898
916899 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
917900
918 - `BetaManagedAgentsRetryStatusExhausted object { type }`
901 - `BetaManagedAgentsRetryStatusExhausted object`
919902
920903 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
921904
922 - `BetaManagedAgentsRetryStatusTerminal object { type }`
905 - `BetaManagedAgentsRetryStatusTerminal object`
923906
924907 The session encountered a terminal error and will transition to `terminated` state.
925908
926909 - `type: "mcp_connection_failed_error"`
927910
928 - `"mcp_connection_failed_error"`
929
930 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
911 - `BetaManagedAgentsMCPAuthenticationFailedError object`
931912
932913 Authentication to an MCP server failed.
933914
from line 924
943924
944925 What the client should do next in response to this error.
945926
946 - `BetaManagedAgentsRetryStatusRetrying object { type }`
927 - `BetaManagedAgentsRetryStatusRetrying object`
947928
948929 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
949930
950 - `BetaManagedAgentsRetryStatusExhausted object { type }`
931 - `BetaManagedAgentsRetryStatusExhausted object`
951932
952933 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
953934
954 - `BetaManagedAgentsRetryStatusTerminal object { type }`
935 - `BetaManagedAgentsRetryStatusTerminal object`
955936
956937 The session encountered a terminal error and will transition to `terminated` state.
957938
958939 - `type: "mcp_authentication_failed_error"`
959940
960 - `"mcp_authentication_failed_error"`
961
962 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
941 - `BetaManagedAgentsBillingError object`
963942
964943 The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
965944
from line 950
971950
972951 What the client should do next in response to this error.
973952
974 - `BetaManagedAgentsRetryStatusRetrying object { type }`
953 - `BetaManagedAgentsRetryStatusRetrying object`
975954
976955 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
977956
978 - `BetaManagedAgentsRetryStatusExhausted object { type }`
957 - `BetaManagedAgentsRetryStatusExhausted object`
979958
980959 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
981960
982 - `BetaManagedAgentsRetryStatusTerminal object { type }`
961 - `BetaManagedAgentsRetryStatusTerminal object`
983962
984963 The session encountered a terminal error and will transition to `terminated` state.
985964
986965 - `type: "billing_error"`
987966
988 - `"billing_error"`
989
990 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
967 - `BetaManagedAgentsCredentialHostUnreachableError object`
991968
992969 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
993970
from line 980
1003980
1004981 What the client should do next in response to this error.
1005982
1006 - `BetaManagedAgentsRetryStatusRetrying object { type }`
983 - `BetaManagedAgentsRetryStatusRetrying object`
1007984
1008985 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
1009986
1010 - `BetaManagedAgentsRetryStatusExhausted object { type }`
987 - `BetaManagedAgentsRetryStatusExhausted object`
1011988
1012989 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1013990
1014 - `BetaManagedAgentsRetryStatusTerminal object { type }`
991 - `BetaManagedAgentsRetryStatusTerminal object`
1015992
1016993 The session encountered a terminal error and will transition to `terminated` state.
1017994
1018995 - `type: "credential_host_unreachable_error"`
1019996
1020 - `"credential_host_unreachable_error"`
1021
1022997 - `vault_id: string`
1023998
1024999 ID of the vault containing the affected credential.
from line 1002
10271002
10281003 A timestamp in RFC 3339 format
10291004
1005 format: date-time
1006
10301007 - `type: "session.error"`
10311008
1032 - `"session.error"`
1033
1034 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
1009 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
10351010
10361011 Indicates the session is recovering from an error state and is rescheduled for execution.
10371012
from line 1018
10431018
10441019 A timestamp in RFC 3339 format
10451020
1021 format: date-time
1022
10461023 - `type: "session.status_rescheduled"`
10471024
1048 - `"session.status_rescheduled"`
1049
1050 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
1025 - `BetaManagedAgentsSessionStatusRunningEvent object`
10511026
10521027 Indicates the session is actively running and the agent is working.
10531028
from line 1034
10591034
10601035 A timestamp in RFC 3339 format
10611036
1037 format: date-time
1038
10621039 - `type: "session.status_running"`
10631040
1064 - `"session.status_running"`
1065
1066 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
1041 - `BetaManagedAgentsSessionStatusIdleEvent object`
10671042
10681043 Indicates the agent has paused and is awaiting user input.
10691044
from line 1050
10751050
10761051 A timestamp in RFC 3339 format
10771052
1053 format: date-time
1054
10781055 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
10791056
10801057 The agent completed its turn naturally and is ready for the next user message.
10811058
1082 - `BetaManagedAgentsSessionEndTurn object { type }`
1059 - `BetaManagedAgentsSessionEndTurn object`
10831060
10841061 The agent completed its turn naturally and is ready for the next user message.
10851062
10861063 - `type: "end_turn"`
10871064
1088 - `"end_turn"`
1089
1090 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1065 - `BetaManagedAgentsSessionRequiresAction object`
10911066
10921067 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
10931068
from line 1072
10971072
10981073 - `type: "requires_action"`
10991074
1100 - `"requires_action"`
1101
1102 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1075 - `BetaManagedAgentsSessionRetriesExhausted object`
11031076
11041077 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
11051078
11061079 - `type: "retries_exhausted"`
11071080
1108 - `"retries_exhausted"`
1109
1110 - `BetaManagedAgentsSessionBudgetReached object { type }`
1081 - `BetaManagedAgentsSessionBudgetReached object`
11111082
11121083 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
11131084
11141085 - `type: "budget_reached"`
11151086
1116 - `"budget_reached"`
1117
11181087 - `type: "session.status_idle"`
11191088
1120 - `"session.status_idle"`
1121
1122 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
1089 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
11231090
11241091 Indicates the session has terminated, either due to an error or completion.
11251092
from line 1098
11311098
11321099 A timestamp in RFC 3339 format
11331100
1101 format: date-time
1102
11341103 - `type: "session.status_terminated"`
11351104
1136 - `"session.status_terminated"`
1137
1138 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
1105 - `BetaManagedAgentsSessionThreadCreatedEvent object`
11391106
11401107 Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
11411108
from line 1118
11511118
11521119 A timestamp in RFC 3339 format
11531120
1121 format: date-time
1122
11541123 - `session_thread_id: string`
11551124
11561125 Public `sthr_` ID of the newly created thread.
11571126
11581127 - `type: "session.thread_created"`
11591128
1160 - `"session.thread_created"`
1161
1162 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
1129 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
11631130
11641131 Emitted when an outcome evaluation cycle begins.
11651132
from line 1138
11711138
11721139 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
11731140
1141 format: int32
1142
11741143 - `outcome_id: string`
11751144
11761145 The `outc_` ID of the outcome being evaluated.
from line 1148
11791148
11801149 A timestamp in RFC 3339 format
11811150
1151 format: date-time
1152
11821153 - `type: "span.outcome_evaluation_start"`
11831154
1184 - `"span.outcome_evaluation_start"`
1185
1186 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
1155 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
11871156
11881157 Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.
11891158
from line 1168
11991168
12001169 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
12011170
1171 format: int32
1172
12021173 - `outcome_evaluation_start_id: string`
12031174
12041175 The id of the corresponding `span.outcome_evaluation_start` event.
from line 1182
12111182
12121183 A timestamp in RFC 3339 format
12131184
1185 format: date-time
1186
12141187 - `result: string`
12151188
12161189 Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
12171190
12181191 - `type: "span.outcome_evaluation_end"`
12191192
1220 - `"span.outcome_evaluation_end"`
1221
12221193 - `usage: BetaManagedAgentsSpanModelUsage`
12231194
12241195 Token usage for a single model request.
from line 1198
12271198
12281199 Tokens used to create prompt cache in this request.
12291200
1201 format: int32
1202
12301203 - `cache_read_input_tokens: number`
12311204
12321205 Tokens read from prompt cache in this request.
12331206
1207 format: int32
1208
12341209 - `input_tokens: number`
12351210
12361211 Input tokens consumed by this request.
12371212
1213 format: int32
1214
12381215 - `output_tokens: number`
12391216
12401217 Output tokens generated by this request.
12411218
1219 format: int32
1220
12421221 - `speed: optional "standard" or "fast" or null`
12431222
12441223 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1226
12471226
12481227 - `"fast"`
12491228
1250 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
1229 - `BetaManagedAgentsSpanModelRequestStartEvent object`
12511230
12521231 Emitted when a model request is initiated by the agent.
12531232
from line 1238
12591238
12601239 A timestamp in RFC 3339 format
12611240
1241 format: date-time
1242
12621243 - `type: "span.model_request_start"`
12631244
1264 - `"span.model_request_start"`
1265
1266 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
1245 - `BetaManagedAgentsSpanModelRequestEndEvent object`
12671246
12681247 Emitted when a model request completes.
12691248
from line 1266
12871266
12881267 A timestamp in RFC 3339 format
12891268
1269 format: date-time
1270
12901271 - `type: "span.model_request_end"`
12911272
1292 - `"span.model_request_end"`
1293
1294 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
1273 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
12951274
12961275 Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.
12971276
from line 1282
13031282
13041283 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
13051284
1285 format: int32
1286
13061287 - `outcome_id: string`
13071288
13081289 The `outc_` ID of the outcome being evaluated.
from line 1292
13111292
13121293 A timestamp in RFC 3339 format
13131294
1295 format: date-time
1296
13141297 - `type: "span.outcome_evaluation_ongoing"`
13151298
1316 - `"span.outcome_evaluation_ongoing"`
1317
1318 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
1299 - `BetaManagedAgentsUserDefineOutcomeEvent object`
13191300
13201301 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
13211302
from line 1312
13311312
13321313 Evaluate-then-revise cycles before giving up. Default 3, max 20.
13331314
1315 format: int32
1316
13341317 - `outcome_id: string`
13351318
13361319 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1322
13391322
13401323 A timestamp in RFC 3339 format
13411324
1325 format: date-time
1326
13421327 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
13431328
13441329 Rubric for grading the quality of an outcome.
13451330
1346 - `BetaManagedAgentsFileRubric object { file_id, type }`
1331 - `BetaManagedAgentsFileRubric object`
13471332
13481333 Rubric referenced by a file uploaded via the Files API.
13491334
from line 1338
13531338
13541339 - `type: "file"`
13551340
1356 - `"file"`
1357
1358 - `BetaManagedAgentsTextRubric object { content, type }`
1341 - `BetaManagedAgentsTextRubric object`
13591342
13601343 Rubric content provided inline as text.
13611344
from line 1348
13651348
13661349 - `type: "text"`
13671350
1368 - `"text"`
1369
13701351 - `type: "user.define_outcome"`
13711352
1372 - `"user.define_outcome"`
1373
1374 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
1353 - `BetaManagedAgentsSessionDeletedEvent object`
13751354
13761355 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
13771356
from line 1362
13831362
13841363 A timestamp in RFC 3339 format
13851364
1365 format: date-time
1366
13861367 - `type: "session.deleted"`
13871368
1388 - `"session.deleted"`
1389
1390 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
1369 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
13911370
13921371 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
13931372
from line 1382
14031382
14041383 A timestamp in RFC 3339 format
14051384
1385 format: date-time
1386
14061387 - `session_thread_id: string`
14071388
14081389 Public sthr_ ID of the thread that started running.
14091390
14101391 - `type: "session.thread_status_running"`
14111392
1412 - `"session.thread_status_running"`
1413
1414 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
1393 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
14151394
14161395 A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14171396
from line 1406
14271406
14281407 A timestamp in RFC 3339 format
14291408
1409 format: date-time
1410
14301411 - `session_thread_id: string`
14311412
14321413 Public sthr_ ID of the thread that went idle.
from line 1416
14351416
14361417 The agent completed its turn naturally and is ready for the next user message.
14371418
1438 - `BetaManagedAgentsSessionEndTurn object { type }`
1419 - `BetaManagedAgentsSessionEndTurn object`
14391420
14401421 The agent completed its turn naturally and is ready for the next user message.
14411422
1442 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1423 - `BetaManagedAgentsSessionRequiresAction object`
14431424
14441425 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
14451426
1446 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1427 - `BetaManagedAgentsSessionRetriesExhausted object`
14471428
14481429 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
14491430
1450 - `BetaManagedAgentsSessionBudgetReached object { type }`
1431 - `BetaManagedAgentsSessionBudgetReached object`
14511432
14521433 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
14531434
14541435 - `type: "session.thread_status_idle"`
14551436
1456 - `"session.thread_status_idle"`
1457
1458 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
1437 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
14591438
14601439 A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14611440
from line 1450
14711450
14721451 A timestamp in RFC 3339 format
14731452
1453 format: date-time
1454
14741455 - `session_thread_id: string`
14751456
14761457 Public sthr_ ID of the thread that terminated.
14771458
14781459 - `type: "session.thread_status_terminated"`
14791460
1480 - `"session.thread_status_terminated"`
1481
1482 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
1461 - `BetaManagedAgentsUserToolResultEvent object`
14831462
14841463 Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.
14851464
from line 1472
14931472
14941473 - `type: "user.tool_result"`
14951474
1496 - `"user.tool_result"`
1497
14981475 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
14991476
15001477 The result content returned by the tool.
15011478
1502 - `BetaManagedAgentsTextBlock object { text, type }`
1479 - `BetaManagedAgentsTextBlock object`
15031480
15041481 Regular text content.
15051482
1506 - `BetaManagedAgentsImageBlock object { source, type }`
1483 - `BetaManagedAgentsImageBlock object`
15071484
15081485 Image content specified directly as base64 data or as a reference via a URL.
15091486
1510 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1487 - `BetaManagedAgentsDocumentBlock object`
15111488
15121489 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
15131490
1514 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
1491 - `BetaManagedAgentsSearchResultBlock object`
15151492
15161493 A block containing a web search result.
15171494
from line 1500
15231500
15241501 A timestamp in RFC 3339 format
15251502
1503 format: date-time
1504
15261505 - `session_thread_id: optional string or null`
15271506
15281507 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
15291508
1530 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
1509 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
15311510
15321511 A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
15331512
from line 1522
15431522
15441523 A timestamp in RFC 3339 format
15451524
1525 format: date-time
1526
15461527 - `session_thread_id: string`
15471528
15481529 Public sthr_ ID of the thread that is retrying.
15491530
15501531 - `type: "session.thread_status_rescheduled"`
15511532
1552 - `"session.thread_status_rescheduled"`
1553
1554 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
1533 - `BetaManagedAgentsSessionUpdatedEvent object`
15551534
15561535 Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
15571536
from line 1542
15631542
15641543 A timestamp in RFC 3339 format
15651544
1545 format: date-time
1546
15661547 - `type: "session.updated"`
15671548
1568 - `"session.updated"`
1569
15701549 - `agent: optional BetaManagedAgentsSessionAgent or null`
15711550
15721551 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1560
15811560
15821561 - `type: "url"`
15831562
1584 - `"url"`
1585
15861563 - `url: string`
15871564
15881565 - `model: BetaManagedAgentsModelConfig`
from line 1636
16591636
16601637 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16611638
1662 - `BetaManagedAgentsEffortLow object { type }`
1639 - `BetaManagedAgentsEffortLow object`
16631640
16641641 Low effort. Favors latency over reasoning depth.
16651642
16661643 - `type: "low"`
16671644
1668 - `"low"`
1669
1670 - `BetaManagedAgentsEffortMedium object { type }`
1645 - `BetaManagedAgentsEffortMedium object`
16711646
16721647 Medium effort. Balances latency and reasoning depth.
16731648
16741649 - `type: "medium"`
16751650
1676 - `"medium"`
1677
1678 - `BetaManagedAgentsEffortHigh object { type }`
1651 - `BetaManagedAgentsEffortHigh object`
16791652
16801653 High effort. Favors reasoning depth.
16811654
16821655 - `type: "high"`
16831656
1684 - `"high"`
1685
1686 - `BetaManagedAgentsEffortXhigh object { type }`
1657 - `BetaManagedAgentsEffortXhigh object`
16871658
16881659 Extra-high effort. Not all models accept this level.
16891660
16901661 - `type: "xhigh"`
16911662
1692 - `"xhigh"`
1693
1694 - `BetaManagedAgentsEffortMax object { type }`
1663 - `BetaManagedAgentsEffortMax object`
16951664
16961665 Maximum effort. Favors reasoning depth over latency.
16971666
16981667 - `type: "max"`
16991668
1700 - `"max"`
1701
17021669 - `inference_geo: optional string`
17031670
17041671 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1686
17191686
17201687 Full `agent` definitions the coordinator may spawn as session threads.
17211688
1722 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1689 - `BetaManagedAgentsSessionThreadAgent object`
17231690
17241691 Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.
17251692
from line 1710
17431710
17441711 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17451712
1746 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1713 - `BetaManagedAgentsAnthropicSkill object`
17471714
17481715 A resolved Anthropic-managed skill.
17491716
from line 1718
17511718
17521719 - `type: "anthropic"`
17531720
1754 - `"anthropic"`
1755
17561721 - `version: string`
17571722
1758 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1723 - `BetaManagedAgentsCustomSkill object`
17591724
17601725 A resolved user-created custom skill.
17611726
from line 1728
17631728
17641729 - `type: "custom"`
17651730
1766 - `"custom"`
1767
17681731 - `version: string`
17691732
17701733 - `system: string or null`
17711734
17721735 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17731736
1774 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1737 - `BetaManagedAgentsAgentToolset20260401 object`
17751738
17761739 - `configs: array of BetaManagedAgentsAgentToolConfig`
17771740
1778 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1741 - `BetaManagedAgentsBashToolConfig object`
17791742
17801743 Configuration for the bash tool.
17811744
from line 1746
17831746
17841747 - `name: "bash"`
17851748
1786 - `"bash"`
1787
17881749 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
17891750
17901751 Permission policy for tool execution.
17911752
1792 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1753 - `BetaManagedAgentsAlwaysAllowPolicy object`
17931754
17941755 Tool calls are automatically approved without user confirmation.
17951756
17961757 - `type: "always_allow"`
17971758
1798 - `"always_allow"`
1799
1800 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1759 - `BetaManagedAgentsAlwaysAskPolicy object`
18011760
18021761 Tool calls require user confirmation before execution.
18031762
18041763 - `type: "always_ask"`
18051764
1806 - `"always_ask"`
1807
18081765 - `type: "bash"`
18091766
1810 - `"bash"`
1811
1812 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1767 - `BetaManagedAgentsEditToolConfig object`
18131768
18141769 Configuration for the edit tool.
18151770
from line 1772
18171772
18181773 - `name: "edit"`
18191774
1820 - `"edit"`
1821
18221775 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18231776
18241777 Permission policy for tool execution.
18251778
1826 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1779 - `BetaManagedAgentsAlwaysAllowPolicy object`
18271780
18281781 Tool calls are automatically approved without user confirmation.
18291782
1830 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1783 - `BetaManagedAgentsAlwaysAskPolicy object`
18311784
18321785 Tool calls require user confirmation before execution.
18331786
18341787 - `type: "edit"`
18351788
1836 - `"edit"`
1837
1838 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1789 - `BetaManagedAgentsReadToolConfig object`
18391790
18401791 Configuration for the read tool.
18411792
from line 1794
18431794
18441795 - `name: "read"`
18451796
1846 - `"read"`
1847
18481797 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18491798
18501799 Permission policy for tool execution.
18511800
1852 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1801 - `BetaManagedAgentsAlwaysAllowPolicy object`
18531802
18541803 Tool calls are automatically approved without user confirmation.
18551804
1856 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1805 - `BetaManagedAgentsAlwaysAskPolicy object`
18571806
18581807 Tool calls require user confirmation before execution.
18591808
18601809 - `type: "read"`
18611810
1862 - `"read"`
1863
1864 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1811 - `BetaManagedAgentsWriteToolConfig object`
18651812
18661813 Configuration for the write tool.
18671814
from line 1816
18691816
18701817 - `name: "write"`
18711818
1872 - `"write"`
1873
18741819 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18751820
18761821 Permission policy for tool execution.
18771822
1878 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1823 - `BetaManagedAgentsAlwaysAllowPolicy object`
18791824
18801825 Tool calls are automatically approved without user confirmation.
18811826
1882 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1827 - `BetaManagedAgentsAlwaysAskPolicy object`
18831828
18841829 Tool calls require user confirmation before execution.
18851830
18861831 - `type: "write"`
18871832
1888 - `"write"`
1889
1890 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1833 - `BetaManagedAgentsGlobToolConfig object`
18911834
18921835 Configuration for the glob tool.
18931836
from line 1838
18951838
18961839 - `name: "glob"`
18971840
1898 - `"glob"`
1899
19001841 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19011842
19021843 Permission policy for tool execution.
19031844
1904 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1845 - `BetaManagedAgentsAlwaysAllowPolicy object`
19051846
19061847 Tool calls are automatically approved without user confirmation.
19071848
1908 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1849 - `BetaManagedAgentsAlwaysAskPolicy object`
19091850
19101851 Tool calls require user confirmation before execution.
19111852
19121853 - `type: "glob"`
19131854
1914 - `"glob"`
1915
1916 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1855 - `BetaManagedAgentsGrepToolConfig object`
19171856
19181857 Configuration for the grep tool.
19191858
from line 1860
19211860
19221861 - `name: "grep"`
19231862
1924 - `"grep"`
1925
19261863 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19271864
19281865 Permission policy for tool execution.
19291866
1930 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1867 - `BetaManagedAgentsAlwaysAllowPolicy object`
19311868
19321869 Tool calls are automatically approved without user confirmation.
19331870
1934 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1871 - `BetaManagedAgentsAlwaysAskPolicy object`
19351872
19361873 Tool calls require user confirmation before execution.
19371874
19381875 - `type: "grep"`
19391876
1940 - `"grep"`
1941
1942 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1877 - `BetaManagedAgentsWebFetchToolConfig object`
19431878
19441879 Configuration for the web_fetch tool.
19451880
from line 1882
19471882
19481883 - `name: "web_fetch"`
19491884
1950 - `"web_fetch"`
1951
19521885 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19531886
19541887 Permission policy for tool execution.
19551888
1956 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1889 - `BetaManagedAgentsAlwaysAllowPolicy object`
19571890
19581891 Tool calls are automatically approved without user confirmation.
19591892
1960 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1893 - `BetaManagedAgentsAlwaysAskPolicy object`
19611894
19621895 Tool calls require user confirmation before execution.
19631896
19641897 - `type: "web_fetch"`
19651898
1966 - `"web_fetch"`
1967
19681899 - `allowed_domains: optional array of string`
19691900
19701901 - `blocked_domains: optional array of string`
19711902
19721903 - `max_content_tokens: optional number or null`
19731904
1974 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1905 format: int32
1906
1907 - `BetaManagedAgentsWebSearchToolConfig object`
19751908
19761909 Configuration for the web_search tool.
19771910
from line 1912
19791912
19801913 - `name: "web_search"`
19811914
1982 - `"web_search"`
1983
19841915 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19851916
19861917 Permission policy for tool execution.
19871918
1988 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1919 - `BetaManagedAgentsAlwaysAllowPolicy object`
19891920
19901921 Tool calls are automatically approved without user confirmation.
19911922
1992 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1923 - `BetaManagedAgentsAlwaysAskPolicy object`
19931924
19941925 Tool calls require user confirmation before execution.
19951926
19961927 - `type: "web_search"`
19971928
1998 - `"web_search"`
1999
20001929 - `allowed_domains: optional array of string`
20011930
20021931 - `blocked_domains: optional array of string`
from line 1938
20091938
20101939 Location precision. Only "approximate" is supported.
20111940
2012 - `"approximate"`
2013
20141941 - `city: optional string or null`
20151942
20161943 City name.
20171944
1945 minLength: 1, maxLength: 255
1946
20181947 - `country: optional string or null`
20191948
20201949 Two-letter ISO 3166-1 country code, uppercase.
from line 1952
20231952
20241953 Region or state name.
20251954
1955 minLength: 1, maxLength: 255
1956
20261957 - `timezone: optional string or null`
20271958
20281959 IANA timezone identifier, e.g. "America/Los_Angeles".
20291960
1961 minLength: 1, maxLength: 255
1962
20301963 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20311964
20321965 Resolved default configuration for agent tools.
from line 1970
20371970
20381971 Permission policy for tool execution.
20391972
2040 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1973 - `BetaManagedAgentsAlwaysAllowPolicy object`
20411974
20421975 Tool calls are automatically approved without user confirmation.
20431976
2044 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1977 - `BetaManagedAgentsAlwaysAskPolicy object`
20451978
20461979 Tool calls require user confirmation before execution.
20471980
20481981 - `type: "agent_toolset_20260401"`
20491982
2050 - `"agent_toolset_20260401"`
2051
2052 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1983 - `BetaManagedAgentsMCPToolset object`
20531984
20541985 - `configs: array of BetaManagedAgentsMCPToolConfig`
20551986
from line 1992
20611992
20621993 Permission policy for tool execution.
20631994
2064 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1995 - `BetaManagedAgentsAlwaysAllowPolicy object`
20651996
20661997 Tool calls are automatically approved without user confirmation.
20671998
2068 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1999 - `BetaManagedAgentsAlwaysAskPolicy object`
20692000
20702001 Tool calls require user confirmation before execution.
20712002
from line 2010
20792010
20802011 Permission policy for tool execution.
20812012
2082 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2013 - `BetaManagedAgentsAlwaysAllowPolicy object`
20832014
20842015 Tool calls are automatically approved without user confirmation.
20852016
2086 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2017 - `BetaManagedAgentsAlwaysAskPolicy object`
20872018
20882019 Tool calls require user confirmation before execution.
20892020
from line 2022
20912022
20922023 - `type: "mcp_toolset"`
20932024
2094 - `"mcp_toolset"`
2095
2096 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2025 - `BetaManagedAgentsCustomTool object`
20972026
20982027 A custom tool as returned in API responses.
20992028
from line 2034
21052034
21062035 - `type: "object"`
21072036
2108 - `"object"`
2109
21102037 - `properties: optional map[unknown] or null`
21112038
21122039 - `required: optional array of string or null`
from line 2042
21152042
21162043 - `type: "custom"`
21172044
2118 - `"custom"`
2119
21202045 - `type: "agent"`
21212046
2122 - `"agent"`
2123
21242047 - `version: number`
21252048
2126 - `BetaManagedAgentsAdvisor object { model, type }`
2049 format: int32
2050
2051 - `BetaManagedAgentsAdvisor object`
21272052
21282053 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
21292054
from line 2058
21332058
21342059 - `type: "advisor"`
21352060
2136 - `"advisor"`
2137
21382061 - `type: "coordinator"`
21392062
2140 - `"coordinator"`
2141
21422063 - `name: string`
21432064
21442065 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
21452066
2146 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2067 - `BetaManagedAgentsAnthropicSkill object`
21472068
21482069 A resolved Anthropic-managed skill.
21492070
2150 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2071 - `BetaManagedAgentsCustomSkill object`
21512072
21522073 A resolved user-created custom skill.
21532074
from line 2076
21552076
21562077 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
21572078
2158 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2159
2160 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2161
2162 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2079 - `BetaManagedAgentsAgentToolset20260401 object`
2080
2081 - `BetaManagedAgentsMCPToolset object`
2082
2083 - `BetaManagedAgentsCustomTool object`
21632084
21642085 A custom tool as returned in API responses.
21652086
21662087 - `type: "agent"`
21672088
2168 - `"agent"`
2169
21702089 - `version: number`
21712090
2091 format: int32
2092
21722093 - `budget: optional BetaManagedAgentsBudgetLimit or null`
21732094
21742095 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2106
21852106
21862107 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
21872108
2188 - `"USD"`
2189
21902109 - `type: "limit"`
21912110
2192 - `"limit"`
2193
21942111 - `metadata: optional map[string]`
21952112
21962113 The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
from line 2116
21992116
22002117 The session's new title. Present only when the update changed it.
22012118
2202 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
2119 - `BetaManagedAgentsSystemMessageEvent object`
22032120
22042121 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
22052122
from line 2132
22152132
22162133 The text content.
22172134
2135 minLength: 1
2136
22182137 - `type: "text"`
22192138
2220 - `"text"`
2221
22222139 - `type: "system.message"`
22232140
2224 - `"system.message"`
2225
22262141 - `processed_at: optional string or null`
22272142
22282143 A timestamp in RFC 3339 format
22292144
2230 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
2145 format: date-time
2146
2147 - `BetaManagedAgentsSessionUsageEvent object`
22312148
22322149 Periodic snapshot of the session's cumulative usage and tracked list cost.
22332150
from line 2156
22392156
22402157 A timestamp in RFC 3339 format
22412158
2159 format: date-time
2160
22422161 - `type: "session.usage"`
22432162
2244 - `"session.usage"`
2245
22462163 - `usage: BetaManagedAgentsSessionUsageSnapshot`
22472164
22482165 Point-in-time snapshot of a session's cumulative usage.
from line 2168
22512168
22522169 Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
22532170
2171 format: double
2172
22542173 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
22552174
22562175 Prompt-cache creation token usage broken down by cache lifetime.
from line 2178
22592178
22602179 Tokens used to create 1-hour ephemeral cache entries.
22612180
2181 format: int32
2182
22622183 - `ephemeral_5m_input_tokens: optional number`
22632184
22642185 Tokens used to create 5-minute ephemeral cache entries.
22652186
2187 format: int32
2188
22662189 - `cache_read_input_tokens: optional number`
22672190
22682191 Total tokens read from prompt cache.
22692192
2193 format: int32
2194
22702195 - `input_tokens: optional number`
22712196
22722197 Total input tokens consumed across all turns.
22732198
2199 format: int32
2200
22742201 - `list_cost: optional BetaMonetaryAmount`
22752202
22762203 A monetary amount in a specific currency.
from line 2206
22792206
22802207 Total output tokens generated across all turns.
22812208
2209 format: int32
2210
22822211 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
22832212
22842213 Cumulative count of server-executed tool invocations, broken down by tool.
from line 2216
22872216
22882217 Number of server-executed web fetch requests.
22892218
2219 format: int32
2220
22902221 - `web_search_requests: optional number`
22912222
22922223 Number of server-executed web search requests.
22932224
2225 format: int32
2226
22942227 - `budget: optional BetaManagedAgentsBudgetLimit or null`
22952228
22962229 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2232
22992232
23002233 Opaque cursor for the next page. Null when no more results.
23012234
2302### Example
2303
2304```http
2235## Example
2236
2237```bash
23052238curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events \
23062239 -H 'anthropic-version: 2023-06-01' \
23072240 -H 'anthropic-beta: managed-agents-2026-04-01' \
23082241 -H "X-Api-Key: $ANTHROPIC_API_KEY"
23092242```
23102243
2311#### Response
2244### Response (200)
23122245
23132246```json
23142247{
23152248
No line in this hunk matches that.