List Events changedapi/beta/sessions/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+328added
Lines−387removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits25to this page, all time
# List Events ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List 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 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
No line in this hunk matches that.