api/beta/sessions/threads/events/list / documentation change

The whole hunk

from line 1, old and new numbered

lines

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---

16# List Session Thread Events

38**GET** `/v1/sessions/{session_id}/threads/{thread_id}/events`

from line 35

3035

3136 - `string`

3237

33 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

38 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

3439

3540 - `"message-batches-2024-09-24"`

3641

from line 83

7883

7984 - `"user-profiles-2026-08-18"`

8085

86 - `"user-profiles-2026-09-04"`

8188 - `"advisor-tool-2026-03-01"`

8289

8390 - `"managed-agents-2026-04-01"`

from line 127

120127

121128 - `"mid-conversation-system-clear-at-2026-08-21"`

122129

130- `"anthropic-workspace-id": optional string`

131

123132## Returns

124133

125134- `data: optional array of BetaManagedAgentsSessionEvent`

from line 139

130139

131140 A user message event in the session conversation.

132141

142 - `type: "user.message"`

143

133144 - `id: string`

134145

135146 Unique identifier for this event.

from line 153

142153

143154 Regular text content.

144155

156 - `type: "text"`

157

145158 - `text: string`

146159

147160 The text content.

148161

149162 minLength: 1

150163

164 - `BetaManagedAgentsImageBlock object`

165

166 Image content specified directly as base64 data or as a reference via a URL.

167

168 - `type: "image"`

169

170 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

171

172 Union type for image source variants.

173

174 - `BetaManagedAgentsBase64ImageSource object`

175

176 Base64-encoded image data.

177

178 - `type: "base64"`

179

180 - `data: string`

181

182 Base64-encoded image data.

183

184 minLength: 1

185

186 - `media_type: string`

187

188 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

189

190 minLength: 1

191

192 - `BetaManagedAgentsURLImageSource object`

193

194 Image referenced by URL.

195

196 - `type: "url"`

197

198 - `url: string`

199

200 URL of the image to fetch.

201

202 minLength: 1

203

204 - `BetaManagedAgentsFileImageSource object`

205

206 Image referenced by file ID.

207

208 - `type: "file"`

209

210 - `file_id: string`

211

212 ID of a previously uploaded file.

213

214 minLength: 1

215

216 - `BetaManagedAgentsDocumentBlock object`

217

218 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

219

220 - `type: "document"`

221

222 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`

223

224 Union type for document source variants.

225

226 - `BetaManagedAgentsBase64DocumentSource object`

227

228 Base64-encoded document data.

229

230 - `type: "base64"`

231

232 - `data: string`

233

234 Base64-encoded document data.

235

236 minLength: 1

237

238 - `media_type: string`

239

240 MIME type of the document (e.g., "application/pdf").

241

242 minLength: 1

243

244 - `BetaManagedAgentsPlainTextDocumentSource object`

245

246 Plain text document content.

247

248 - `type: "text"`

249

250 - `data: string`

251

252 The plain text content.

253

254 minLength: 1

255

256 - `media_type: "text/plain"`

257

258 MIME type of the text content. Must be "text/plain".

259

260 - `BetaManagedAgentsURLDocumentSource object`

261

262 Document referenced by URL.

263

264 - `type: "url"`

265

266 - `url: string`

267

268 URL of the document to fetch.

269

270 minLength: 1

271

272 - `BetaManagedAgentsFileDocumentSource object`

273

274 Document referenced by file ID.

275

276 - `type: "file"`

277

278 - `file_id: string`

279

280 ID of a previously uploaded file.

281

282 minLength: 1

283

284 - `context: optional string or null`

285

286 Additional context about the document for the model.

287

288 - `title: optional string or null`

289

290 The title of the document.

291

292 - `BetaManagedAgentsRedactedBlock object`

293

294 Placeholder for content withheld by Anthropic model policy.

295

296 - `type: "redacted"`

297

298 - `processed_at: optional string or null`

299

300 A timestamp in RFC 3339 format

301

302 format: date-time

303

304 - `BetaManagedAgentsUserInterruptEvent object`

305

306 An interrupt event that pauses agent execution and returns control to the user.

307

308 - `type: "user.interrupt"`

309

310 - `id: string`

311

312 Unique identifier for this event.

313

314 - `processed_at: optional string or null`

315

316 A timestamp in RFC 3339 format

317

318 format: date-time

319

320 - `session_thread_id: optional string or null`

321

322 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.

323

324 - `BetaManagedAgentsUserToolConfirmationEvent object`

325

326 A tool confirmation event that approves or denies a pending tool execution.

327

328 - `type: "user.tool_confirmation"`

329

330 - `id: string`

331

332 Unique identifier for this event.

333

334 - `result: "allow" or "deny"`

335

336 UserToolConfirmationResult enum

337

338 - `"allow"`

339

340 - `"deny"`

341

342 - `tool_use_id: string`

343

344 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

345

346 - `deny_message: optional string or null`

347

348 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

349

350 maxLength: 10000

351

352 - `processed_at: optional string or null`

353

354 A timestamp in RFC 3339 format

355

356 format: date-time

357

358 - `session_thread_id: optional string or null`

359

360 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.

361

362 - `BetaManagedAgentsUserCustomToolResultEvent object`

363

364 Event sent by the client providing the result of a custom tool execution.

365

366 - `type: "user.custom_tool_result"`

367

368 - `id: string`

369

370 Unique identifier for this event.

371

372 - `custom_tool_use_id: string`

373

374 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

375

376 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

377

378 The result content returned by the tool.

379

380 - `BetaManagedAgentsTextBlock object`

381

382 Regular text content.

383

384 - `BetaManagedAgentsImageBlock object`

385

386 Image content specified directly as base64 data or as a reference via a URL.

387

388 - `BetaManagedAgentsDocumentBlock object`

389

390 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

391

392 - `BetaManagedAgentsSearchResultBlock object`

393

394 A block containing a web search result.

395

396 - `type: "search_result"`

397

398 - `citations: BetaManagedAgentsSearchResultCitations`

399

400 Citation settings for a search result.

401

402 - `enabled: boolean`

403

404 Whether citations are enabled for this search result.

405

406 - `content: array of BetaManagedAgentsSearchResultContent`

407

408 Array of text content blocks from the search result.

409

410 - `type: "text"`

411

412 - `text: string`

413

414 The text content.

415

416 minLength: 1

417

418 - `source: string`

419

420 The URL source of the search result.

421

422 minLength: 1

423

424 - `title: string`

425

426 The title of the search result.

427

428 minLength: 1

429

430 - `is_error: optional boolean or null`

431

432 Whether the tool execution resulted in an error.

433

434 - `processed_at: optional string or null`

435

436 A timestamp in RFC 3339 format

437

438 format: date-time

439

440 - `session_thread_id: optional string or null`

441

442 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

443

444 - `BetaManagedAgentsAgentCustomToolUseEvent object`

445

446 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.

447

448 - `type: "agent.custom_tool_use"`

449

450 - `id: string`

451

452 Unique identifier for this event.

453

454 - `input: map[unknown]`

455

456 Input parameters for the tool call.

457

458 - `name: string`

459

460 Name of the custom tool being called.

461

462 - `processed_at: string`

463

464 A timestamp in RFC 3339 format

465

466 format: date-time

467

468 - `session_thread_id: optional string or null`

469

470 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.

471

472 - `BetaManagedAgentsAgentMessageEvent object`

473

474 An agent response event in the session conversation.

475

476 - `type: "agent.message"`

477

478 - `id: string`

479

480 Unique identifier for this event.

481

482 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`

483

484 Array of text blocks comprising the agent response.

485

486 - `BetaManagedAgentsTextBlock object`

487

488 Regular text content.

489

490 - `BetaManagedAgentsRedactedBlock object`

491

492 Placeholder for content withheld by Anthropic model policy.

493

494 - `processed_at: string`

495

496 A timestamp in RFC 3339 format

497

498 format: date-time

499

500 - `BetaManagedAgentsAgentThinkingEvent object`

501

502 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

503

504 - `type: "agent.thinking"`

505

506 - `id: string`

507

508 Unique identifier for this event.

509

510 - `processed_at: string`

511

512 A timestamp in RFC 3339 format

513

514 format: date-time

515

516 - `BetaManagedAgentsAgentMCPToolUseEvent object`

517

518 Event emitted when the agent invokes a tool provided by an MCP server.

519

520 - `type: "agent.mcp_tool_use"`

521

522 - `id: string`

523

524 Unique identifier for this event.

525

526 - `input: map[unknown]`

527

528 Input parameters for the tool call.

529

530 - `mcp_server_name: string`

531

532 Name of the MCP server providing the tool.

533

534 - `name: string`

535

536 Name of the MCP tool being used.

537

538 - `processed_at: string`

539

540 A timestamp in RFC 3339 format

541

542 format: date-time

543

544 - `evaluated_permission: optional "allow" or "ask" or "deny"`

545

546 AgentEvaluatedPermission enum

547

548 - `"allow"`

549

550 - `"ask"`

551

552 - `"deny"`

553

554 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`

555

556 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.

557

558 - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object`

559

560 The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".

561

562 - `type: "always_allow"`

563

564 - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object`

565

566 The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".

567

568 - `type: "always_ask"`

569

570 - `BetaManagedAgentsAgentToolEvaluationAuto object`

571

572 The resolved permission_policy was auto: the server judged this invocation individually.

573

574 - `type: "auto"`

575

576 - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission`

577

578 The server's per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.

579

580 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object`

581

582 The server judged the invocation safe to execute without client approval.

583

584 - `type: "allow"`

585

586 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object`

587

588 The server reached no judgement; the invocation is held for client approval.

589

590 - `type: "ask"`

591

592 - `reason_code: string`

593

594 The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.

595

596 maxLength: 64

597

598 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object`

599

600 The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.

601

602 - `type: "deny"`

603

604 - `reason_code: string`

605

606 The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.

607

608 maxLength: 64

609

610 - `session_thread_id: optional string or null`

611

612 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.

613

614 - `BetaManagedAgentsAgentMCPToolResultEvent object`

615

616 Event representing the result of an MCP tool execution.

617

618 - `type: "agent.mcp_tool_result"`

619

620 - `id: string`

621

622 Unique identifier for this event.

623

624 - `mcp_tool_use_id: string`

625

626 The id of the `agent.mcp_tool_use` event this result corresponds to.

627

628 - `processed_at: string`

629

630 A timestamp in RFC 3339 format

631

632 format: date-time

633

634 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

635

636 The result content returned by the tool.

637

638 - `BetaManagedAgentsTextBlock object`

639

640 Regular text content.

641

642 - `BetaManagedAgentsImageBlock object`

643

644 Image content specified directly as base64 data or as a reference via a URL.

645

646 - `BetaManagedAgentsDocumentBlock object`

647

648 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

649

650 - `BetaManagedAgentsSearchResultBlock object`

651

652 A block containing a web search result.

653

654 - `is_error: optional boolean or null`

655

656 Whether the tool execution resulted in an error.

657

658 - `BetaManagedAgentsAgentToolUseEvent object`

659

660 Event emitted when the agent invokes a built-in agent tool.

661

662 - `type: "agent.tool_use"`

663

664 - `id: string`

665

666 Unique identifier for this event.

667

668 - `input: map[unknown]`

669

670 Input parameters for the tool call.

671

672 - `name: string`

673

674 Name of the agent tool being used.

675

676 - `processed_at: string`

677

678 A timestamp in RFC 3339 format

679

680 format: date-time

681

682 - `evaluated_permission: optional "allow" or "ask" or "deny"`

683

684 AgentEvaluatedPermission enum

685

686 - `"allow"`

687

688 - `"ask"`

689

690 - `"deny"`

691

692 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`

693

694 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.

695

696 - `session_thread_id: optional string or null`

697

698 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.

699

