--- title: "List agents" method: GET path: "/agents" tags: ["Agents"] --- # List agents `GET /agents` ## Request - Base URL: `https://api.openai.com/v1` - URL: `https://api.openai.com/v1/agents` - Auth: HTTP bearer Lists reusable agents in the current project. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). ## Query parameters - `limit` integer - `order` 'asc' | 'desc': The order in which paginated resources are returned. - `after` string ## Response `200` A page of agents. - AgentListResource: A page of Agents API resources, with IDs for retrieving additional pages. - `object` 'list', required: The object type, which is always `list`. - `data` AgentResource[], required: The resources returned in this page, in the requested sort order. - `id` string, required: The ID of the reusable agent. - `object` 'agent', required: The object type. Always `agent`. - `created_at` integer, required: The Unix timestamp, in seconds, when the agent was created. - `updated_at` integer, required: The Unix timestamp, in seconds, when the agent was last updated. - `name` string, nullable, required: A human-readable name for the agent, or null if it is unnamed. - `metadata` object, required: Custom string key-value pairs attached to the agent. - `model` string, required: The requested model name used for inference. - `reasoning` ReasoningResource, required: The reasoning configuration used by an agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required: The amount of reasoning effort used by an agent. - `summary` 'concise' | 'detailed' | 'auto', required: The reasoning summary format requested from an agent. - `text` TextResource, required: The text configuration used by an agent. - `format` union, required: The effective output format for generated text. - object: Generates ordinary text without a structured-output constraint. - `type` 'text', required: The type of the object. Always `text`. - object: Constrains generated text to a JSON Schema. - `type` 'json_schema', required: The type of the object. Always `json_schema`. - `schema` object, required: The JSON Schema that generated text must match. - `verbosity` 'low' | 'medium' | 'high', required: The amount of text produced by an agent. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast', required: The service-tier policy configured for an agent. - `instructions` string, nullable, required: Custom instructions appended to the agent's default base instructions. - `tools` PersistedAgentToolResource[], required: Tools available to the agent. - union: A credential-free tool available to a reusable agent. - object: A function defined by the application. - `type` 'function', required: The type of the object. Always `function`. - `name` string, required: The name of the function. - `description` string, required: A description of what the function does. - `parameters` object, required: A JSON Schema object describing the function's arguments. - `defer_loading` boolean, required: Whether the function is deferred and discovered through tool search. - object: Discovers deferred function tools and loads them into the model context. - `type` 'tool_search', required: The type of the object. Always `tool_search`. - object: Enables calling tools from model-generated code. - `type` 'programmatic_tool_calling', required: The type of the object. Always `programmatic_tool_calling`. - `enabled` boolean, required: Whether tools can be called from model-generated code. - object: Tools provided by a remote MCP server without stored credentials. - `type` 'mcp', required: The type of the object. Always `mcp`. - `server_label` string, required: A label used to identify the MCP server in tool calls. - `credential_id` string, nullable, required: The vault credential selected for this MCP server, if any. - `transport` union, required: A credential-free transport used to connect to an MCP server. - object: Connects to an MCP server over HTTP. - … - object: Starts an MCP server as a local process. - … - `request_metadata` object, required: Metadata included with requests to this MCP server. - `allowed_tools` string[], nullable, required: The MCP tools the agent may call, or null when all server tools are allowed. - `required` boolean, required: Whether this MCP server must initialize before the first turn. - `connection_origin` 'service' | 'environment', required: Where outbound MCP HTTP connections originate. - object: Web search. - `type` 'web_search', required: The type of the object. Always `web_search`. - `mode` 'disabled' | 'cached' | 'live', required: The source used for web search results. - `context_size` 'low' | 'medium' | 'high', required: The amount of web search context made available to the model. - `allowed_domains` string[], nullable, required: Allowed search domains, or `null` when the search is unrestricted. - `location` WebSearchLocationResource, required: Approximate user location used to localize web search results. - `country` string, nullable, required: The two-letter ISO country code, such as `US`. - `region` string, nullable, required: The region or state name. - `city` string, nullable, required: The city name. - `timezone` string, nullable, required: The IANA timezone, such as `America/Los_Angeles`. - object: Browser use in an OpenAI-hosted session. - `type` 'computer_use', required: The type of the object. Always `computer_use`. - `include_screenshots` boolean, required: Whether computer tool outputs include screenshots. - object: Lets the agent manage its own scheduled wakeups. - `type` 'automations', required: The type of the object. Always `automations`. - `multi_agent` MultiAgentConfigResource, required: The resolved configuration for creating and coordinating subagents. - `enabled` boolean, required: Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents` integer, nullable, required: Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `compaction` CompactionResource: The effective settings for compacting the agent's context. - `async` boolean, required: Whether context is compacted in the background. Defaults to true. - `experimental` ExperimentalConfigResource: The effective experimental settings for an agent. - `time_awareness` boolean, required: Whether the model receives periodic current-time reminders. - `first_id` string, nullable, required: The ID of the first resource in `data`, or `null` if the page is empty. - `last_id` string, nullable, required: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `has_more` boolean, required: Whether there are more resources to retrieve after this page. ## Other responses - `400`: The request was invalid. - `401`: Authentication or project context was missing. - `403`: The API key lacks the required permission. - `404`: The requested session or event was not found. - `409`: The request conflicted with the current session state. - `500`: An internal error occurred. - `503`: The service is temporarily unavailable. ## Changes - **2026-10-29** `0a26f104d35f`: 1 info - added the optional property `data/items/experimental` to the response with the `200` status - **2026-10-28** `81bec64c97ee`: 1 info - added the optional property `data/items/compaction` to the response with the `200` status - **2026-10-23** `edf54d38a1a0`: 1 breaking, 1 info - added `#/components/schemas/PersistedAgentToolResourceAutomations` to the `data/items/tools/items/` response property `oneOf` list for the response status `200` - added `automations` discriminator mapping keys to the `data/items/tools/items/` response property for the response status `200` - **2026-10-08** `051b70dab8dd`: 1 breaking, 1 warning - for the `query` request parameter `limit`, default value `20` was added - for the `query` request parameter `limit`, the max was set to `100.00` - **2026-10-05** `7f654af7f94f`: 1 info - endpoint added [Operation history](https://skmtc.dev/omnistack-sh/apis/openai-api/changes/agents/get.md) --- [API](https://skmtc.dev/omnistack-sh/apis/openai-api.md) - [All operations](https://skmtc.dev/omnistack-sh/apis/openai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnistack-sh/apis/openai-api/revisions/0a26f104d35f?raw)