Skip to main content

List agents

List agents in the current workspace with pagination.

Endpoint

GET /agents Returns 200 and a list envelope. data is an array of Agent objects.

Query parameters

limit integer (optional)Number of items per page, default 20; recommended range 1..100order string (optional)Sort direction, asc or desc, default descafter string (optional)The last_id from the previous page; the cursor item is excludedbefore string (optional)The first_id from the previous page, for reverse pagination; cannot be used with after; the cursor must be a valid agent in the current workspacePassing both after and before returns 400. For the first page, omit after. For later pages, pass the last_id from the previous response. For reverse pagination, pass the first_id as before. has_more indicates whether the current scan direction has more results. The list is sorted lexicographically by agent ID, is not guaranteed to sort stably by created_at, and does not provide snapshot isolation under concurrent writes.

Request example

curl -sS "$BASE_URL/agents?limit=20&order=desc" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

Response fields

object stringList object type, fixed as listdata arrayAgent objects on this page; [] when emptyfirst_id string / nullID of the first item; null for an empty pagelast_id string / nullID of the last item; null for an empty pagehas_more booleanWhether the current scan direction has another page

Agent fields

id stringAgent ID. Treat it as an opaque stringobject stringAgent object type, fixed as agentcreated_at integerCreation time as a Unix timestamp in secondsupdated_at integerLast modification time as a Unix timestamp in seconds; not a version numbername string / nullDisplay namemetadata object / nullMetadata, stored string key-value pairsmodel stringStored model IDreasoning object / nullReasoning configuration. Either subfield can be null.
effort string / nullReasoning effort: none, minimal, low, medium, high, xhigh, maxsummary string / nullReasoning summary: concise, detailed, auto
text object / nullText output configuration.
format objectOutput format.
type string / nullOutput format type, fixed as text
verbosity string / nullOutput verbosity, low, medium, high
instructions string / nullStored custom instructionstools array / nullStored tool configuration; each branch returns only its own fields
function objectFunction tool configuration; returns name, description, and parametersmcp objectMCP tool configuration; returns server_label, transport, allowed_tools, required, and connection_origin; transport is http or stdioweb_search objectWeb search tool configuration; returns type and the saved configuration
multi_agent object / nullSubagent configuration.
enabled booleanWhether subagent tools are enabledmax_concurrent_subagents integer / nullMaximum number of concurrent subagents; no default is applied
Optional fields that were never set can be null.

Response example

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Error codes

Business errors return an error object with type, code, message, and param. Common errors:
HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorFix limit and order as described in the query parameters
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404not_found_error / not_found_errorUse the last_id returned by the previous page as after
500server_error / server_errorRetry later. If it keeps failing, submit a ticket with x-request-id