700 - `BetaManagedAgentsAgentToolResultEvent object`

701

702 Event representing the result of an agent tool execution.

703

704 - `type: "agent.tool_result"`

705

706 - `id: string`

707

708 Unique identifier for this event.

709

710 - `processed_at: string`

711

712 A timestamp in RFC 3339 format

713

714 format: date-time

715

716 - `tool_use_id: string`

717

718 The id of the `agent.tool_use` event this result corresponds to.

719

720 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

721

722 The result content returned by the tool.

723

724 - `BetaManagedAgentsTextBlock object`

725

726 Regular text content.

727

728 - `BetaManagedAgentsImageBlock object`

729

730 Image content specified directly as base64 data or as a reference via a URL.

731

732 - `BetaManagedAgentsDocumentBlock object`

733

734 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

735

736 - `BetaManagedAgentsSearchResultBlock object`

737

738 A block containing a web search result.

739

740 - `is_error: optional boolean or null`

741

742 Whether the tool execution resulted in an error.

743

744 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`

745

746 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

747

748 - `type: "agent.thread_message_received"`

749

750 - `id: string`

751

752 Unique identifier for this event.

753

754 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

755

756 Message content blocks.

757

758 - `BetaManagedAgentsTextBlock object`

759

760 Regular text content.

761

762 - `BetaManagedAgentsImageBlock object`

763

764 Image content specified directly as base64 data or as a reference via a URL.

765

766 - `BetaManagedAgentsDocumentBlock object`

767

768 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

769

770 - `BetaManagedAgentsRedactedBlock object`

771

772 Placeholder for content withheld by Anthropic model policy.

773

774 - `from_session_thread_id: string`

775

776 Public `sthr_` ID of the thread that sent the message.

777

778 - `processed_at: string`

779

780 A timestamp in RFC 3339 format

781

782 format: date-time

783

784 - `from_agent_name: optional string or null`

785

786 Name of the callable agent this message came from. Absent when received from the primary agent.

787

788 - `BetaManagedAgentsAgentThreadMessageSentEvent object`

789

790 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

791

792 - `type: "agent.thread_message_sent"`

793

794 - `id: string`

795

796 Unique identifier for this event.

797

798 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

799

800 Message content blocks.

801

802 - `BetaManagedAgentsTextBlock object`

803

804 Regular text content.

805

806 - `BetaManagedAgentsImageBlock object`

807

808 Image content specified directly as base64 data or as a reference via a URL.

809

810 - `BetaManagedAgentsDocumentBlock object`

811

812 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

813

814 - `BetaManagedAgentsRedactedBlock object`

815

816 Placeholder for content withheld by Anthropic model policy.

817

818 - `processed_at: string`

819

820 A timestamp in RFC 3339 format

821

822 format: date-time

823

824 - `to_session_thread_id: string`

825

826 Public `sthr_` ID of the thread the message was sent to.

827

828 - `to_agent_name: optional string or null`

829

830 Name of the callable agent this message was sent to. Absent when sent to the primary agent.

831

832 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`

833

834 Indicates that context compaction (summarization) occurred during the session.

835

836 - `type: "agent.thread_context_compacted"`

837

838 - `id: string`

839

840 Unique identifier for this event.

841

842 - `processed_at: string`

843

844 A timestamp in RFC 3339 format

845

846 format: date-time

847

848 - `BetaManagedAgentsSessionErrorEvent object`

849

850 An error event indicating a problem occurred during session execution.

851

852 - `type: "session.error"`

853

854 - `id: string`

855

856 Unique identifier for this event.

857

858 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`

859

860 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.

861

862 - `BetaManagedAgentsUnknownError object`

863

864 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.

865

866 - `type: "unknown_error"`

867

868 - `message: string`

869

870 Human-readable error description.

871

872 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

873

874 What the client should do next in response to this error.

875

876 - `BetaManagedAgentsRetryStatusRetrying object`

877

878 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.

879

880 - `type: "retrying"`

881

882 - `BetaManagedAgentsRetryStatusExhausted object`

883

884 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

885

886 - `type: "exhausted"`

887

888 - `BetaManagedAgentsRetryStatusTerminal object`

889

890 The session encountered a terminal error and will transition to `terminated` state.

891

892 - `type: "terminal"`

893

894 - `BetaManagedAgentsModelOverloadedError object`

895

896 The model is currently overloaded. Emitted after automatic retries are exhausted.

897

898 - `type: "model_overloaded_error"`

899

900 - `message: string`

901

902 Human-readable error description.

903

904 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

905

906 What the client should do next in response to this error.

907

908 - `BetaManagedAgentsRetryStatusRetrying object`

909

910 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.

911

912 - `BetaManagedAgentsRetryStatusExhausted object`

913

914 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

915

916 - `BetaManagedAgentsRetryStatusTerminal object`

917

918 The session encountered a terminal error and will transition to `terminated` state.

919

920 - `BetaManagedAgentsModelRateLimitedError object`

921

922 The model request was rate-limited.

923

924 - `type: "model_rate_limited_error"`

925

926 - `message: string`

927

928 Human-readable error description.

929

930 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

931

932 What the client should do next in response to this error.

933

934 - `BetaManagedAgentsRetryStatusRetrying object`

935

936 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.

937

938 - `BetaManagedAgentsRetryStatusExhausted object`

939

940 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

941

942 - `BetaManagedAgentsRetryStatusTerminal object`

943

944 The session encountered a terminal error and will transition to `terminated` state.

945

946 - `BetaManagedAgentsModelRequestFailedError object`

947

948 A model request failed for a reason other than overload or rate-limiting.

949

950 - `type: "model_request_failed_error"`

951

952 - `message: string`

953

954 Human-readable error description.

955

956 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

957

958 What the client should do next in response to this error.

959

960 - `BetaManagedAgentsRetryStatusRetrying object`

961

962 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.

963

964 - `BetaManagedAgentsRetryStatusExhausted object`

965

966 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

967

968 - `BetaManagedAgentsRetryStatusTerminal object`

969

970 The session encountered a terminal error and will transition to `terminated` state.

971

972 - `BetaManagedAgentsMCPConnectionFailedError object`

973

974 Failed to connect to an MCP server.

975

976 - `type: "mcp_connection_failed_error"`

977

978 - `mcp_server_name: string`

979

980 Name of the MCP server that failed to connect.

981

982 - `message: string`

983

984 Human-readable error description.

985

986 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

987

988 What the client should do next in response to this error.

989

990 - `BetaManagedAgentsRetryStatusRetrying object`

991

992 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.

993

994 - `BetaManagedAgentsRetryStatusExhausted object`

995

996 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

997

998 - `BetaManagedAgentsRetryStatusTerminal object`

999

1000 The session encountered a terminal error and will transition to `terminated` state.

1001

1002 - `BetaManagedAgentsMCPAuthenticationFailedError object`

1003

1004 Authentication to an MCP server failed.

1005

1006 - `type: "mcp_authentication_failed_error"`

1007

1008 - `mcp_server_name: string`

1009

1010 Name of the MCP server that failed authentication.

1011

1012 - `message: string`

1013

1014 Human-readable error description.

1015

1016 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1017

1018 What the client should do next in response to this error.

1019

1020 - `BetaManagedAgentsRetryStatusRetrying object`

1021

1022 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.

1023

1024 - `BetaManagedAgentsRetryStatusExhausted object`

1025

1026 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

1027

1028 - `BetaManagedAgentsRetryStatusTerminal object`

1029

1030 The session encountered a terminal error and will transition to `terminated` state.

1031

1032 - `BetaManagedAgentsBillingError object`

1033

1034 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.

1035

1036 - `type: "billing_error"`

1037

1038 - `message: string`

1039

1040 Human-readable error description.

1041

1042 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1043

1044 What the client should do next in response to this error.

1045

1046 - `BetaManagedAgentsRetryStatusRetrying object`

1047

1048 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.

1049

1050 - `BetaManagedAgentsRetryStatusExhausted object`

1051

1052 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

1053

1054 - `BetaManagedAgentsRetryStatusTerminal object`

1055

1056 The session encountered a terminal error and will transition to `terminated` state.

1057

1058 - `BetaManagedAgentsCredentialHostUnreachableError object`

1059

1060 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

1061

1062 - `type: "credential_host_unreachable_error"`

1063

1064 - `credential_id: string`

1065

1066 ID of the affected credential.

1067

1068 - `message: string`

1069

1070 Human-readable error description.

1071

1072 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1073

1074 What the client should do next in response to this error.

1075

1076 - `BetaManagedAgentsRetryStatusRetrying object`

1077

1078 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.

1079

1080 - `BetaManagedAgentsRetryStatusExhausted object`

1081

1082 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

1083

1084 - `BetaManagedAgentsRetryStatusTerminal object`

1085

1086 The session encountered a terminal error and will transition to `terminated` state.

1087

1088 - `vault_id: string`

1089

1090 ID of the vault containing the affected credential.

1091

1092 - `processed_at: string`

1093

1094 A timestamp in RFC 3339 format

1095

1096 format: date-time

1097

1098 - `BetaManagedAgentsSessionStatusRescheduledEvent object`

1099

1100 Indicates the session is recovering from an error state and is rescheduled for execution.

1101

1102 - `type: "session.status_rescheduled"`

1103

1104 - `id: string`

1105

1106 Unique identifier for this event.

1107

1108 - `processed_at: string`

1109

1110 A timestamp in RFC 3339 format

1111

1112 format: date-time

1113

1114 - `BetaManagedAgentsSessionStatusRunningEvent object`

1115

1116 Indicates the session is actively running and the agent is working.

1117

1118 - `type: "session.status_running"`

1119

1120 - `id: string`

1121

1122 Unique identifier for this event.

1123

1124 - `processed_at: string`

1125

1126 A timestamp in RFC 3339 format

1127

1128 format: date-time

1129

1130 - `BetaManagedAgentsSessionStatusIdleEvent object`

1131

1132 Indicates the agent has paused and is awaiting user input.

1133

1134 - `type: "session.status_idle"`

1135

1136 - `id: string`

1137

1138 Unique identifier for this event.

1139

1140 - `processed_at: string`

1141

1142 A timestamp in RFC 3339 format

1143

1144 format: date-time

1145

1146 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`

1147

1148 The agent completed its turn naturally and is ready for the next user message.

1149

1150 - `BetaManagedAgentsSessionEndTurn object`

1151

1152 The agent completed its turn naturally and is ready for the next user message.

1153

1154 - `type: "end_turn"`

1155

1156 - `BetaManagedAgentsSessionRequiresAction object`

1157

1158 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.

1159

1160 - `type: "requires_action"`

1161

1162 - `event_ids: array of string`

1163

1164 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

1165

1166 - `BetaManagedAgentsSessionRetriesExhausted object`

1167

1168 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.

1169

1170 - `type: "retries_exhausted"`

1171

1172 - `BetaManagedAgentsSessionBudgetReached object`

1173

1174 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.

1175

1176 - `type: "budget_reached"`

1177

1178 - `BetaManagedAgentsSessionStatusTerminatedEvent object`

1179

1180 Indicates the session has terminated, either due to an error or completion.

1181

1182 - `type: "session.status_terminated"`

1183

1184 - `id: string`

1185

1186 Unique identifier for this event.

1187

1188 - `processed_at: string`

1189

1190 A timestamp in RFC 3339 format

1191

1192 format: date-time

1193

1194 - `BetaManagedAgentsSessionThreadCreatedEvent object`

1195

1196 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.

1197

1198 - `type: "session.thread_created"`

1199

1200 - `id: string`

1201

1202 Unique identifier for this event.

1203

1204 - `agent_name: string`

1205

1206 Name of the callable agent the thread runs.

1207

1208 - `processed_at: string`

1209

1210 A timestamp in RFC 3339 format

1211

