List Sessions changedapi/beta/sessions/list
Nearest release: v2.1.268, published under an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+386added
Lines−331removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits26to this page, all time
The whole hunk
from line 1, old and new numbered
/
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
No line in this hunk matches that.