Skip to main content

List agents

List Agents under the current account with cursor pagination. GET /api/v1/cloud/agents Lists Agents under the current account. Archived Agents are excluded unless include_archived=true is provided.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT>

Query parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo20Items per page. Range 1-100; values above 100 return 400 invalid_request_error
pagestringNo-Cursor returned by the previous response's next_page
include_archivedbooleanNofalseSet to true to include archived Agents
created_at[gte]stringNo-Include Agents created at or after this RFC 3339 timestamp
created_at[lte]stringNo-Include Agents created at or before this RFC 3339 timestamp
See Pagination for cursor semantics.

Example request

curl -X GET "https://api.qoder.com.cn/api/v1/cloud/agents?limit=2" \
  -H "Authorization: Bearer $QODER_PAT"

Example response

HTTP 200 OK 
{
  "data": [
    {
      "type": "agent",
      "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "name": "doc-test-agent",
      "description": "",
      "model": "ultimate",
      "system": "You are a documentation testing assistant.",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "multiagent": null,
      "version": 1,
      "archived_at": null,
      "created_at": "2026-05-18T15:26:39.61669Z",
      "updated_at": "2026-05-18T15:26:39.61669Z"
    },
    {
      "type": "agent",
      "id": "agent_019eYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
      "name": "test-agent-e2e",
      "description": "Agent used for end-to-end testing",
      "model": "ultimate",
      "system": "You are a testing assistant.",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "multiagent": null,
      "version": 2,
      "archived_at": null,
      "created_at": "2026-05-18T03:04:33.952256Z",
      "updated_at": "2026-05-18T03:05:28.023697Z"
    }
  ],
  "first_id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "last_id": "agent_019eYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
  "has_more": true,
  "next_page": "agent_019eYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
}

Response fields

Field

Type

Description

data

array of Agent object

Agents on the current page

first_id

string

ID of the first record on this page

last_id

string

ID of the last record on this page

has_more

boolean

Whether more records remain

next_page

string|null

Cursor for the next page. Equals last_id when has_more is true, otherwise null

Pagination

Page forward (next page): 
curl "https://api.qoder.com.cn/api/v1/cloud/agents?limit=20&page=agent_019eYYYY..."

Errors

HTTPTypeTrigger
400invalid_request_errorlimit is not a positive integer
400invalid_request_errorInvalid pagination cursor
400invalid_request_errorcreated_at[gte] or created_at[lte] is not RFC 3339
401authentication_errorPAT invalid or expired
403permission_errorNot authorized for this operation
See Errors for the full error envelope.

Notes

  • Records are returned in descending ID order by default.
  • Archived Agents do not appear in the default listing. Pass include_archived=true to include them.
  • Pagination is cursor-based; offset-based pagination is not supported.