List Agent Versions API: GET /agents/{agent_id}/versions-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Lists all historical versions of an agent with pagination. When a session is created, it locks to the current version; the session detail also embeds a full agent snapshot for that version.

Prerequisites

Endpoint and authentication configured. For details, see Overview and authentication.

Endpoint

GET /agents/{agent_id}/versions

Query parameters

Parameter	Required	Type	Description
`limit`	No	int	Number of items per page. Default: 20, maximum: 100
`page`	No	string	Pagination cursor. Omit for the first request; pass the `next_page` value from the previous response to fetch the next page

Request example

Bash

curl "$AGENTSTUDIO_URL/agents/agent_xxx/versions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Python

for version in client.agents.list_versions("agent_xxx", limit=10):
    print(version.version, version.created_at)

Java

CursorPage<AgentVersion> versions = client.agents().listVersions(
    "agent_xxx", AgentListParam.builder().limit(10).build());

Response

The response contains data (an array of Agent objects, each representing a historical version snapshot, sorted by version number in descending order), next_page (cursor for the next page; null when no more data), and request_id. Each Agent object has the same fields as the Create Agent response. Field descriptions:

Agent object fields

Field	Type	Description
`id`	string	Agent ID (same across all versions)
`type`	string	Always `agent`
`version`	int	Version number; returned in descending order
`name` / `description` / `system`	string	Name, description, and system prompt in this version snapshot
`model` / `tools` / `mcp_servers` / `skills` / `metadata`	object / array	Model, toolkits, MCP references, skills, and business metadata in this version snapshot
`archived_at`	string \| null	Archive timestamp; `null` if not archived
`created_at` / `updated_at`	string	Creation / update time of this version
`workspace_id`	string	Workspace ID