> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

| Header          | Required | Description    |
| --------------- | -------- | -------------- |
| `Authorization` | Yes      | `Bearer <PAT>` |

## Query parameters

| Parameter          | Type    | Required | Default | Description                                                                      |
| ------------------ | ------- | -------- | ------- | -------------------------------------------------------------------------------- |
| `limit`            | integer | No       | 20      | Items per page. Range 1-100; values above 100 return `400 invalid_request_error` |
| `page`             | string  | No       | -       | Cursor returned by the previous response's `next_page`                           |
| `include_archived` | boolean | No       | `false` | Set to `true` to include archived Agents                                         |
| `created_at[gte]`  | string  | No       | -       | Include Agents created at or after this RFC 3339 timestamp                       |
| `created_at[lte]`  | string  | No       | -       | Include Agents created at or before this RFC 3339 timestamp                      |

See [Pagination](/cloud-agents/api/conventions/pagination) for cursor semantics.

## Example request

```bash theme={null}
curl -X GET "https://api.qoder.com/api/v1/cloud/agents?limit=2" \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "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](/cloud-agents/api/agents/schemas#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):

```bash theme={null}
curl "https://api.qoder.com/api/v1/cloud/agents?limit=20&page=agent_019eYYYY..."
```

## Errors

| HTTP | Type                    | Trigger                                                |
| ---- | ----------------------- | ------------------------------------------------------ |
| 400  | `invalid_request_error` | `limit` is not a positive integer                      |
| 400  | `invalid_request_error` | Invalid pagination cursor                              |
| 400  | `invalid_request_error` | `created_at[gte]` or `created_at[lte]` is not RFC 3339 |
| 401  | `authentication_error`  | PAT invalid or expired                                 |
| 403  | `permission_error`      | Not authorized for this operation                      |

See [Errors](/cloud-agents/api/conventions/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.

## Related

<CardGroup cols={2}>
  <Card title="Agent setup" icon="user-gear" href="/cloud-agents/define-agent">
    Create a reusable, versioned agent configuration.
  </Card>
</CardGroup>