---
title: "List agent versions"
method: GET
path: "/agents/{agent_id}/versions"
tags: ["Agents"]
---

# List agent versions

`GET /agents/{agent_id}/versions`

## Request

- Base URL: `https://api.coval.dev/v1`
- URL: `https://api.coval.dev/v1/agents/{agent_id}/versions`
- Auth: API key in header `x-api-key`

List the version history for an agent, newest first. The newest entry is the agent's current live config; earlier entries are prior states displaced by later saves. Only behavioral config is versioned; identity and cosmetic fields are not.

## Path parameters

- `agent_id` string, required

## Response `200`

Agent version history retrieved successfully

- ListAgentVersionsResponse: Response for GET /v1/agents/{agent_id}/versions (newest first)
  - `versions` AgentVersionResource[], required
    - `name` string, required: Resource name
    - `ulid` string, required: Version identifier (26-char ULID)
    - `version_number` integer, required: Per-agent monotonic version number, 1-based
    - `change_type` 'save' | 'revert', required: How this version came about. A revert is a save whose new state mirrors an older version.
    - `label` string, nullable: Optional user-supplied tag
    - `model_type` string, required: Agent model type at snapshot time
    - `phone_number` string, nullable
    - `endpoint` string, nullable
    - `metadata` object, nullable
    - `attributes` object, nullable
    - `workflows` object: Verbatim workflow-config snapshot
    - `prompt` string, nullable
    - `language` string, nullable
    - `test_set_ids` string[], nullable
    - `metric_ids` string[], nullable
    - `created_by` string, required: Who created this version (user ULID)
    - `create_time` string, date-time, nullable: When this version became current

## Other responses

- `401`: Authentication failed
- `404`: Agent not found, inactive, or belongs to different organization
- `500`: Internal server error

---

[API](https://skmtc.dev/coval/apis/coval-agents-api.md) - [All operations](https://skmtc.dev/coval/apis/coval-agents-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coval/apis/coval-agents-api/revisions/ba0291fe3911?raw)