The whole hunk
from line 1, old and new numbered
/
lines
from line 1
1---
2title: List Sessions
3url: https://platform.claude.com/docs/en/api/beta/sessions/list
4---
5
16# List Sessions
27
38**GET** `/v1/sessions`
from line 95
9095
9196 - `string`
9297
93 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
98 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
9499
95100 - `"message-batches-2024-09-24"`
96101
from line 143
138143
139144 - `"user-profiles-2026-08-18"`
140145
146 - `"user-profiles-2026-09-04"`
147
141148 - `"advisor-tool-2026-03-01"`
142149
143150 - `"managed-agents-2026-04-01"`
from line 187
180187
181188 - `"mid-conversation-system-clear-at-2026-08-21"`
182189
190- `"anthropic-workspace-id": optional string`
191
183192## Returns
184193
185194- `data: optional array of BetaManagedAgentsSession`
from line 195
186195
187196 List of sessions.
188197
198 - `type: "session"`
199
189200 - `id: string`
190201
191202 - `agent: BetaManagedAgentsSessionAgent`
from line 203
192203
193204 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
194205
206 - `type: "agent"`
207
195208 - `id: string`
196209
197210 - `description: string or null`
from line 211
198211
199212 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
200213
201 - `name: string`
202
203214 - `type: "url"`
204215
216 - `name: string`
217
205218 - `url: string`
206219
207220 - `model: BetaManagedAgentsModelConfig`
from line 341
328341
329342 Resolved coordinator topology with full agent definitions for each roster member.
330343
344 - `type: "coordinator"`
345
331346 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
332347
333348 Full `agent` definitions the coordinator may spawn as session threads.
from line 351
336351
337352 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`.
338353
354 - `type: "agent"`
355
339356 - `id: string`
340357
341358 - `description: string or null`
from line 359
342359
343360 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
344361
345 - `name: string`
346
347362 - `type: "url"`
348363
364 - `name: string`
365
349366 - `url: string`
350367
351368 - `model: BetaManagedAgentsModelConfig`
from line 377
360377
361378 A resolved Anthropic-managed skill.
362379
363 - `skill_id: string`
364
365380 - `type: "anthropic"`
366381
382 - `skill_id: string`
383
367384 - `version: string`
368385
369386 - `BetaManagedAgentsCustomSkill object`
from line 387
370387
371388 A resolved user-created custom skill.
372389
373 - `skill_id: string`
374
375390 - `type: "custom"`
376391
392 - `skill_id: string`
393
377394 - `version: string`
378395
379396 - `system: string or null`
from line 399
382399
383400 - `BetaManagedAgentsAgentToolset20260401 object`
384401
402 - `type: "agent_toolset_20260401"`
403
385404 - `configs: array of BetaManagedAgentsAgentToolConfig`
386405
387406 - `BetaManagedAgentsBashToolConfig object`
from line 407
388407
389408 Configuration for the bash tool.
390409
410 - `type: "bash"`
411
391412 - `enabled: boolean`
392413
393414 - `name: "bash"`
394415
395 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
416 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
396417
397418 Permission policy for tool execution.
398419
from line 429
408429
409430 - `type: "always_ask"`
410431
411 - `type: "bash"`
432 - `BetaManagedAgentsAutoPolicy object`
412433
434 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.
435
436 - `type: "auto"`
437
413438 - `BetaManagedAgentsEditToolConfig object`
414439
415440 Configuration for the edit tool.
416441
442 - `type: "edit"`
443
417444 - `enabled: boolean`
418445
419446 - `name: "edit"`
420447
421 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
448 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
422449
423450 Permission policy for tool execution.
424451
from line 457
430457
431458 Tool calls require user confirmation before execution.
432459
433 - `type: "edit"`
460 - `BetaManagedAgentsAutoPolicy object`
434461
462 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.
463
435464 - `BetaManagedAgentsReadToolConfig object`
436465
437466 Configuration for the read tool.
438467
468 - `type: "read"`
469
439470 - `enabled: boolean`
440471
441472 - `name: "read"`
442473
443 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
474 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
444475
445476 Permission policy for tool execution.
446477
from line 483
452483
453484 Tool calls require user confirmation before execution.
454485
455 - `type: "read"`
486 - `BetaManagedAgentsAutoPolicy object`
456487
488 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.
489
457490 - `BetaManagedAgentsWriteToolConfig object`
458491
459492 Configuration for the write tool.
460493
494 - `type: "write"`
495
461496 - `enabled: boolean`
462497
463498 - `name: "write"`
464499
465 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
500 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
466501
467502 Permission policy for tool execution.
468503
from line 509
474509
475510 Tool calls require user confirmation before execution.
476511
477 - `type: "write"`
512 - `BetaManagedAgentsAutoPolicy object`
478513
514 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.
515
479516 - `BetaManagedAgentsGlobToolConfig object`
480517
481518 Configuration for the glob tool.
482519
520 - `type: "glob"`
521
483522 - `enabled: boolean`
484523
485524 - `name: "glob"`
486525
487 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
526 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
488527
489528 Permission policy for tool execution.
490529
from line 535
496535
497536 Tool calls require user confirmation before execution.
498537
499 - `type: "glob"`
538 - `BetaManagedAgentsAutoPolicy object`
500539
540 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.
541
501542 - `BetaManagedAgentsGrepToolConfig object`
502543
503544 Configuration for the grep tool.
504545
546 - `type: "grep"`
547
505548 - `enabled: boolean`
506549
507550 - `name: "grep"`
508551
509 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
552 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
510553
511554 Permission policy for tool execution.
512555
from line 561
518561
519562 Tool calls require user confirmation before execution.
520563
521 - `type: "grep"`
564 - `BetaManagedAgentsAutoPolicy object`
522565
566 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.
567
523568 - `BetaManagedAgentsWebFetchToolConfig object`
524569
525570 Configuration for the web_fetch tool.
526571
572 - `type: "web_fetch"`
573
527574 - `enabled: boolean`
528575
529576 - `name: "web_fetch"`
530577
531 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
578 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
532579
533580 Permission policy for tool execution.
534581
from line 587
540587
541588 Tool calls require user confirmation before execution.
542589
543 - `type: "web_fetch"`
590 - `BetaManagedAgentsAutoPolicy object`
544591
592 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.
593
545594 - `allowed_domains: optional array of string`
546595
547596 - `blocked_domains: optional array of string`
from line 603
554603
555604 Configuration for the web_search tool.
556605
606 - `type: "web_search"`
607
557608 - `enabled: boolean`
558609
559610 - `name: "web_search"`
560611
561 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
612 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
562613
563614 Permission policy for tool execution.
564615
from line 621
570621
571622 Tool calls require user confirmation before execution.
572623
573 - `type: "web_search"`
624 - `BetaManagedAgentsAutoPolicy object`
574625
626 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.
627
575628 - `allowed_domains: optional array of string`
576629
577630 - `blocked_domains: optional array of string`
from line 665
612665
613666 - `enabled: boolean`
614667
615 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
668 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
616669
617670 Permission policy for tool execution.
618671
from line 677
624677
625678 Tool calls require user confirmation before execution.
626679
627 - `type: "agent_toolset_20260401"`
680 - `BetaManagedAgentsAutoPolicy object`
628681
682 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.
683
629684 - `BetaManagedAgentsMCPToolset object`
630685
686 - `type: "mcp_toolset"`
687
631688 - `configs: array of BetaManagedAgentsMCPToolConfig`
632689
633690 - `enabled: boolean`
from line 691
634691
635692 - `name: string`
636693
637 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
694 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
638695
639696 Permission policy for tool execution.
640697
from line 703
646703
647704 Tool calls require user confirmation before execution.
648705
706 - `BetaManagedAgentsAutoPolicy object`
707
708 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.
709
649710 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
650711
651712 Resolved default configuration for all tools from an MCP server.
from line 713
652713
653714 - `enabled: boolean`
654715
655 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
716 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
656717
657718 Permission policy for tool execution.
658719
from line 725
664725
665726 Tool calls require user confirmation before execution.
666727
667 - `mcp_server_name: string`
728 - `BetaManagedAgentsAutoPolicy object`
668729
669 - `type: "mcp_toolset"`
730 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.
670731
732 - `mcp_server_name: string`
733
671734 - `BetaManagedAgentsCustomTool object`
672735
673736 A custom tool as returned in API responses.
674737
738 - `type: "custom"`
739
675740 - `description: string`
676741
677742 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
from line 751
686751
687752 - `name: string`
688753
689 - `type: "custom"`
690
691 - `type: "agent"`
692
693754 - `version: number`
694755
695756 format: int32
from line 759
698759
699760 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
700761
762 - `type: "advisor"`
763
701764 - `model: string`
702765
703766 The advisor model id.
704767
705 - `type: "advisor"`
706
707 - `type: "coordinator"`
708
709768 - `name: string`
710769
711770 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
from line 789
730789
731790 A custom tool as returned in API responses.
732791
733 - `type: "agent"`
734
735792 - `version: number`
736793
737794 format: int32
from line 803
746803
747804 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
748805
806 - `type: "limit"`
807
749808 - `max_list_cost: BetaMonetaryAmount`
750809
751810 A monetary amount in a specific currency.
from line 817
758817
759818 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.
760819
761 - `type: "limit"`
762
763820 - `created_at: string`
764821
765822 A timestamp in RFC 3339 format
from line 831
774831
775832 Per-outcome evaluation state. One entry per `define_outcome` event sent to the session.
776833
834 - `type: "outcome_evaluation"`
835
777836 - `completed_at: string or null`
778837
779838 A timestamp in RFC 3339 format
from line 861
802861
803862 Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.
804863
805 - `type: "outcome_evaluation"`
806
807864 - `resources: array of BetaManagedAgentsSessionResource`
808865
809866 - `BetaManagedAgentsGitHubRepositoryResource object`
810867
868 - `type: "github_repository"`
869
811870 - `id: string`
812871
813872 - `created_at: string`
from line 877
818877
819878 - `mount_path: string`
820879
821 - `type: "github_repository"`
822
823880 - `updated_at: string`
824881
825882 A timestamp in RFC 3339 format
from line 889
832889
833890 - `BetaManagedAgentsBranchCheckout object`
834891
892 - `type: "branch"`
893
835894 - `name: string`
836895
837896 Branch name to check out.
from line 897
838897
839898 minLength: 1, maxLength: 255
840899
841 - `type: "branch"`
842
843900 - `BetaManagedAgentsCommitCheckout object`
844901
902 - `type: "commit"`
903
845904 - `sha: string`
846905
847906 Full commit SHA to check out.
from line 907
848907
849908 minLength: 7, maxLength: 64
850909
851 - `type: "commit"`
852
853910 - `BetaManagedAgentsFileResource object`
854911
912 - `type: "file"`
913
855914 - `id: string`
856915
857916 - `created_at: string`
from line 923
864923
865924 - `mount_path: string`
866925
867 - `type: "file"`
868
869926 - `updated_at: string`
870927
871928 A timestamp in RFC 3339 format
from line 933
876933
877934 A memory store attached to an agent session.
878935
936 - `type: "memory_store"`
937
879938 - `memory_store_id: string`
880939
881940 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
882941
883 - `type: "memory_store"`
884
885942 - `access: optional "read_write" or "read_only" or null`
886943
887944 Access mode for an attached memory store.
from line 994
937994 - `"terminated"`
938995
939996 - `title: string or null`
940
941 - `type: "session"`
942997
943998 - `updated_at: string`
944999