1212 format: date-time

1213

1214 - `session_thread_id: string`

1215

1216 Public `sthr_` ID of the newly created thread.

1217

1218 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`

1219

1220 Emitted when an outcome evaluation cycle begins.

1221

1222 - `type: "span.outcome_evaluation_start"`

1223

1224 - `id: string`

1225

1226 Unique identifier for this event.

1227

1228 - `iteration: number`

1229

1230 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

1231

1232 format: int32

1233

1234 - `outcome_id: string`

1235

1236 The `outc_` ID of the outcome being evaluated.

1237

1238 - `processed_at: string`

1239

1240 A timestamp in RFC 3339 format

1241

1242 format: date-time

1243

1244 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`

1245

1246 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.

1247

1248 - `type: "span.outcome_evaluation_end"`

1249

1250 - `id: string`

1251

1252 Unique identifier for this event.

1253

1254 - `explanation: string`

1255

1256 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

1257

1258 - `iteration: number`

1259

1260 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

1261

1262 format: int32

1263

1264 - `outcome_evaluation_start_id: string`

1265

1266 The id of the corresponding `span.outcome_evaluation_start` event.

1267

1268 - `outcome_id: string`

1269

1270 The `outc_` ID of the outcome being evaluated.

1271

1272 - `processed_at: string`

1273

1274 A timestamp in RFC 3339 format

1275

1276 format: date-time

1277

1278 - `result: string`

1279

1280 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.

1281

1282 - `usage: BetaManagedAgentsSpanModelUsage`

1283

1284 Token usage for a single model request.

1285

1286 - `cache_creation_input_tokens: number`

1287

1288 Tokens used to create prompt cache in this request.

1289

1290 format: int32

1291

1292 - `cache_read_input_tokens: number`

1293

1294 Tokens read from prompt cache in this request.

1295

1296 format: int32

1297

1298 - `input_tokens: number`

1299

1300 Input tokens consumed by this request.

1301

1302 format: int32

1303

1304 - `output_tokens: number`

1305

1306 Output tokens generated by this request.

1307

1308 format: int32

1309

1310 - `speed: optional "standard" or "fast" or null`

1311

1312 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.

1313

1314 - `"standard"`

1315

1316 - `"fast"`

1317

1318 - `BetaManagedAgentsSpanModelRequestStartEvent object`

1319

1320 Emitted when a model request is initiated by the agent.

1321

1322 - `type: "span.model_request_start"`

1323

1324 - `id: string`

1325

1326 Unique identifier for this event.

1327

1328 - `processed_at: string`

1329

1330 A timestamp in RFC 3339 format

1331

1332 format: date-time

1333

1334 - `BetaManagedAgentsSpanModelRequestEndEvent object`

1335

1336 Emitted when a model request completes.

1337

1338 - `type: "span.model_request_end"`

1339

1340 - `id: string`

1341

1342 Unique identifier for this event.

1343

1344 - `is_error: boolean or null`

1345

1346 Whether the model request resulted in an error.

1347

1348 - `model_request_start_id: string`

1349

1350 The id of the corresponding `span.model_request_start` event.

1351

1352 - `model_usage: BetaManagedAgentsSpanModelUsage`

1353

1354 Token usage for a single model request.

1355

1356 - `processed_at: string`

1357

1358 A timestamp in RFC 3339 format

1359

1360 format: date-time

1361

1362 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`

1363

1364 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.

1365

1366 - `type: "span.outcome_evaluation_ongoing"`

1367

1368 - `id: string`

1369

1370 Unique identifier for this event.

1371

1372 - `iteration: number`

1373

1374 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

1375

1376 format: int32

1377

1378 - `outcome_id: string`

1379

1380 The `outc_` ID of the outcome being evaluated.

1381

1382 - `processed_at: string`

1383

1384 A timestamp in RFC 3339 format

1385

1386 format: date-time

1387

1388 - `BetaManagedAgentsUserDefineOutcomeEvent object`

1389

1390 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

1391

1392 - `type: "user.define_outcome"`

1393

1394 - `id: string`

1395

1396 Unique identifier for this event.

1397

1398 - `description: string`

1399

1400 What the agent should produce. Copied from the input event.

1401

1402 - `max_iterations: number or null`

1403

1404 Evaluate-then-revise cycles before giving up. Default 3, max 20.

1405

1406 format: int32

1407

1408 - `outcome_id: string`

1409

1410 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

1411

1412 - `processed_at: string`

1413

1414 A timestamp in RFC 3339 format

1415

1416 format: date-time

1417

1418 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`

1419

1420 Rubric for grading the quality of an outcome.

1421

1422 - `BetaManagedAgentsFileRubric object`

1423

1424 Rubric referenced by a file uploaded via the Files API.

1425

1426 - `type: "file"`

1427

1428 - `file_id: string`

1429

1430 ID of the rubric file.

1431

1432 - `BetaManagedAgentsTextRubric object`

1433

1434 Rubric content provided inline as text.

1435

1511436 - `type: "text"`

1521437

1438 - `content: string`

1439

1440 Rubric content. Plain text or markdown — the grader treats it as freeform text.

1441

1442 - `BetaManagedAgentsSessionDeletedEvent object`

1443

1444 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

1445

1446 - `type: "session.deleted"`

1447

1448 - `id: string`

1449

1450 Unique identifier for this event.

1451

1452 - `processed_at: string`

1453

1454 A timestamp in RFC 3339 format

1455

1456 format: date-time

1457

1458 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`

1459

1460 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1461

1462 - `type: "session.thread_status_running"`

1463

1464 - `id: string`

1465

1466 Unique identifier for this event.

1467

1468 - `agent_name: string`

1469

1470 Name of the agent the thread runs.

1471

1472 - `processed_at: string`

1473

1474 A timestamp in RFC 3339 format

1475

1476 format: date-time

1477

1478 - `session_thread_id: string`

1479

1480 Public sthr_ ID of the thread that started running.

1481

1482 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`

1483

1484 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.

1485

1486 - `type: "session.thread_status_idle"`

1487

1488 - `id: string`

1489

1490 Unique identifier for this event.

1491

1492 - `agent_name: string`

1493

1494 Name of the agent the thread runs.

1495

1496 - `processed_at: string`

1497

1498 A timestamp in RFC 3339 format

1499

1500 format: date-time

1501

1502 - `session_thread_id: string`

1503

1504 Public sthr_ ID of the thread that went idle.

1505

1506 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`

1507

1508 The agent completed its turn naturally and is ready for the next user message.

1509

1510 - `BetaManagedAgentsSessionEndTurn object`

1511

1512 The agent completed its turn naturally and is ready for the next user message.

1513

1514 - `BetaManagedAgentsSessionRequiresAction object`

1515

1516 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.

1517

1518 - `BetaManagedAgentsSessionRetriesExhausted object`

1519

1520 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.

1521

1522 - `BetaManagedAgentsSessionBudgetReached object`

1523

1524 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.

1525

1526 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`

1527

1528 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.

1529

1530 - `type: "session.thread_status_terminated"`

1531

1532 - `id: string`

1533

1534 Unique identifier for this event.

1535

1536 - `agent_name: string`

1537

1538 Name of the agent the thread runs.

1539

1540 - `processed_at: string`

1541

1542 A timestamp in RFC 3339 format

1543

1544 format: date-time

1545

1546 - `session_thread_id: string`

1547

1548 Public sthr_ ID of the thread that terminated.

1549

1550 - `BetaManagedAgentsUserToolResultEvent object`

1551

1552 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.

1553

1554 - `type: "user.tool_result"`

1555

1556 - `id: string`

1557

1558 Unique identifier for this event.

1559

1560 - `tool_use_id: string`

1561

1562 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

1563

1564 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

1565

1566 The result content returned by the tool.

1567

1568 - `BetaManagedAgentsTextBlock object`

1569

1570 Regular text content.

1571

1531572 - `BetaManagedAgentsImageBlock object`

1541573

1551574 Image content specified directly as base64 data or as a reference via a URL.

1561575

157 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

158

159 Union type for image source variants.

160

161 - `BetaManagedAgentsBase64ImageSource object`

162

163 Base64-encoded image data.

164

165 - `data: string`

166

167 Base64-encoded image data.

168

169 minLength: 1

170

171 - `media_type: string`

172

173 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

174

175 minLength: 1

176

177 - `type: "base64"`

178

179 - `BetaManagedAgentsURLImageSource object`

180

181 Image referenced by URL.

182

183 - `type: "url"`

184

185 - `url: string`

186

187 URL of the image to fetch.

188

189 minLength: 1

190

191 - `BetaManagedAgentsFileImageSource object`

192

193 Image referenced by file ID.

194

195 - `file_id: string`

196

197 ID of a previously uploaded file.

198

199 minLength: 1

200

201 - `type: "file"`

202

203 - `type: "image"`

204

2051576 - `BetaManagedAgentsDocumentBlock object`

2061577

2071578 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

2081579

209 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`

210

211 Union type for document source variants.

212

213 - `BetaManagedAgentsBase64DocumentSource object`

214

215 Base64-encoded document data.

216

217 - `data: string`

218

219 Base64-encoded document data.

220

221 minLength: 1

222

223 - `media_type: string`

224

225 MIME type of the document (e.g., "application/pdf").

226

227 minLength: 1

228

229 - `type: "base64"`

230

231 - `BetaManagedAgentsPlainTextDocumentSource object`

232

233 Plain text document content.

234

235 - `data: string`

236

237 The plain text content.

238

239 minLength: 1

240

241 - `media_type: "text/plain"`

242

243 MIME type of the text content. Must be "text/plain".

244

245 - `type: "text"`

246

247 - `BetaManagedAgentsURLDocumentSource object`

248

249 Document referenced by URL.

250

251 - `type: "url"`

252

253 - `url: string`

254

255 URL of the document to fetch.

256

257 minLength: 1

258

259 - `BetaManagedAgentsFileDocumentSource object`

260

261 Document referenced by file ID.

262

263 - `file_id: string`

264

265 ID of a previously uploaded file.

266

267 minLength: 1

268

269 - `type: "file"`

270

271 - `type: "document"`

272

273 - `context: optional string or null`

274

275 Additional context about the document for the model.

276

277 - `title: optional string or null`

278

279 The title of the document.

280

281 - `BetaManagedAgentsRedactedBlock object`

282

283 Placeholder for content withheld by Anthropic model policy.

284

285 - `type: "redacted"`

286

287 - `type: "user.message"`

1580 - `BetaManagedAgentsSearchResultBlock object`

1581

1582 A block containing a web search result.

1583

1584 - `is_error: optional boolean or null`

1585

1586 Whether the tool execution resulted in an error.

2881587

2891588 - `processed_at: optional string or null`

2901589

from line 1591

2921591

2931592 format: date-time

2941593

295 - `BetaManagedAgentsUserInterruptEvent object`

296

297 An interrupt event that pauses agent execution and returns control to the user.

298

299 - `id: string`

300

301 Unique identifier for this event.

302

303 - `type: "user.interrupt"`

1594 - `session_thread_id: optional string or null`

1595

1596 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

1597

1598 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`

1599

1600 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.

1601

1602 - `type: "session.thread_status_rescheduled"`

1603

1604 - `id: string`

1605

1606 Unique identifier for this event.

1607

1608 - `agent_name: string`

1609

1610 Name of the agent the thread runs.

1611

1612 - `processed_at: string`

1613

1614 A timestamp in RFC 3339 format

1615

1616 format: date-time

1617

1618 - `session_thread_id: string`

1619

1620 Public sthr_ ID of the thread that is retrying.

1621

1622 - `BetaManagedAgentsSessionUpdatedEvent object`

1623

1624 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.

1625

1626 - `type: "session.updated"`

1627

1628 - `id: string`

1629

1630 Unique identifier for this event.

