> ## 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 agent versions

> List the version history of an Agent in descending order by version number.

`GET /api/v1/cloud/agents/{agent_id}/versions`

Returns the version history of the specified Agent, sorted by version number in descending order (newest first).

## Headers

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

## Path parameters

| Parameter  | Type   | Required | Description             |
| ---------- | ------ | -------- | ----------------------- |
| `agent_id` | string | Yes      | Agent unique identifier |

## 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`                           |

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/agent_019eXXXX.../versions" \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "type": "agent",
      "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "name": "doc-test-agent-updated",
      "description": "Used for API documentation testing",
      "model": "ultimate",
      "system": "You are an updated documentation testing assistant.",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "multiagent": null,
      "version": 2,
      "archived_at": null,
      "created_at": "2026-05-18T15:26:39.61669Z",
      "updated_at": "2026-05-18T15:27:07.967138Z"
    },
    {
      "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"
    }
  ],
  "first_id": "2",
  "last_id": "1",
  "has_more": false,
  "next_page": null
}
```

## Response fields

| Field       | Type                                                                                       | Description                                                                          |
| ----------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `data`      | array of [Agent version snapshot](/cloud-agents/api/agents/schemas#agent-version-snapshot) | Version snapshots on the current page                                                |
| `first_id`  | string                                                                                     | Version identifier of the first record on this page                                  |
| `last_id`   | string                                                                                     | Version identifier of the last record on this page                                   |
| `has_more`  | boolean                                                                                    | Whether more versions remain                                                         |
| `next_page` | string\|null                                                                               | Cursor for the next page. Equals `last_id` when `has_more` is true, otherwise `null` |

## Version history

* Creating an Agent stores version 1.
* Every successful update stores the next version.
* Each version stores the full Agent snapshot at that point in time.
* Useful for auditing changes or reference during rollback.

## 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` | `page` is not a positive integer version cursor |
| 401  | `authentication_error`  | PAT invalid or expired                          |
| 403  | `permission_error`      | Not authorized for this Agent                   |
| 404  | `not_found_error`       | Agent with the given ID does not exist          |

See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope.

## Notes

* For this endpoint, `first_id` and `last_id` are the version numbers as strings (such as `"1"`, `"2"`).
* Versions are sorted in descending order by default (latest first).
* Archiving an Agent does not create a new version snapshot.
* Combine with the OCC mechanism on `POST /api/v1/cloud/agents/{agent_id}` to track configuration changes.

## Related

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