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 parameterslimitinteger (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 |
Response fieldsobjectstringList 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 pageAgent fieldsidstringAgent 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.
Properties effort string / nullReasoning effort: none, minimal, low, medium, high, xhigh, maxsummary string / nullReasoning summary: concise, detailed, autoobject / nullText output configuration.
Properties format objectOutput format.
Properties type string / nullOutput format type, fixed as textstring / nullOutput verbosity, low, medium, highstring / nullStored custom instructionstools array / nullStored tool configuration; each branch returns only its own fields
Properties 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 configurationobject / nullSubagent configuration.
Properties enabled booleanWhether subagent tools are enabledmax_concurrent_subagents integer / nullMaximum number of concurrent subagents; no default is appliednull. | Response example |
Error codes
Business errors return an error object with type, code, message, and param. Common errors:
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Fix limit and order as described in the query parameters |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | not_found_error / not_found_error | Use the last_id returned by the previous page as after |
500 | server_error / server_error | Retry later. If it keeps failing, submit a ticket with x-request-id |