1631

1632 - `processed_at: string`

1633

1634 A timestamp in RFC 3339 format

1635

1636 format: date-time

1637

1638 - `agent: optional BetaManagedAgentsSessionAgent or null`

1639

1640 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

1641

1642 - `type: "agent"`

1643

1644 - `id: string`

1645

1646 - `description: string or null`

1647

1648 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1649

1650 - `type: "url"`

1651

1652 - `name: string`

1653

1654 - `url: string`

1655

1656 - `model: BetaManagedAgentsModelConfig`

1657

1658 Model identifier and configuration.

1659

1660 - `id: BetaManagedAgentsModel`

1661

1662 The model that will power your agent.

1663

1664 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

1665

1666 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`

1667

1668 The model that will power your agent.

1669

1670 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

1671

1672 - `"claude-fable-5-1"`

1673

1674 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows

1675

1676 - `"claude-sonnet-5"`

1677

1678 High-performance model for coding and agents

1679

1680 - `"claude-fable-5"`

1681

1682 Next generation of intelligence for the hardest knowledge work and coding problems

1683

1684 - `"claude-opus-5"`

1685

1686 Powerful intelligence for long-running agents and coding

1687

1688 - `"claude-opus-4-8"`

1689

1690 Powerful intelligence for long-running agents and coding

1691

1692 - `"claude-opus-4-7"`

1693

1694 Powerful intelligence for long-running agents and coding

1695

1696 - `"claude-opus-4-6"`

1697

1698 Powerful intelligence for long-running agents and coding

1699

1700 - `"claude-sonnet-4-6"`

1701

1702 Best combination of speed and intelligence

1703

1704 - `"claude-haiku-4-5"`

1705

1706 Fastest model with near-frontier intelligence

1707

1708 - `"claude-haiku-4-5-20251001"`

1709

1710 Fastest model with near-frontier intelligence

1711

1712 - `"claude-opus-4-5"`

1713

1714 Powerful intelligence for long-running agents and coding

1715

1716 - `"claude-opus-4-5-20251101"`

1717

1718 Powerful intelligence for long-running agents and coding

1719

1720 - `"claude-sonnet-4-5"`

1721

1722 High-performance model for agents and coding

1723

1724 - `"claude-sonnet-4-5-20250929"`

1725

1726 High-performance model for agents and coding

1727

1728 - `string`

1729

1730 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`

1731

1732 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.

1733

1734 - `BetaManagedAgentsEffortLow object`

1735

1736 Low effort. Favors latency over reasoning depth.

1737

1738 - `type: "low"`

1739

1740 - `BetaManagedAgentsEffortMedium object`

1741

1742 Medium effort. Balances latency and reasoning depth.

1743

1744 - `type: "medium"`

1745

1746 - `BetaManagedAgentsEffortHigh object`

1747

1748 High effort. Favors reasoning depth.

1749

1750 - `type: "high"`

1751

1752 - `BetaManagedAgentsEffortXhigh object`

1753

1754 Extra-high effort. Not all models accept this level.

1755

1756 - `type: "xhigh"`

1757

1758 - `BetaManagedAgentsEffortMax object`

1759

1760 Maximum effort. Favors reasoning depth over latency.

1761

1762 - `type: "max"`

1763

1764 - `inference_geo: optional string`

1765

1766 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.

1767

1768 - `speed: optional "standard" or "fast"`

1769

1770 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.

1771

1772 - `"standard"`

1773

1774 - `"fast"`

1775

1776 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`

1777

1778 Resolved coordinator topology with full agent definitions for each roster member.

1779

1780 - `type: "coordinator"`

1781

1782 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`

1783

1784 Full `agent` definitions the coordinator may spawn as session threads.

1785

1786 - `BetaManagedAgentsSessionThreadAgent object`

1787

1788 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`.

1789

1790 - `type: "agent"`

1791

1792 - `id: string`

1793

1794 - `description: string or null`

1795

1796 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1797

1798 - `type: "url"`

1799

1800 - `name: string`

1801

1802 - `url: string`

1803

1804 - `model: BetaManagedAgentsModelConfig`

1805

1806 Model identifier and configuration.

1807

1808 - `name: string`

1809

1810 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

1811

1812 - `BetaManagedAgentsAnthropicSkill object`

1813

1814 A resolved Anthropic-managed skill.

1815

1816 - `type: "anthropic"`

1817

1818 - `skill_id: string`

1819

1820 - `version: string`

1821

1822 - `BetaManagedAgentsCustomSkill object`

1823

1824 A resolved user-created custom skill.

1825

1826 - `type: "custom"`

1827

1828 - `skill_id: string`

1829

1830 - `version: string`

1831

1832 - `system: string or null`

1833

1834 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`

1835

1836 - `BetaManagedAgentsAgentToolset20260401 object`

1837

1838 - `type: "agent_toolset_20260401"`

1839

1840 - `configs: array of BetaManagedAgentsAgentToolConfig`

1841

1842 - `BetaManagedAgentsBashToolConfig object`

1843

1844 Configuration for the bash tool.

1845

1846 - `type: "bash"`

1847

1848 - `enabled: boolean`

1849

1850 - `name: "bash"`

1851

1852 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1853

1854 Permission policy for tool execution.

1855

1856 - `BetaManagedAgentsAlwaysAllowPolicy object`

1857

1858 Tool calls are automatically approved without user confirmation.

1859

1860 - `type: "always_allow"`

1861

1862 - `BetaManagedAgentsAlwaysAskPolicy object`

1863

1864 Tool calls require user confirmation before execution.

1865

1866 - `type: "always_ask"`

1867

1868 - `BetaManagedAgentsAutoPolicy object`

1869

1870 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1871

1872 - `type: "auto"`

1873

1874 - `BetaManagedAgentsEditToolConfig object`

1875

1876 Configuration for the edit tool.

1877

1878 - `type: "edit"`

1879

1880 - `enabled: boolean`

1881

1882 - `name: "edit"`

1883

1884 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1885

1886 Permission policy for tool execution.

1887

1888 - `BetaManagedAgentsAlwaysAllowPolicy object`

1889

1890 Tool calls are automatically approved without user confirmation.

1891

1892 - `BetaManagedAgentsAlwaysAskPolicy object`

1893

1894 Tool calls require user confirmation before execution.

1895

1896 - `BetaManagedAgentsAutoPolicy object`

1897

1898 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1899

1900 - `BetaManagedAgentsReadToolConfig object`

1901

1902 Configuration for the read tool.

1903

1904 - `type: "read"`

1905

1906 - `enabled: boolean`

1907

1908 - `name: "read"`

1909

1910 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1911

1912 Permission policy for tool execution.

1913

1914 - `BetaManagedAgentsAlwaysAllowPolicy object`

1915

1916 Tool calls are automatically approved without user confirmation.

1917

1918 - `BetaManagedAgentsAlwaysAskPolicy object`

1919

1920 Tool calls require user confirmation before execution.

1921

1922 - `BetaManagedAgentsAutoPolicy object`

1923

1924 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1925

1926 - `BetaManagedAgentsWriteToolConfig object`

1927

1928 Configuration for the write tool.

1929

1930 - `type: "write"`

1931

1932 - `enabled: boolean`

1933

1934 - `name: "write"`

1935

1936 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1937

1938 Permission policy for tool execution.

1939

1940 - `BetaManagedAgentsAlwaysAllowPolicy object`

1941

1942 Tool calls are automatically approved without user confirmation.

1943

1944 - `BetaManagedAgentsAlwaysAskPolicy object`

1945

1946 Tool calls require user confirmation before execution.

1947

1948 - `BetaManagedAgentsAutoPolicy object`

1949

1950 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1951

1952 - `BetaManagedAgentsGlobToolConfig object`

1953

1954 Configuration for the glob tool.

1955

1956 - `type: "glob"`

1957

1958 - `enabled: boolean`

1959

1960 - `name: "glob"`

1961

1962 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1963

1964 Permission policy for tool execution.

1965

1966 - `BetaManagedAgentsAlwaysAllowPolicy object`

1967

1968 Tool calls are automatically approved without user confirmation.

1969

1970 - `BetaManagedAgentsAlwaysAskPolicy object`

1971

1972 Tool calls require user confirmation before execution.

1973

1974 - `BetaManagedAgentsAutoPolicy object`

1975

1976 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1977

1978 - `BetaManagedAgentsGrepToolConfig object`

1979

1980 Configuration for the grep tool.

1981

1982 - `type: "grep"`

1983

1984 - `enabled: boolean`

1985

1986 - `name: "grep"`

1987

1988 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1989

1990 Permission policy for tool execution.

1991

1992 - `BetaManagedAgentsAlwaysAllowPolicy object`

1993

1994 Tool calls are automatically approved without user confirmation.

1995

1996 - `BetaManagedAgentsAlwaysAskPolicy object`

1997

1998 Tool calls require user confirmation before execution.

1999

2000 - `BetaManagedAgentsAutoPolicy object`

2001

2002 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2003

2004 - `BetaManagedAgentsWebFetchToolConfig object`

2005

2006 Configuration for the web_fetch tool.

2007

2008 - `type: "web_fetch"`

2009

2010 - `enabled: boolean`

2011

2012 - `name: "web_fetch"`

2013

2014 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2015

2016 Permission policy for tool execution.

2017

2018 - `BetaManagedAgentsAlwaysAllowPolicy object`

2019

2020 Tool calls are automatically approved without user confirmation.

2021

2022 - `BetaManagedAgentsAlwaysAskPolicy object`

2023

2024 Tool calls require user confirmation before execution.

2025

2026 - `BetaManagedAgentsAutoPolicy object`

2027

2028 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2029

2030 - `allowed_domains: optional array of string`

2031

2032 - `blocked_domains: optional array of string`

2033

2034 - `max_content_tokens: optional number or null`

2035

2036 format: int32

2037

2038 - `BetaManagedAgentsWebSearchToolConfig object`

2039

2040 Configuration for the web_search tool.

2041

2042 - `type: "web_search"`

2043

2044 - `enabled: boolean`

2045

2046 - `name: "web_search"`

2047

2048 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2049

2050 Permission policy for tool execution.

2051

2052 - `BetaManagedAgentsAlwaysAllowPolicy object`

2053

2054 Tool calls are automatically approved without user confirmation.

2055

2056 - `BetaManagedAgentsAlwaysAskPolicy object`

2057

2058 Tool calls require user confirmation before execution.

2059

2060 - `BetaManagedAgentsAutoPolicy object`

2061

2062 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2063

2064 - `allowed_domains: optional array of string`

2065

2066 - `blocked_domains: optional array of string`

2067

2068 - `user_location: optional BetaManagedAgentsUserLocation or null`

2069

2070 Approximate user location for search result localization.

2071

2072 - `type: "approximate"`

2073

2074 Location precision. Only "approximate" is supported.

2075

2076 - `city: optional string or null`

2077

2078 City name.

2079

2080 minLength: 1, maxLength: 255

2081

2082 - `country: optional string or null`

2083

2084 Two-letter ISO 3166-1 country code, uppercase.

2085

2086 - `region: optional string or null`

2087

2088 Region or state name.

2089

2090 minLength: 1, maxLength: 255

2091

2092 - `timezone: optional string or null`

2093

2094 IANA timezone identifier, e.g. "America/Los_Angeles".

2095

2096 minLength: 1, maxLength: 255

2097

