List agents
List the organisation's agents, newest first by default.
List the organisation's agents, newest first by default.
A row here and the agent read on its own carry the same keys, so you can
write one decoder for both. A row is thinner wherever the listing does not
fetch something: prompts comes back empty; knowledge_base and
calling_guard are null; integrations has no mcp;
follow_up_config is empty; and variables names only the greeting's
placeholders, because the prompts are not read. Everything else — the
greeting, the labels, the seven configuration sections — is the same object.
Read an agent on its own before acting on any of those fields.
Two other behaviours worth knowing:
- A page can come back with fewer rows than you asked for — this is normal.
Creating an agent also creates a web-call companion that shares its prompt and is
not listed here, so
page_size=20commonly returns about 10 agents, andpage_size=1can return none at all. A short page does NOT mean the end of the list. - Use
has_more, nevertotal, to decide whether to keep going.has_moreis authoritative.totalis an estimate that shifts withpage_sizeand is not a number to divide. Iterate untilhas_moreis false and collect what arrives.
Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/agentsAuthorization
AuthorizationRequiredBearer <token>
Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.
In: header
Query Parameters
statusStatus
DRAFT | ACTIVE | INACTIVE | ARCHIVED. ARCHIVED agents are excluded unless this filter names them explicitly.
categoryCategory
conversation | extraction | summarization | custom. Any other value is refused with 422 — an agent whose category is free text cannot be filtered for.
searchSearch
Case-insensitive substring match on the agent's name, its summary or its labels.
sort_bySort By
created_at | updated_at | name | status
"created_at"sort_orderSort Order
asc | desc
"desc"organization_idOrganization Id
Must match the organisation the API key belongs to.
pagePage
1-indexed page number (max 10000 — narrow the window instead)
1Minimum: 1Maximum: 10000page_sizePage Size
Items per page (max 100)
20Minimum: 1Maximum: 100Response Body
200
A page of agents, newest first by default. Each row carries the same keys as GET /v2/agents/{agent_id}.
dataRequiredData
This page of agents, newest first by default.
paginationRequiredPagination
Where this page sits in the result set.
400
1000 — malformed or contradictory input. 1002 — a required parameter is missing.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
403
1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
422
1001 — the body or query failed validation; the message names the first offending field.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
503
1501 — a service this endpoint depends on is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
504
1502 — a service this endpoint depends on did not answer in time.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
A page of agents, newest first by default. Each row carries the same keys as GET /v2/agents/{agent_id}.