Skip to main content
GET
List agents
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

GET /api/v2/agents/list returns the agents you may read, oldest first. An agent is included only when your key or External App holds agents:read at the agent’s home org unit (or an org unit above it). An agent with no home org unit and every PERSONAL agent are never returned. limit is the number of agents a page returns; it defaults to 50, and a value above 100 is 400 too_big. Agents you may not read, and agents the filters leave out, are skipped and never counted. Pass meta.nextCursor back as cursor while meta.hasMore is true. A page holds fewer than limit agents, or none, for one of two reasons: no further agent matches, and meta.hasMore is false; or the page examined its limit of 200 agents and stopped, and meta.hasMore is true. meta.hasMore is false only when no further agent matches. Agents come in creation order, oldest first; there is no other sort.

Search and filters

The filters match exactly what the Console’s agents page matches, after visibility:
  • status: one of active, inactive, archived, draft, deprecated.
  • search: 1 to 200 characters, a case-insensitive substring of the agent’s agentId, name, description or purpose.
  • executionModel: repeatable; native.
  • tier: repeatable; system, worker or personal, the governance tier as the Console shows it. PERSONAL agents are never listed under any filter.
  • modelId: once, 1-128 characters; only agents whose default model is this catalog model, by its full id (anthropic/claude-opus-4) or a legacy bare name (claude-opus-4). A Gloo-proxied id (gloo-...) is its own model.
A limit that is not a positive integer, an empty or unreadable cursor, a repeated limit, cursor, search or modelId, an empty or over-long modelId, an empty or over-long search, or an unknown status, executionModel or tier is 400 bad_request. Each item is an Agent: exactly the fifteen documented fields, with null for unset optional values.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

limit
integer
default:50

Agents to return on this page, after visibility and filters, 1 to 100; a larger value is 400 too_big.

Required range: 1 <= x <= 100
cursor
string

The opaque meta.nextCursor from the previous page.

Minimum string length: 1
status
enum<string>
Available options:
active,
inactive,
archived,
draft,
deprecated

A case-insensitive substring of the agent's slug, name, description or purpose.

Required string length: 1 - 200
executionModel
enum<string>[]

Only agents with one of these execution models. Repeatable.

Available options:
native
tier
enum<string>[]

Only agents in one of these governance tiers, as the Console shows them. Repeatable. PERSONAL agents are never listed.

Available options:
system,
worker,
personal
modelId
string

Only agents whose default model is this catalog model, by full id or the legacy bare name.

Required string length: 1 - 128

Response

Agent list

data
object[]
required
meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.