2098 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`

2099

2100 Resolved default configuration for agent tools.

2101

2102 - `enabled: boolean`

2103

2104 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2105

2106 Permission policy for tool execution.

2107

2108 - `BetaManagedAgentsAlwaysAllowPolicy object`

2109

2110 Tool calls are automatically approved without user confirmation.

2111

2112 - `BetaManagedAgentsAlwaysAskPolicy object`

2113

2114 Tool calls require user confirmation before execution.

2115

2116 - `BetaManagedAgentsAutoPolicy object`

2117

2118 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2119

2120 - `BetaManagedAgentsMCPToolset object`

2121

2122 - `type: "mcp_toolset"`

2123

2124 - `configs: array of BetaManagedAgentsMCPToolConfig`

2125

2126 - `enabled: boolean`

2127

2128 - `name: string`

2129

2130 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2131

2132 Permission policy for tool execution.

2133

2134 - `BetaManagedAgentsAlwaysAllowPolicy object`

2135

2136 Tool calls are automatically approved without user confirmation.

2137

2138 - `BetaManagedAgentsAlwaysAskPolicy object`

2139

2140 Tool calls require user confirmation before execution.

2141

2142 - `BetaManagedAgentsAutoPolicy object`

2143

2144 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2145

2146 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

2147

2148 Resolved default configuration for all tools from an MCP server.

2149

2150 - `enabled: boolean`

2151

2152 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2153

2154 Permission policy for tool execution.

2155

2156 - `BetaManagedAgentsAlwaysAllowPolicy object`

2157

2158 Tool calls are automatically approved without user confirmation.

2159

2160 - `BetaManagedAgentsAlwaysAskPolicy object`

2161

2162 Tool calls require user confirmation before execution.

2163

2164 - `BetaManagedAgentsAutoPolicy object`

2165

2166 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2167

2168 - `mcp_server_name: string`

2169

2170 - `BetaManagedAgentsCustomTool object`

2171

2172 A custom tool as returned in API responses.

2173

2174 - `type: "custom"`

2175

2176 - `description: string`

2177

2178 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

2179

2180 JSON Schema for custom tool input parameters.

2181

2182 - `type: "object"`

2183

2184 - `properties: optional map[unknown] or null`

2185

2186 - `required: optional array of string or null`

2187

2188 - `name: string`

2189

2190 - `version: number`

2191

2192 format: int32

2193

2194 - `BetaManagedAgentsAdvisor object`

2195

2196 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

2197

2198 - `type: "advisor"`

2199

2200 - `model: string`

2201

2202 The advisor model id.

2203

2204 - `name: string`

2205

2206 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

2207

2208 - `BetaManagedAgentsAnthropicSkill object`

2209

2210 A resolved Anthropic-managed skill.

2211

2212 - `BetaManagedAgentsCustomSkill object`

2213

2214 A resolved user-created custom skill.

2215

2216 - `system: string or null`

2217

2218 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`

2219

2220 - `BetaManagedAgentsAgentToolset20260401 object`

2221

2222 - `BetaManagedAgentsMCPToolset object`

2223

2224 - `BetaManagedAgentsCustomTool object`

2225

2226 A custom tool as returned in API responses.

2227

2228 - `version: number`

2229

2230 format: int32

2231

2232 - `budget: optional BetaManagedAgentsBudgetLimit or null`

2233

2234 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

2235

2236 - `type: "limit"`

2237

2238 - `max_list_cost: BetaMonetaryAmount`

2239

2240 A monetary amount in a specific currency.

2241

2242 - `amount: string`

2243

2244 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

2245

2246 - `currency: BetaCurrency`

2247

2248 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.

2249

2250 - `metadata: optional map[string]`

2251

2252 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.

2253

2254 - `title: optional string or null`

2255

2256 The session's new title. Present only when the update changed it.

2257

2258 - `BetaManagedAgentsSystemMessageEvent object`

2259

2260 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

2261

2262 - `type: "system.message"`

2263

2264 - `id: string`

2265

2266 Unique identifier for this event.

2267

2268 - `content: array of BetaManagedAgentsSystemContentBlock`

2269

2270 System content blocks. Text-only.

2271

2272 - `type: "text"`

2273

2274 - `text: string`

2275

2276 The text content.

2277

2278 minLength: 1

3042279

3052280 - `processed_at: optional string or null`

3062281

from line 2283

3082283

3092284 format: date-time

3102285

311 - `session_thread_id: optional string or null`

312

313 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.

314

315 - `BetaManagedAgentsUserToolConfirmationEvent object`

316

317 A tool confirmation event that approves or denies a pending tool execution.

318

319 - `id: string`

320

321 Unique identifier for this event.

322

323 - `result: "allow" or "deny"`

324

325 UserToolConfirmationResult enum

326

327 - `"allow"`

328

329 - `"deny"`

330

331 - `tool_use_id: string`

332

333 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

334

335 - `type: "user.tool_confirmation"`

336

337 - `deny_message: optional string or null`

338

339 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

340

341 maxLength: 10000

342

343 - `processed_at: optional string or null`

344

345 A timestamp in RFC 3339 format

346

347 format: date-time

348

349 - `session_thread_id: optional string or null`

350

351 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.

352

353 - `BetaManagedAgentsUserCustomToolResultEvent object`

354

355 Event sent by the client providing the result of a custom tool execution.

356

357 - `id: string`

358

359 Unique identifier for this event.

360

361 - `custom_tool_use_id: string`

362

363 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

364

365 - `type: "user.custom_tool_result"`

366

367 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

368

369 The result content returned by the tool.

370

371 - `BetaManagedAgentsTextBlock object`

372

373 Regular text content.

374

375 - `BetaManagedAgentsImageBlock object`

376

377 Image content specified directly as base64 data or as a reference via a URL.

378

379 - `BetaManagedAgentsDocumentBlock object`

380

381 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

382

383 - `BetaManagedAgentsSearchResultBlock object`

384

385 A block containing a web search result.

386

387 - `citations: BetaManagedAgentsSearchResultCitations`

388

389 Citation settings for a search result.

390

391 - `enabled: boolean`

392

393 Whether citations are enabled for this search result.

394

395 - `content: array of BetaManagedAgentsSearchResultContent`

396

397 Array of text content blocks from the search result.

398

399 - `text: string`

400

401 The text content.

402

403 minLength: 1

404

405 - `type: "text"`

406

407 - `source: string`

408

409 The URL source of the search result.

410

411 minLength: 1

412

413 - `title: string`

414

415 The title of the search result.

416

417 minLength: 1

418

419 - `type: "search_result"`

420

421 - `is_error: optional boolean or null`

422

423 Whether the tool execution resulted in an error.

424

425 - `processed_at: optional string or null`

426

427 A timestamp in RFC 3339 format

428

429 format: date-time

430

431 - `session_thread_id: optional string or null`

432

433 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

434

435 - `BetaManagedAgentsAgentCustomToolUseEvent object`

436

437 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.

438

439 - `id: string`

440

441 Unique identifier for this event.

442

443 - `input: map[unknown]`

444

445 Input parameters for the tool call.

446

447 - `name: string`

448

449 Name of the custom tool being called.

450

451 - `processed_at: string`

452

453 A timestamp in RFC 3339 format

454

455 format: date-time

456

457 - `type: "agent.custom_tool_use"`

458

459 - `session_thread_id: optional string or null`

460

461 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.

462

463 - `BetaManagedAgentsAgentMessageEvent object`

464

465 An agent response event in the session conversation.

466

467 - `id: string`

468

469 Unique identifier for this event.

470

471 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`

472

473 Array of text blocks comprising the agent response.

474

475 - `BetaManagedAgentsTextBlock object`

476

477 Regular text content.

478

479 - `BetaManagedAgentsRedactedBlock object`

480

481 Placeholder for content withheld by Anthropic model policy.

482

483 - `processed_at: string`

484

485 A timestamp in RFC 3339 format

486

487 format: date-time

488

489 - `type: "agent.message"`

490

491 - `BetaManagedAgentsAgentThinkingEvent object`

492

493 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

494

495 - `id: string`

496

497 Unique identifier for this event.

498

499 - `processed_at: string`

500

501 A timestamp in RFC 3339 format

502

503 format: date-time

504

505 - `type: "agent.thinking"`

506

507 - `BetaManagedAgentsAgentMCPToolUseEvent object`

508

509 Event emitted when the agent invokes a tool provided by an MCP server.

510

511 - `id: string`

512

513 Unique identifier for this event.

514

515 - `input: map[unknown]`

516

517 Input parameters for the tool call.

518

519 - `mcp_server_name: string`

520

521 Name of the MCP server providing the tool.

522

523 - `name: string`

524

525 Name of the MCP tool being used.

526

527 - `processed_at: string`

528

529 A timestamp in RFC 3339 format

530

531 format: date-time

532

533 - `type: "agent.mcp_tool_use"`

534

535 - `evaluated_permission: optional "allow" or "ask" or "deny"`

536

537 AgentEvaluatedPermission enum

538

539 - `"allow"`

540

541 - `"ask"`

542

543 - `"deny"`

544

545 - `session_thread_id: optional string or null`

546

547 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.

548

549 - `BetaManagedAgentsAgentMCPToolResultEvent object`

550

551 Event representing the result of an MCP tool execution.

552

553 - `id: string`

554

555 Unique identifier for this event.

556

557 - `mcp_tool_use_id: string`

558

559 The id of the `agent.mcp_tool_use` event this result corresponds to.

560

561 - `processed_at: string`

562

563 A timestamp in RFC 3339 format

564

565 format: date-time

566

567 - `type: "agent.mcp_tool_result"`

568

569 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

570

571 The result content returned by the tool.

572

573 - `BetaManagedAgentsTextBlock object`

574

575 Regular text content.

576

577 - `BetaManagedAgentsImageBlock object`

578

579 Image content specified directly as base64 data or as a reference via a URL.

580

581 - `BetaManagedAgentsDocumentBlock object`

582

583 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

584

585 - `BetaManagedAgentsSearchResultBlock object`

586

587 A block containing a web search result.

588

589 - `is_error: optional boolean or null`

590

591 Whether the tool execution resulted in an error.

592

593 - `BetaManagedAgentsAgentToolUseEvent object`

594

595 Event emitted when the agent invokes a built-in agent tool.

596

597 - `id: string`

598

599 Unique identifier for this event.

600

601 - `input: map[unknown]`

602

603 Input parameters for the tool call.

604

605 - `name: string`

606

607 Name of the agent tool being used.

608

609 - `processed_at: string`

610

611 A timestamp in RFC 3339 format

612

613 format: date-time

614

615 - `type: "agent.tool_use"`

616

617 - `evaluated_permission: optional "allow" or "ask" or "deny"`

618

619 AgentEvaluatedPermission enum

620

621 - `"allow"`

622

623 - `"ask"`

624

625 - `"deny"`

626

627 - `session_thread_id: optional string or null`

628

629 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.

630

631 - `BetaManagedAgentsAgentToolResultEvent object`

632

633 Event representing the result of an agent tool execution.

634

635 - `id: string`

636

637 Unique identifier for this event.

638

639 - `processed_at: string`

640

641 A timestamp in RFC 3339 format

642

643 format: date-time

644

645 - `tool_use_id: string`

646

647 The id of the `agent.tool_use` event this result corresponds to.

648

649 - `type: "agent.tool_result"`

650

651 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

652

653 The result content returned by the tool.

654

655 - `BetaManagedAgentsTextBlock object`

656

657 Regular text content.

658

659 - `BetaManagedAgentsImageBlock object`

660

661 Image content specified directly as base64 data or as a reference via a URL.

662

663 - `BetaManagedAgentsDocumentBlock object`

664

665 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

666

667 - `BetaManagedAgentsSearchResultBlock object`

668

669 A block containing a web search result.

670

671 - `is_error: optional boolean or null`

672

673 Whether the tool execution resulted in an error.

674

675 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`

676

677 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

678

679 - `id: string`

680

681 Unique identifier for this event.

682

683 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

684

685 Message content blocks.

686

687 - `BetaManagedAgentsTextBlock object`

688

689 Regular text content.

690

691 - `BetaManagedAgentsImageBlock object`

