Repository Public
1---2title: List Agents3url: https://platform.claude.com/docs/en/api/beta/agents/list4---56# List Agents78**GET** `/v1/agents`910List Agents1112## Query parameters1314- `"created_at[gte]": optional string`1516 Return agents created at or after this time (inclusive).1718 format: date-time1920- `"created_at[lte]": optional string`2122 Return agents created at or before this time (inclusive).2324 format: date-time2526- `include_archived: optional boolean`2728 Include archived agents in results. Defaults to false.2930- `limit: optional number`3132 Maximum results per page. Default 20, maximum 100.3334 format: int323536- `page: optional string`3738 Opaque pagination cursor from a previous response.3940## Headers4142- `"anthropic-beta": optional array of AnthropicBeta`4344 Optional header to specify the beta version(s) you want to use.4546 - `string`4748 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`4950 - `"message-batches-2024-09-24"`5152 - `"prompt-caching-2024-07-31"`5354 - `"computer-use-2024-10-22"`5556 - `"computer-use-2025-01-24"`5758 - `"pdfs-2024-09-25"`5960 - `"token-counting-2024-11-01"`6162 - `"token-efficient-tools-2025-02-19"`6364 - `"output-128k-2025-02-19"`6566 - `"files-api-2025-04-14"`6768 - `"mcp-client-2025-04-04"`6970 - `"mcp-client-2025-11-20"`7172 - `"dev-full-thinking-2025-05-14"`7374 - `"interleaved-thinking-2025-05-14"`7576 - `"code-execution-2025-05-22"`7778 - `"extended-cache-ttl-2025-04-11"`7980 - `"context-1m-2025-08-07"`8182 - `"context-management-2025-06-27"`8384 - `"model-context-window-exceeded-2025-08-26"`8586 - `"skills-2025-10-02"`8788 - `"fast-mode-2026-02-01"`8990 - `"output-300k-2026-03-24"`9192 - `"user-profiles-2026-03-24"`9394 - `"user-profiles-2026-08-18"`9596 - `"user-profiles-2026-09-04"`9798 - `"advisor-tool-2026-03-01"`99100 - `"managed-agents-2026-04-01"`101102 - `"cache-diagnosis-2026-04-07"`103104 - `"dreaming-2026-04-21"`105106 - `"thinking-token-count-2026-05-13"`107108 - `"server-side-fallback-2026-06-01"`109110 - `"server-side-fallback-2026-07-01"`111112 - `"fallback-credit-2026-06-01"`113114 - `"fallback-credit-2026-07-01"`115116 - `"agent-memory-2026-07-22"`117118 - `"mid-conversation-tool-changes-2026-07-01"`119120 - `"compact-2026-01-12"`121122 - `"computer-use-2025-11-24"`123124 - `"mcp-tunnels-2026-06-22"`125126 - `"structured-outputs-2025-11-13"`127128 - `"task-budgets-2026-03-13"`129130 - `"thinking-display-updates-2026-08-18"`131132 - `"ce-user-management-2026-07-13"`133134 - `"mid-conversation-output-config-2026-07-01"`135136 - `"thinking-binding-controls-2026-08-01"`137138 - `"mid-conversation-system-clear-at-2026-08-21"`139140 - `"compact-2026-09-04"`141142- `"anthropic-workspace-id": optional string`143144## Returns145146- `data: array of BetaManagedAgentsAgent`147148 List of agents.149150 - `type: "agent"`151152 - `id: string`153154 - `archived_at: string or null`155156 A timestamp in RFC 3339 format157158 format: date-time159160 - `created_at: string`161162 A timestamp in RFC 3339 format163164 format: date-time165166 - `description: string or null`167168 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`169170 - `type: "url"`171172 - `name: string`173174 - `url: string`175176 - `metadata: map[string]`177178 - `model: BetaManagedAgentsModelConfig`179180 Model identifier and configuration.181182 - `id: BetaManagedAgentsModel`183184 The model that will power your agent.185186 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.187188 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`189190 The model that will power your agent.191192 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.193194 - `"claude-fable-5-1"`195196 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows197198 - `"claude-sonnet-5"`199200 High-performance model for coding and agents201202 - `"claude-fable-5"`203204 Next generation of intelligence for the hardest knowledge work and coding problems205206 - `"claude-opus-5"`207208 Powerful intelligence for long-running agents and coding209210 - `"claude-opus-4-8"`211212 Powerful intelligence for long-running agents and coding213214 - `"claude-opus-4-7"`215216 Powerful intelligence for long-running agents and coding217218 - `"claude-opus-4-6"`219220 Powerful intelligence for long-running agents and coding221222 - `"claude-sonnet-4-6"`223224 Best combination of speed and intelligence225226 - `"claude-haiku-4-5"`227228 Fastest model with near-frontier intelligence229230 - `"claude-haiku-4-5-20251001"`231232 Fastest model with near-frontier intelligence233234 - `"claude-opus-4-5"`235236 Powerful intelligence for long-running agents and coding237238 - `"claude-opus-4-5-20251101"`239240 Powerful intelligence for long-running agents and coding241242 - `"claude-sonnet-4-5"`243244 High-performance model for agents and coding245246 - `"claude-sonnet-4-5-20250929"`247248 High-performance model for agents and coding249250 - `string`251252 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`253254 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.255256 - `BetaManagedAgentsEffortLow object`257258 Low effort. Favors latency over reasoning depth.259260 - `type: "low"`261262 - `BetaManagedAgentsEffortMedium object`263264 Medium effort. Balances latency and reasoning depth.265266 - `type: "medium"`267268 - `BetaManagedAgentsEffortHigh object`269270 High effort. Favors reasoning depth.271272 - `type: "high"`273274 - `BetaManagedAgentsEffortXhigh object`275276 Extra-high effort. Not all models accept this level.277278 - `type: "xhigh"`279280 - `BetaManagedAgentsEffortMax object`281282 Maximum effort. Favors reasoning depth over latency.283284 - `type: "max"`285286 - `inference_geo: optional string`287288 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.289290 - `speed: optional "standard" or "fast"`291292 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.293294 - `"standard"`295296 - `"fast"`297298 - `multiagent: BetaManagedAgentsMultiagent or null`299300 Resolved coordinator topology with a concrete agent roster.301302 - `type: "coordinator"`303304 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`305306 Agents the coordinator may spawn as session threads, each resolved to a specific version.307308 - `BetaManagedAgentsAgentReference object`309310 A resolved agent reference with a concrete version.311312 - `type: "agent"`313314 - `id: string`315316 - `version: number`317318 format: int32319320 - `BetaManagedAgentsAdvisor object`321322 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.323324 - `type: "advisor"`325326 - `model: string`327328 The advisor model id.329330 - `name: string`331332 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`333334 - `BetaManagedAgentsAnthropicSkill object`335336 A resolved Anthropic-managed skill.337338 - `type: "anthropic"`339340 - `skill_id: string`341342 - `version: string`343344 - `BetaManagedAgentsCustomSkill object`345346 A resolved user-created custom skill.347348 - `type: "custom"`349350 - `skill_id: string`351352 - `version: string`353354 - `system: string or null`355356 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`357358 - `BetaManagedAgentsAgentToolset20260401 object`359360 - `type: "agent_toolset_20260401"`361362 - `configs: array of BetaManagedAgentsAgentToolConfig`363364 - `BetaManagedAgentsBashToolConfig object`365366 Configuration for the bash tool.367368 - `type: "bash"`369370 - `enabled: boolean`371372 - `name: "bash"`373374 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`375376 Permission policy for tool execution.377378 - `BetaManagedAgentsAlwaysAllowPolicy object`379380 Tool calls are automatically approved without user confirmation.381382 - `type: "always_allow"`383384 - `BetaManagedAgentsAlwaysAskPolicy object`385386 Tool calls require user confirmation before execution.387388 - `type: "always_ask"`389390 - `BetaManagedAgentsAutoPolicy object`391392 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.393394 - `type: "auto"`395396 - `BetaManagedAgentsEditToolConfig object`397398 Configuration for the edit tool.399400 - `type: "edit"`401402 - `enabled: boolean`403404 - `name: "edit"`405406 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`407408 Permission policy for tool execution.409410 - `BetaManagedAgentsAlwaysAllowPolicy object`411412 Tool calls are automatically approved without user confirmation.413414 - `BetaManagedAgentsAlwaysAskPolicy object`415416 Tool calls require user confirmation before execution.417418 - `BetaManagedAgentsAutoPolicy object`419420 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.421422 - `BetaManagedAgentsReadToolConfig object`423424 Configuration for the read tool.425426 - `type: "read"`427428 - `enabled: boolean`429430 - `name: "read"`431432 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`433434 Permission policy for tool execution.435436 - `BetaManagedAgentsAlwaysAllowPolicy object`437438 Tool calls are automatically approved without user confirmation.439440 - `BetaManagedAgentsAlwaysAskPolicy object`441442 Tool calls require user confirmation before execution.443444 - `BetaManagedAgentsAutoPolicy object`445446 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.447448 - `BetaManagedAgentsWriteToolConfig object`449450 Configuration for the write tool.451452 - `type: "write"`453454 - `enabled: boolean`455456 - `name: "write"`457458 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`459460 Permission policy for tool execution.461462 - `BetaManagedAgentsAlwaysAllowPolicy object`463464 Tool calls are automatically approved without user confirmation.465466 - `BetaManagedAgentsAlwaysAskPolicy object`467468 Tool calls require user confirmation before execution.469470 - `BetaManagedAgentsAutoPolicy object`471472 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.473474 - `BetaManagedAgentsGlobToolConfig object`475476 Configuration for the glob tool.477478 - `type: "glob"`479480 - `enabled: boolean`481482 - `name: "glob"`483484 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`485486 Permission policy for tool execution.487488 - `BetaManagedAgentsAlwaysAllowPolicy object`489490 Tool calls are automatically approved without user confirmation.491492 - `BetaManagedAgentsAlwaysAskPolicy object`493494 Tool calls require user confirmation before execution.495496 - `BetaManagedAgentsAutoPolicy object`497498 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.499500 - `BetaManagedAgentsGrepToolConfig object`501502 Configuration for the grep tool.503504 - `type: "grep"`505506 - `enabled: boolean`507508 - `name: "grep"`509510 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`511512 Permission policy for tool execution.513514 - `BetaManagedAgentsAlwaysAllowPolicy object`515516 Tool calls are automatically approved without user confirmation.517518 - `BetaManagedAgentsAlwaysAskPolicy object`519520 Tool calls require user confirmation before execution.521522 - `BetaManagedAgentsAutoPolicy object`523524 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.525526 - `BetaManagedAgentsWebFetchToolConfig object`527528 Configuration for the web_fetch tool.529530 - `type: "web_fetch"`531532 - `enabled: boolean`533534 - `name: "web_fetch"`535536 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`537538 Permission policy for tool execution.539540 - `BetaManagedAgentsAlwaysAllowPolicy object`541542 Tool calls are automatically approved without user confirmation.543544 - `BetaManagedAgentsAlwaysAskPolicy object`545546 Tool calls require user confirmation before execution.547548 - `BetaManagedAgentsAutoPolicy object`549550 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.551552 - `allowed_domains: optional array of string`553554 - `blocked_domains: optional array of string`555556 - `max_content_tokens: optional number or null`557558 format: int32559560 - `BetaManagedAgentsWebSearchToolConfig object`561562 Configuration for the web_search tool.563564 - `type: "web_search"`565566 - `enabled: boolean`567568 - `name: "web_search"`569570 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`571572 Permission policy for tool execution.573574 - `BetaManagedAgentsAlwaysAllowPolicy object`575576 Tool calls are automatically approved without user confirmation.577578 - `BetaManagedAgentsAlwaysAskPolicy object`579580 Tool calls require user confirmation before execution.581582 - `BetaManagedAgentsAutoPolicy object`583584 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.585586 - `allowed_domains: optional array of string`587588 - `blocked_domains: optional array of string`589590 - `user_location: optional BetaManagedAgentsUserLocation or null`591592 Approximate user location for search result localization.593594 - `type: "approximate"`595596 Location precision. Only "approximate" is supported.597598 - `city: optional string or null`599600 City name.601602 minLength: 1, maxLength: 255603604 - `country: optional string or null`605606 Two-letter ISO 3166-1 country code, uppercase.607608 - `region: optional string or null`609610 Region or state name.611612 minLength: 1, maxLength: 255613614 - `timezone: optional string or null`615616 IANA timezone identifier, e.g. "America/Los_Angeles".617618 minLength: 1, maxLength: 255619620 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`621622 Resolved default configuration for agent tools.623624 - `enabled: boolean`625626 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`627628 Permission policy for tool execution.629630 - `BetaManagedAgentsAlwaysAllowPolicy object`631632 Tool calls are automatically approved without user confirmation.633634 - `BetaManagedAgentsAlwaysAskPolicy object`635636 Tool calls require user confirmation before execution.637638 - `BetaManagedAgentsAutoPolicy object`639640 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.641642 - `BetaManagedAgentsMCPToolset object`643644 - `type: "mcp_toolset"`645646 - `configs: array of BetaManagedAgentsMCPToolConfig`647648 - `enabled: boolean`649650 - `name: string`651652 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`653654 Permission policy for tool execution.655656 - `BetaManagedAgentsAlwaysAllowPolicy object`657658 Tool calls are automatically approved without user confirmation.659660 - `BetaManagedAgentsAlwaysAskPolicy object`661662 Tool calls require user confirmation before execution.663664 - `BetaManagedAgentsAutoPolicy object`665666 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.667668 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`669670 Resolved default configuration for all tools from an MCP server.671672 - `enabled: boolean`673674 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`675676 Permission policy for tool execution.677678 - `BetaManagedAgentsAlwaysAllowPolicy object`679680 Tool calls are automatically approved without user confirmation.681682 - `BetaManagedAgentsAlwaysAskPolicy object`683684 Tool calls require user confirmation before execution.685686 - `BetaManagedAgentsAutoPolicy object`687688 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.689690 - `mcp_server_name: string`691692 - `BetaManagedAgentsCustomTool object`693694 A custom tool as returned in API responses.695696 - `type: "custom"`697698 - `description: string`699700 - `input_schema: BetaManagedAgentsCustomToolInputSchema`701702 JSON Schema for custom tool input parameters.703704 - `type: "object"`705706 - `properties: optional map[unknown] or null`707708 - `required: optional array of string or null`709710 - `name: string`711712 - `updated_at: string`713714 A timestamp in RFC 3339 format715716 format: date-time717718 - `version: number`719720 The agent's current version. Starts at 1 and increments when the agent is modified.721722 format: int32723724- `next_page: optional string or null`725726 Opaque cursor for the next page. Null when no more results.727728## Example729730```bash731curl https://api.anthropic.com/v1/agents \732 -H 'anthropic-version: 2023-06-01' \733 -H 'anthropic-beta: managed-agents-2026-04-01' \734 -H "X-Api-Key: $ANTHROPIC_API_KEY"735```736737### Response (200)738739```json740{741 "data": [742 {743 "id": "agent_011CZkYpogX7uDKUyvBTophP",744 "archived_at": null,745 "created_at": "2026-03-15T10:00:00Z",746 "description": "A general-purpose starter agent.",747 "mcp_servers": [748 {749 "name": "example-mcp",750 "type": "url",751 "url": "https://example-server.modelcontextprotocol.io/sse"752 }753 ],754 "metadata": {755 "foo": "bar"756 },757 "model": {758 "id": "claude-opus-5",759 "effort": {760 "type": "low"761 },762 "inference_geo": "inference_geo",763 "speed": "standard"764 },765 "multiagent": {766 "agents": [767 {768 "id": "agent_011CZkYqphY8vELVzwCUpqiQ",769 "type": "agent",770 "version": 1771 }772 ],773 "type": "coordinator"774 },775 "name": "My First Agent",776 "skills": [777 {778 "skill_id": "xlsx",779 "type": "anthropic",780 "version": "1"781 },782 {783 "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",784 "type": "custom",785 "version": "2"786 }787 ],788 "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",789 "tools": [790 {791 "configs": [792 {793 "enabled": true,794 "name": "bash",795 "permission_policy": {796 "type": "always_allow"797 },798 "type": "bash"799 }800 ],801 "default_config": {802 "enabled": true,803 "permission_policy": {804 "type": "always_ask"805 }806 },807 "type": "agent_toolset_20260401"808 }809 ],810 "type": "agent",811 "updated_at": "2026-03-15T10:00:00Z",812 "version": 1813 }814 ],815 "next_page": "next_page"816}817```818