Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

List agents

client.beta.agents.list(query?, options?): CursorPage<Agent { id, created_at, instructions, 12 more } >
GET
/agents

Lists reusable agents in the current project. See agent configuration.

Parameters
query: AgentListParams { after, limit, order }
after?: string

Return resources after this resource ID in the selected order.

minLength0
maxLength1048576
limit?: number

The maximum number of resources to return, between 1 and 100. Defaults to 20.

formatint64
minimum1
maximum100
order?: "asc" | "desc"

The order in which resources are returned. Defaults to desc.

Returns
Agent { id, created_at, instructions, 12 more }

A reusable agent scoped to the caller’s project.

id: string

The ID of the reusable agent.

minLength0
created_at: number

The Unix timestamp, in seconds, when the agent was created.

formatint64
instructions: string | null

Custom instructions appended to the agent’s default base instructions.

minLength0
metadata: Record<string, string>

Custom string key-value pairs attached to the agent.

model: string

The requested model name used for inference.

minLength0
multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

name: string | null

A human-readable name for the agent, or null if it is unnamed.

minLength0
object: "agent"

The object type. Always agent.

reasoning: AgentReasoning { effort, summary }

The resolved reasoning configuration, including the model default for an omitted effort.

service_tier: "auto" | "default" | "flex" | 3 more

The resolved service-tier policy used for model requests.

text: AgentText { format, verbosity }

The resolved configuration for text generated by the agent.

tools: Array<PersistedAgentTool>

Tools available to the agent.

minItems0
maxItems2000
updated_at: number

The Unix timestamp, in seconds, when the agent was last updated.

formatint64
compaction?: Compaction { async }

The effective context compaction settings.

experimental?: Experimental { time_awareness }

The effective experimental settings for the agent.

List agents

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const agent of client.beta.agents.list()) {
  console.log(agent.id);
}
200 — Example
{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "instructions": "instructions",
      "metadata": {
        "foo": "string"
      },
      "model": "model",
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 1
      },
      "name": "name",
      "object": "agent",
      "reasoning": {
        "effort": "none",
        "summary": "concise"
      },
      "service_tier": "auto",
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "low"
      },
      "tools": [
        {
          "defer_loading": true,
          "description": "description",
          "name": "name",
          "parameters": {
            "foo": "bar"
          },
          "type": "function",
          "async": true
        }
      ],
      "updated_at": 0,
      "compaction": {
        "async": true
      },
      "experimental": {
        "time_awareness": true
      }
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}
Returns Examples
200 — Example
{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "instructions": "instructions",
      "metadata": {
        "foo": "string"
      },
      "model": "model",
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 1
      },
      "name": "name",
      "object": "agent",
      "reasoning": {
        "effort": "none",
        "summary": "concise"
      },
      "service_tier": "auto",
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "low"
      },
      "tools": [
        {
          "defer_loading": true,
          "description": "description",
          "name": "name",
          "parameters": {
            "foo": "bar"
          },
          "type": "function",
          "async": true
        }
      ],
      "updated_at": 0,
      "compaction": {
        "async": true
      },
      "experimental": {
        "time_awareness": true
      }
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}