692

693 Image content specified directly as base64 data or as a reference via a URL.

694

695 - `BetaManagedAgentsDocumentBlock object`

696

697 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

698

699 - `BetaManagedAgentsRedactedBlock object`

700

701 Placeholder for content withheld by Anthropic model policy.

702

703 - `from_session_thread_id: string`

704

705 Public `sthr_` ID of the thread that sent the message.

706

707 - `processed_at: string`

708

709 A timestamp in RFC 3339 format

710

711 format: date-time

712

713 - `type: "agent.thread_message_received"`

714

715 - `from_agent_name: optional string or null`

716

717 Name of the callable agent this message came from. Absent when received from the primary agent.

718

719 - `BetaManagedAgentsAgentThreadMessageSentEvent object`

720

721 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

722

723 - `id: string`

724

725 Unique identifier for this event.

726

727 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

728

729 Message content blocks.

730

731 - `BetaManagedAgentsTextBlock object`

732

733 Regular text content.

734

735 - `BetaManagedAgentsImageBlock object`

736

737 Image content specified directly as base64 data or as a reference via a URL.

738

739 - `BetaManagedAgentsDocumentBlock object`

740

741 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

742

743 - `BetaManagedAgentsRedactedBlock object`

744

745 Placeholder for content withheld by Anthropic model policy.

746

747 - `processed_at: string`

748

749 A timestamp in RFC 3339 format

750

751 format: date-time

752

753 - `to_session_thread_id: string`

754

755 Public `sthr_` ID of the thread the message was sent to.

756

757 - `type: "agent.thread_message_sent"`

758

759 - `to_agent_name: optional string or null`

760

761 Name of the callable agent this message was sent to. Absent when sent to the primary agent.

762

763 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`

764

765 Indicates that context compaction (summarization) occurred during the session.

766

767 - `id: string`

768

769 Unique identifier for this event.

770

771 - `processed_at: string`

772

773 A timestamp in RFC 3339 format

774

775 format: date-time

776

777 - `type: "agent.thread_context_compacted"`

778

779 - `BetaManagedAgentsSessionErrorEvent object`

780

781 An error event indicating a problem occurred during session execution.

782

783 - `id: string`

784

785 Unique identifier for this event.

786

787 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`

788

789 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.

790

791 - `BetaManagedAgentsUnknownError object`

792

793 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.

794

795 - `message: string`

796

797 Human-readable error description.

798

799 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

800

801 What the client should do next in response to this error.

802

803 - `BetaManagedAgentsRetryStatusRetrying object`

804

805 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.

806

807 - `type: "retrying"`

808

809 - `BetaManagedAgentsRetryStatusExhausted object`

810

811 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

812

813 - `type: "exhausted"`

814

815 - `BetaManagedAgentsRetryStatusTerminal object`

816

817 The session encountered a terminal error and will transition to `terminated` state.

818

819 - `type: "terminal"`

820

821 - `type: "unknown_error"`

822

823 - `BetaManagedAgentsModelOverloadedError object`

824

825 The model is currently overloaded. Emitted after automatic retries are exhausted.

826

827 - `message: string`

828

829 Human-readable error description.

830

831 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

832

833 What the client should do next in response to this error.

834

835 - `BetaManagedAgentsRetryStatusRetrying object`

836

837 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.

838

839 - `BetaManagedAgentsRetryStatusExhausted object`

840

841 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

842

843 - `BetaManagedAgentsRetryStatusTerminal object`

844

845 The session encountered a terminal error and will transition to `terminated` state.

846

847 - `type: "model_overloaded_error"`

848

849 - `BetaManagedAgentsModelRateLimitedError object`

850

851 The model request was rate-limited.

852

853 - `message: string`

854

855 Human-readable error description.

856

857 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

858

859 What the client should do next in response to this error.

860

861 - `BetaManagedAgentsRetryStatusRetrying object`

862

863 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.

864

865 - `BetaManagedAgentsRetryStatusExhausted object`

866

867 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

868

869 - `BetaManagedAgentsRetryStatusTerminal object`

870

871 The session encountered a terminal error and will transition to `terminated` state.

872

873 - `type: "model_rate_limited_error"`

874

875 - `BetaManagedAgentsModelRequestFailedError object`

876

877 A model request failed for a reason other than overload or rate-limiting.

878

879 - `message: string`

880

881 Human-readable error description.

882

883 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

884

885 What the client should do next in response to this error.

886

887 - `BetaManagedAgentsRetryStatusRetrying object`

888

889 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.

890

891 - `BetaManagedAgentsRetryStatusExhausted object`

892

893 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

894

895 - `BetaManagedAgentsRetryStatusTerminal object`

896

897 The session encountered a terminal error and will transition to `terminated` state.

898

899 - `type: "model_request_failed_error"`

900

901 - `BetaManagedAgentsMCPConnectionFailedError object`

902

903 Failed to connect to an MCP server.

904

905 - `mcp_server_name: string`

906

907 Name of the MCP server that failed to connect.

908

909 - `message: string`

910

911 Human-readable error description.

912

913 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

914

915 What the client should do next in response to this error.

916

917 - `BetaManagedAgentsRetryStatusRetrying object`

918

919 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.

920

921 - `BetaManagedAgentsRetryStatusExhausted object`

922

923 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

924

925 - `BetaManagedAgentsRetryStatusTerminal object`

926

927 The session encountered a terminal error and will transition to `terminated` state.

928

929 - `type: "mcp_connection_failed_error"`

930

931 - `BetaManagedAgentsMCPAuthenticationFailedError object`

932

933 Authentication to an MCP server failed.

934

935 - `mcp_server_name: string`

936

937 Name of the MCP server that failed authentication.

938

939 - `message: string`

940

941 Human-readable error description.

942

943 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

944

945 What the client should do next in response to this error.

946

947 - `BetaManagedAgentsRetryStatusRetrying object`

948

949 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.

950

951 - `BetaManagedAgentsRetryStatusExhausted object`

952

953 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

954

955 - `BetaManagedAgentsRetryStatusTerminal object`

956

957 The session encountered a terminal error and will transition to `terminated` state.

958

959 - `type: "mcp_authentication_failed_error"`

960

961 - `BetaManagedAgentsBillingError object`

962

963 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.

964

965 - `message: string`

966

967 Human-readable error description.

968

969 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

970

971 What the client should do next in response to this error.

972

973 - `BetaManagedAgentsRetryStatusRetrying object`

974

975 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.

976

977 - `BetaManagedAgentsRetryStatusExhausted object`

978

979 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

980

981 - `BetaManagedAgentsRetryStatusTerminal object`

982

983 The session encountered a terminal error and will transition to `terminated` state.

984

985 - `type: "billing_error"`

986

987 - `BetaManagedAgentsCredentialHostUnreachableError object`

988

989 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

990

991 - `credential_id: string`

992

993 ID of the affected credential.

994

995 - `message: string`

996

997 Human-readable error description.

998

999 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1000

1001 What the client should do next in response to this error.

1002

1003 - `BetaManagedAgentsRetryStatusRetrying object`

1004

1005 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.

1006

1007 - `BetaManagedAgentsRetryStatusExhausted object`

1008

1009 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

1010

1011 - `BetaManagedAgentsRetryStatusTerminal object`

1012

1013 The session encountered a terminal error and will transition to `terminated` state.

1014

1015 - `type: "credential_host_unreachable_error"`

1016

1017 - `vault_id: string`

1018

1019 ID of the vault containing the affected credential.

1020

1021 - `processed_at: string`

1022

1023 A timestamp in RFC 3339 format

1024

1025 format: date-time

1026

1027 - `type: "session.error"`

1028

1029 - `BetaManagedAgentsSessionStatusRescheduledEvent object`

1030

1031 Indicates the session is recovering from an error state and is rescheduled for execution.

1032

1033 - `id: string`

1034

1035 Unique identifier for this event.

1036

1037 - `processed_at: string`

1038

1039 A timestamp in RFC 3339 format

1040

1041 format: date-time

1042

1043 - `type: "session.status_rescheduled"`

1044

1045 - `BetaManagedAgentsSessionStatusRunningEvent object`

1046

1047 Indicates the session is actively running and the agent is working.

1048

1049 - `id: string`

1050

1051 Unique identifier for this event.

1052

1053 - `processed_at: string`

1054

1055 A timestamp in RFC 3339 format

1056

1057 format: date-time

1058

1059 - `type: "session.status_running"`

1060

1061 - `BetaManagedAgentsSessionStatusIdleEvent object`

1062

1063 Indicates the agent has paused and is awaiting user input.

1064

1065 - `id: string`

1066

1067 Unique identifier for this event.

1068

1069 - `processed_at: string`

1070

1071 A timestamp in RFC 3339 format

1072

1073 format: date-time

1074

1075 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`

1076

1077 The agent completed its turn naturally and is ready for the next user message.

1078

1079 - `BetaManagedAgentsSessionEndTurn object`

1080

1081 The agent completed its turn naturally and is ready for the next user message.

1082

1083 - `type: "end_turn"`

1084

1085 - `BetaManagedAgentsSessionRequiresAction object`

1086

1087 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.

1088

1089 - `event_ids: array of string`

1090

1091 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

1092

1093 - `type: "requires_action"`

1094

1095 - `BetaManagedAgentsSessionRetriesExhausted object`

1096

1097 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.

1098

1099 - `type: "retries_exhausted"`

1100

1101 - `BetaManagedAgentsSessionBudgetReached object`

1102

1103 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.

1104

1105 - `type: "budget_reached"`

1106

1107 - `type: "session.status_idle"`

1108

1109 - `BetaManagedAgentsSessionStatusTerminatedEvent object`

1110

1111 Indicates the session has terminated, either due to an error or completion.

1112

1113 - `id: string`

1114

1115 Unique identifier for this event.

1116

1117 - `processed_at: string`

1118

1119 A timestamp in RFC 3339 format

1120

1121 format: date-time

1122

1123 - `type: "session.status_terminated"`

1124

1125 - `BetaManagedAgentsSessionThreadCreatedEvent object`

1126

1127 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.

1128

1129 - `id: string`

1130

1131 Unique identifier for this event.

1132

1133 - `agent_name: string`

1134

1135 Name of the callable agent the thread runs.

1136

1137 - `processed_at: string`

1138

1139 A timestamp in RFC 3339 format

1140

1141 format: date-time

1142

1143 - `session_thread_id: string`

1144

1145 Public `sthr_` ID of the newly created thread.

1146

1147 - `type: "session.thread_created"`

1148

1149 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`

1150

1151 Emitted when an outcome evaluation cycle begins.

1152

1153 - `id: string`

1154

1155 Unique identifier for this event.

1156

1157 - `iteration: number`

1158

1159 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

1160

1161 format: int32

1162

1163 - `outcome_id: string`

1164

1165 The `outc_` ID of the outcome being evaluated.

1166

1167 - `processed_at: string`

1168

1169 A timestamp in RFC 3339 format

1170

1171 format: date-time

1172

1173 - `type: "span.outcome_evaluation_start"`

1174

