Agents
List agents
Returns the agents the caller may read — an agent is listed only when the caller holds agents:read at the agent’s home org unit, and PERSONAL agents are never listed. Requires permission agents:read.
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 ofactive,inactive,archived,draft,deprecated.search: 1 to 200 characters, a case-insensitive substring of the agent’sagentId, name, description or purpose.executionModel: repeatable;native.tier: repeatable;system,workerorpersonal, 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.
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
Query Parameters
Response
Agent list

