---
title: "List agents"
method: GET
path: "/agents"
tags: ["Agents"]
---

# List agents

`GET /agents`

Lists reusable agents in the current project. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).

## Query parameters

- `limit` integer, nullable
- `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', 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`.
    - `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.
  - `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.
- `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-09-10** `f2dae1a9aced` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openai/apis/openapi/changes/agents/get.md)

---

[API](https://skmtc.dev/openai/apis/openapi.md) · [All operations](https://skmtc.dev/openai/apis/openapi/llms.txt) · [OpenAPI document](https://skmtc.dev/openai/apis/openapi/revisions/26bd6202a0ad?raw)