1175 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`

1176

1177 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.

1178

1179 - `id: string`

1180

1181 Unique identifier for this event.

1182

1183 - `explanation: string`

1184

1185 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

1186

1187 - `iteration: number`

1188

1189 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

1190

1191 format: int32

1192

1193 - `outcome_evaluation_start_id: string`

1194

1195 The id of the corresponding `span.outcome_evaluation_start` event.

1196

1197 - `outcome_id: string`

1198

1199 The `outc_` ID of the outcome being evaluated.

1200

1201 - `processed_at: string`

1202

1203 A timestamp in RFC 3339 format

1204

1205 format: date-time

1206

1207 - `result: string`

1208

1209 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.

1210

1211 - `type: "span.outcome_evaluation_end"`

1212

1213 - `usage: BetaManagedAgentsSpanModelUsage`

1214

1215 Token usage for a single model request.

1216

1217 - `cache_creation_input_tokens: number`

1218

1219 Tokens used to create prompt cache in this request.

1220

1221 format: int32

1222

1223 - `cache_read_input_tokens: number`

1224

1225 Tokens read from prompt cache in this request.

1226

1227 format: int32

1228

1229 - `input_tokens: number`

1230

1231 Input tokens consumed by this request.

1232

1233 format: int32

1234

1235 - `output_tokens: number`

1236

1237 Output tokens generated by this request.

1238

1239 format: int32

1240

1241 - `speed: optional "standard" or "fast" or null`

1242

1243 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.

1244

1245 - `"standard"`

1246

1247 - `"fast"`

1248

1249 - `BetaManagedAgentsSpanModelRequestStartEvent object`

1250

1251 Emitted when a model request is initiated by the agent.

1252

1253 - `id: string`

1254

1255 Unique identifier for this event.

1256

1257 - `processed_at: string`

1258

1259 A timestamp in RFC 3339 format

1260

1261 format: date-time

1262

1263 - `type: "span.model_request_start"`

1264

1265 - `BetaManagedAgentsSpanModelRequestEndEvent object`

1266

1267 Emitted when a model request completes.

1268

1269 - `id: string`

1270

1271 Unique identifier for this event.

1272

1273 - `is_error: boolean or null`

1274

1275 Whether the model request resulted in an error.

1276

1277 - `model_request_start_id: string`

1278

1279 The id of the corresponding `span.model_request_start` event.

1280

1281 - `model_usage: BetaManagedAgentsSpanModelUsage`

1282

1283 Token usage for a single model request.

1284

1285 - `processed_at: string`

1286

1287 A timestamp in RFC 3339 format

1288

1289 format: date-time

1290

1291 - `type: "span.model_request_end"`

1292

1293 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`

1294

1295 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.

1296

1297 - `id: string`

1298

1299 Unique identifier for this event.

1300

1301 - `iteration: number`

1302

1303 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

1304

1305 format: int32

1306

1307 - `outcome_id: string`

1308

1309 The `outc_` ID of the outcome being evaluated.

1310

1311 - `processed_at: string`

1312

1313 A timestamp in RFC 3339 format

1314

1315 format: date-time

1316

1317 - `type: "span.outcome_evaluation_ongoing"`

1318

1319 - `BetaManagedAgentsUserDefineOutcomeEvent object`

1320

1321 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

1322

1323 - `id: string`

1324

1325 Unique identifier for this event.

1326

1327 - `description: string`

1328

1329 What the agent should produce. Copied from the input event.

1330

1331 - `max_iterations: number or null`

1332

1333 Evaluate-then-revise cycles before giving up. Default 3, max 20.

1334

1335 format: int32

1336

1337 - `outcome_id: string`

1338

1339 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

1340

1341 - `processed_at: string`

1342

1343 A timestamp in RFC 3339 format

1344

1345 format: date-time

1346

1347 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`

1348

1349 Rubric for grading the quality of an outcome.

1350

1351 - `BetaManagedAgentsFileRubric object`

1352

1353 Rubric referenced by a file uploaded via the Files API.

1354

1355 - `file_id: string`

1356

1357 ID of the rubric file.

1358

1359 - `type: "file"`

1360

1361 - `BetaManagedAgentsTextRubric object`

1362

1363 Rubric content provided inline as text.

1364

1365 - `content: string`

1366

1367 Rubric content. Plain text or markdown — the grader treats it as freeform text.

1368

1369 - `type: "text"`

1370

1371 - `type: "user.define_outcome"`

1372

1373 - `BetaManagedAgentsSessionDeletedEvent object`

1374

1375 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

1376

1377 - `id: string`

1378

1379 Unique identifier for this event.

1380

1381 - `processed_at: string`

1382

1383 A timestamp in RFC 3339 format

1384

1385 format: date-time

1386

1387 - `type: "session.deleted"`

1388

1389 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`

1390

1391 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1392

1393 - `id: string`

1394

1395 Unique identifier for this event.

1396

1397 - `agent_name: string`

1398

1399 Name of the agent the thread runs.

1400

1401 - `processed_at: string`

1402

1403 A timestamp in RFC 3339 format

1404

1405 format: date-time

1406

1407 - `session_thread_id: string`

1408

1409 Public sthr_ ID of the thread that started running.

1410

1411 - `type: "session.thread_status_running"`

1412

1413 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`

1414

1415 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.

1416

1417 - `id: string`

1418

1419 Unique identifier for this event.

1420

1421 - `agent_name: string`

1422

1423 Name of the agent the thread runs.

1424

1425 - `processed_at: string`

1426

1427 A timestamp in RFC 3339 format

1428

1429 format: date-time

1430

1431 - `session_thread_id: string`

1432

1433 Public sthr_ ID of the thread that went idle.

1434

1435 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`

1436

1437 The agent completed its turn naturally and is ready for the next user message.

1438

1439 - `BetaManagedAgentsSessionEndTurn object`

1440

1441 The agent completed its turn naturally and is ready for the next user message.

1442

1443 - `BetaManagedAgentsSessionRequiresAction object`

1444

1445 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.

1446

1447 - `BetaManagedAgentsSessionRetriesExhausted object`

1448

1449 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.

1450

1451 - `BetaManagedAgentsSessionBudgetReached object`

1452

1453 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.

1454

1455 - `type: "session.thread_status_idle"`

1456

1457 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`

1458

1459 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.

1460

1461 - `id: string`

1462

1463 Unique identifier for this event.

1464

1465 - `agent_name: string`

1466

1467 Name of the agent the thread runs.

1468

1469 - `processed_at: string`

1470

1471 A timestamp in RFC 3339 format

1472

1473 format: date-time

1474

1475 - `session_thread_id: string`

1476

1477 Public sthr_ ID of the thread that terminated.

1478

1479 - `type: "session.thread_status_terminated"`

1480

1481 - `BetaManagedAgentsUserToolResultEvent object`

1482

1483 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.

1484

1485 - `id: string`

1486

1487 Unique identifier for this event.

1488

1489 - `tool_use_id: string`

1490

1491 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

1492

1493 - `type: "user.tool_result"`

1494

1495 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

1496

1497 The result content returned by the tool.

1498

1499 - `BetaManagedAgentsTextBlock object`

1500

1501 Regular text content.

1502

1503 - `BetaManagedAgentsImageBlock object`

1504

1505 Image content specified directly as base64 data or as a reference via a URL.

1506

1507 - `BetaManagedAgentsDocumentBlock object`

1508

1509 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

1510

1511 - `BetaManagedAgentsSearchResultBlock object`

1512

1513 A block containing a web search result.

1514

1515 - `is_error: optional boolean or null`

1516

1517 Whether the tool execution resulted in an error.

1518

1519 - `processed_at: optional string or null`

1520

1521 A timestamp in RFC 3339 format

1522

1523 format: date-time

1524

1525 - `session_thread_id: optional string or null`

1526

1527 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

1528

1529 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`

1530

1531 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.

1532

1533 - `id: string`

1534

1535 Unique identifier for this event.

1536

1537 - `agent_name: string`

1538

1539 Name of the agent the thread runs.

1540

1541 - `processed_at: string`

1542

1543 A timestamp in RFC 3339 format

1544

1545 format: date-time

1546

1547 - `session_thread_id: string`

1548

1549 Public sthr_ ID of the thread that is retrying.

1550

1551 - `type: "session.thread_status_rescheduled"`

1552

1553 - `BetaManagedAgentsSessionUpdatedEvent object`

1554

1555 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.

1556

1557 - `id: string`

1558

1559 Unique identifier for this event.

1560

1561 - `processed_at: string`

1562

1563 A timestamp in RFC 3339 format

1564

1565 format: date-time

1566

1567 - `type: "session.updated"`

1568

1569 - `agent: optional BetaManagedAgentsSessionAgent or null`

1570

1571 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

1572

1573 - `id: string`

1574

1575 - `description: string or null`

1576

1577 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1578

1579 - `name: string`

1580

1581 - `type: "url"`

1582

1583 - `url: string`

1584

1585 - `model: BetaManagedAgentsModelConfig`

1586

1587 Model identifier and configuration.

1588

1589 - `id: BetaManagedAgentsModel`

1590

1591 The model that will power your agent.

1592

1593 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

1594

1595 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`

1596

1597 The model that will power your agent.

1598

1599 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

1600

1601 - `"claude-fable-5-1"`

1602

1603 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows

1604

1605 - `"claude-sonnet-5"`

1606

1607 High-performance model for coding and agents

1608

1609 - `"claude-fable-5"`

1610

1611 Next generation of intelligence for the hardest knowledge work and coding problems

1612

1613 - `"claude-opus-5"`

1614

1615 Powerful intelligence for long-running agents and coding

1616

1617 - `"claude-opus-4-8"`

1618

1619 Powerful intelligence for long-running agents and coding

1620

1621 - `"claude-opus-4-7"`

1622

1623 Powerful intelligence for long-running agents and coding

1624

1625 - `"claude-opus-4-6"`

1626

1627 Powerful intelligence for long-running agents and coding

1628

1629 - `"claude-sonnet-4-6"`

1630

1631 Best combination of speed and intelligence

1632

1633 - `"claude-haiku-4-5"`

1634

1635 Fastest model with near-frontier intelligence

1636

1637 - `"claude-haiku-4-5-20251001"`

1638

1639 Fastest model with near-frontier intelligence

1640

1641 - `"claude-opus-4-5"`

1642

1643 Powerful intelligence for long-running agents and coding

1644

1645 - `"claude-opus-4-5-20251101"`

1646

1647 Powerful intelligence for long-running agents and coding

1648

1649 - `"claude-sonnet-4-5"`

1650

1651 High-performance model for agents and coding

1652

1653 - `"claude-sonnet-4-5-20250929"`

1654

1655 High-performance model for agents and coding

1656

1657 - `string`

1658

1659 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`

1660

1661 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.

1662

1663 - `BetaManagedAgentsEffortLow object`

1664

1665 Low effort. Favors latency over reasoning depth.

1666

1667 - `type: "low"`

1668

1669 - `BetaManagedAgentsEffortMedium object`

1670

1671 Medium effort. Balances latency and reasoning depth.

1672

1673 - `type: "medium"`

1674

1675 - `BetaManagedAgentsEffortHigh object`

1676

1677 High effort. Favors reasoning depth.

1678

1679 - `type: "high"`

1680

1681 - `BetaManagedAgentsEffortXhigh object`

1682

1683 Extra-high effort. Not all models accept this level.

1684

1685 - `type: "xhigh"`

1686

1687 - `BetaManagedAgentsEffortMax object`

1688

1689 Maximum effort. Favors reasoning depth over latency.

1690

1691 - `type: "max"`

1692

1693 - `inference_geo: optional string`

1694

1695 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.

1696

1697 - `speed: optional "standard" or "fast"`

1698

1699 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.

1700

1701 - `"standard"`

1702

1703 - `"fast"`

1704

1705 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`

1706

1707 Resolved coordinator topology with full agent definitions for each roster member.

1708

1709 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`

1710

1711 Full `agent` definitions the coordinator may spawn as session threads.

1712

1713 - `BetaManagedAgentsSessionThreadAgent object`

1714

1715 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`.

1716

1717 - `id: string`

1718

1719 - `description: string or null`

1720

1721 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1722

1723 - `name: string`

1724

1725 - `type: "url"`

1726

1727 - `url: string`

1728

1729 - `model: BetaManagedAgentsModelConfig`

1730

1731 Model identifier and configuration.

1732

1733 - `name: string`

1734

1735 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

1736

1737 - `BetaManagedAgentsAnthropicSkill object`

1738

1739 A resolved Anthropic-managed skill.

1740

1741 - `skill_id: string`

1742

1743 - `type: "anthropic"`

1744

1745 - `version: string`

1746

1747 - `BetaManagedAgentsCustomSkill object`

1748

1749 A resolved user-created custom skill.

1750

1751 - `skill_id: string`

1752

1753 - `type: "custom"`

1754

1755 - `version: string`

1756

1757 - `system: string or null`

1758

1759 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`

1760

1761 - `BetaManagedAgentsAgentToolset20260401 object`

1762

1763 - `configs: array of BetaManagedAgentsAgentToolConfig`

1764

1765 - `BetaManagedAgentsBashToolConfig object`

1766

1767 Configuration for the bash tool.

1768

1769 - `enabled: boolean`

1770

1771 - `name: "bash"`

1772

1773 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1774

1775 Permission policy for tool execution.

1776

1777 - `BetaManagedAgentsAlwaysAllowPolicy object`

1778

1779 Tool calls are automatically approved without user confirmation.

1780

1781 - `type: "always_allow"`

1782

1783 - `BetaManagedAgentsAlwaysAskPolicy object`

1784

1785 Tool calls require user confirmation before execution.

1786

1787 - `type: "always_ask"`

1788

1789 - `type: "bash"`

1790

1791 - `BetaManagedAgentsEditToolConfig object`

1792

1793 Configuration for the edit tool.

1794

1795 - `enabled: boolean`

1796

1797 - `name: "edit"`

1798

1799 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1800

1801 Permission policy for tool execution.

1802

1803 - `BetaManagedAgentsAlwaysAllowPolicy object`

1804

1805 Tool calls are automatically approved without user confirmation.

1806

1807 - `BetaManagedAgentsAlwaysAskPolicy object`

1808

1809 Tool calls require user confirmation before execution.

1810

1811 - `type: "edit"`

1812

1813 - `BetaManagedAgentsReadToolConfig object`

1814

1815 Configuration for the read tool.

1816

1817 - `enabled: boolean`

1818

1819 - `name: "read"`

1820

1821 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1822

1823 Permission policy for tool execution.

1824

1825 - `BetaManagedAgentsAlwaysAllowPolicy object`

1826

1827 Tool calls are automatically approved without user confirmation.

1828

1829 - `BetaManagedAgentsAlwaysAskPolicy object`

1830

1831 Tool calls require user confirmation before execution.

1832

1833 - `type: "read"`

1834

1835 - `BetaManagedAgentsWriteToolConfig object`

1836

1837 Configuration for the write tool.

1838

1839 - `enabled: boolean`

1840

1841 - `name: "write"`

1842

1843 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1844

1845 Permission policy for tool execution.

1846

1847 - `BetaManagedAgentsAlwaysAllowPolicy object`

1848

1849 Tool calls are automatically approved without user confirmation.

1850

1851 - `BetaManagedAgentsAlwaysAskPolicy object`

1852

1853 Tool calls require user confirmation before execution.

1854

1855 - `type: "write"`

1856

1857 - `BetaManagedAgentsGlobToolConfig object`

1858

1859 Configuration for the glob tool.

1860

1861 - `enabled: boolean`

1862

1863 - `name: "glob"`

1864

1865 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1866

1867 Permission policy for tool execution.

1868

1869 - `BetaManagedAgentsAlwaysAllowPolicy object`

1870

1871 Tool calls are automatically approved without user confirmation.

1872

1873 - `BetaManagedAgentsAlwaysAskPolicy object`

1874

1875 Tool calls require user confirmation before execution.

1876

1877 - `type: "glob"`

1878

1879 - `BetaManagedAgentsGrepToolConfig object`

1880

1881 Configuration for the grep tool.

1882

1883 - `enabled: boolean`

1884

1885 - `name: "grep"`

1886

1887 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1888

1889 Permission policy for tool execution.

1890

1891 - `BetaManagedAgentsAlwaysAllowPolicy object`

1892

1893 Tool calls are automatically approved without user confirmation.

1894

1895 - `BetaManagedAgentsAlwaysAskPolicy object`

1896

1897 Tool calls require user confirmation before execution.

1898

1899 - `type: "grep"`

1900

1901 - `BetaManagedAgentsWebFetchToolConfig object`

1902

1903 Configuration for the web_fetch tool.

1904

1905 - `enabled: boolean`

1906

1907 - `name: "web_fetch"`

1908

1909 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1910

1911 Permission policy for tool execution.

1912

1913 - `BetaManagedAgentsAlwaysAllowPolicy object`

1914

1915 Tool calls are automatically approved without user confirmation.

1916

1917 - `BetaManagedAgentsAlwaysAskPolicy object`

1918

1919 Tool calls require user confirmation before execution.

1920

1921 - `type: "web_fetch"`

1922

1923 - `allowed_domains: optional array of string`

1924

1925 - `blocked_domains: optional array of string`

1926

1927 - `max_content_tokens: optional number or null`

1928

1929 format: int32

1930

1931 - `BetaManagedAgentsWebSearchToolConfig object`

1932

1933 Configuration for the web_search tool.

1934

1935 - `enabled: boolean`

1936

1937 - `name: "web_search"`

1938

1939 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1940

1941 Permission policy for tool execution.

1942

1943 - `BetaManagedAgentsAlwaysAllowPolicy object`

1944

1945 Tool calls are automatically approved without user confirmation.

1946

1947 - `BetaManagedAgentsAlwaysAskPolicy object`

1948

1949 Tool calls require user confirmation before execution.

1950

1951 - `type: "web_search"`

1952

1953 - `allowed_domains: optional array of string`

1954

1955 - `blocked_domains: optional array of string`

1956

1957 - `user_location: optional BetaManagedAgentsUserLocation or null`

1958

1959 Approximate user location for search result localization.

1960

1961 - `type: "approximate"`

1962

1963 Location precision. Only "approximate" is supported.

1964

1965 - `city: optional string or null`

1966

1967 City name.

1968

1969 minLength: 1, maxLength: 255

1970

1971 - `country: optional string or null`

1972

1973 Two-letter ISO 3166-1 country code, uppercase.

1974

1975 - `region: optional string or null`

1976

1977 Region or state name.

1978

1979 minLength: 1, maxLength: 255

1980

1981 - `timezone: optional string or null`

1982

1983 IANA timezone identifier, e.g. "America/Los_Angeles".

1984

1985 minLength: 1, maxLength: 255

1986

1987 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`

1988

1989 Resolved default configuration for agent tools.

1990

1991 - `enabled: boolean`

1992

1993 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1994

1995 Permission policy for tool execution.

1996

1997 - `BetaManagedAgentsAlwaysAllowPolicy object`

1998

1999 Tool calls are automatically approved without user confirmation.

2000

2001 - `BetaManagedAgentsAlwaysAskPolicy object`

2002

2003 Tool calls require user confirmation before execution.

2004

2005 - `type: "agent_toolset_20260401"`

2006

2007 - `BetaManagedAgentsMCPToolset object`

2008

2009 - `configs: array of BetaManagedAgentsMCPToolConfig`

2010

2011 - `enabled: boolean`

2012

2013 - `name: string`

2014

2015 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

2016

2017 Permission policy for tool execution.

2018

2019 - `BetaManagedAgentsAlwaysAllowPolicy object`

2020

2021 Tool calls are automatically approved without user confirmation.

2022

2023 - `BetaManagedAgentsAlwaysAskPolicy object`

2024

2025 Tool calls require user confirmation before execution.

2026

2027 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

2028

2029 Resolved default configuration for all tools from an MCP server.

2030

2031 - `enabled: boolean`

2032

2033 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

2034

2035 Permission policy for tool execution.

2036

2037 - `BetaManagedAgentsAlwaysAllowPolicy object`

2038

2039 Tool calls are automatically approved without user confirmation.

2040

2041 - `BetaManagedAgentsAlwaysAskPolicy object`

2042

2043 Tool calls require user confirmation before execution.

2044

2045 - `mcp_server_name: string`

2046

2047 - `type: "mcp_toolset"`

2048

2049 - `BetaManagedAgentsCustomTool object`

2050

2051 A custom tool as returned in API responses.

2052

2053 - `description: string`

2054

2055 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

2056

2057 JSON Schema for custom tool input parameters.

2058

2059 - `type: "object"`

2060

2061 - `properties: optional map[unknown] or null`

2062

2063 - `required: optional array of string or null`

2064

2065 - `name: string`

2066

2067 - `type: "custom"`

2068

2069 - `type: "agent"`

2070

2071 - `version: number`

2072

2073 format: int32

2074

2075 - `BetaManagedAgentsAdvisor object`

2076

2077 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

2078

2079 - `model: string`

2080

2081 The advisor model id.

2082

2083 - `type: "advisor"`

2084

2085 - `type: "coordinator"`

2086

2087 - `name: string`

2088

2089 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

2090

2091 - `BetaManagedAgentsAnthropicSkill object`

2092

2093 A resolved Anthropic-managed skill.

2094

2095 - `BetaManagedAgentsCustomSkill object`

2096

2097 A resolved user-created custom skill.

2098

2099 - `system: string or null`

2100

2101 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`

2102

2103 - `BetaManagedAgentsAgentToolset20260401 object`

2104

2105 - `BetaManagedAgentsMCPToolset object`

2106

2107 - `BetaManagedAgentsCustomTool object`

2108

2109 A custom tool as returned in API responses.

2110

2111 - `type: "agent"`

2112

2113 - `version: number`

2114

2115 format: int32

2116

2117 - `budget: optional BetaManagedAgentsBudgetLimit or null`

2118

2119 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

2120

2121 - `max_list_cost: BetaMonetaryAmount`

2122

2123 A monetary amount in a specific currency.

2124

2125 - `amount: string`

2126

2127 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

2128

2129 - `currency: BetaCurrency`

2130

2131 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.

2132

2133 - `type: "limit"`

2134

2135 - `metadata: optional map[string]`

2136

2137 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.

2138

2139 - `title: optional string or null`

2140

2141 The session's new title. Present only when the update changed it.

2142

2143 - `BetaManagedAgentsSystemMessageEvent object`

2144

2145 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

2146

2147 - `id: string`

2148

2149 Unique identifier for this event.

2150

2151 - `content: array of BetaManagedAgentsSystemContentBlock`

2152

2153 System content blocks. Text-only.

2154

2155 - `text: string`

2156

2157 The text content.

2158

2159 minLength: 1

2160

2161 - `type: "text"`

2162

2163 - `type: "system.message"`

2164

2165 - `processed_at: optional string or null`

2166

2167 A timestamp in RFC 3339 format

2168

2169 format: date-time

2170

21712286 - `BetaManagedAgentsSessionUsageEvent object`

21722287

21732288 Periodic snapshot of the session's cumulative usage and tracked list cost.

21742289

2175 - `id: string`

2176

2177 Unique identifier for this event.

2178

2179 - `processed_at: string`

2180

2181 A timestamp in RFC 3339 format

2182

2183 format: date-time

2184

21852290 - `type: "session.usage"`

2291

2292 - `id: string`

2293

2294 Unique identifier for this event.

2295

2296 - `processed_at: string`

2297

2298 A timestamp in RFC 3339 format

2299

2300 format: date-time

21862301

21872302 - `usage: BetaManagedAgentsSessionUsageSnapshot`

21882303

21892304

This page’s history 11 edits

21 Sep 2026 +4 −4
16 Sep 2026 +3 −1
15 Sep 2026 +6 −6
11 Sep 2026 +0 −6
10 Sep 2026 +2122 −2007 · this one
1 Sep 2026 +12 −2

The page’s own history →

Where it came from

The captureapi
Upstream pageplatform.claude.com

List Session Thread Events changed

The whole hunk