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

# Agent バージョン一覧

> 指定された Agent のバージョン履歴を取得します。

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

指定された Agent のバージョン履歴を取得します。バージョン番号の降順（最新バージョンが先頭）で返されます。

## リクエストヘッダー

| ヘッダー            | 必須 | 説明             |
| --------------- | -- | -------------- |
| `Authorization` | はい | `Bearer <PAT>` |

## パスパラメーター

| パラメーター     | 型      | 必須 | 説明           |
| ---------- | ------ | -- | ------------ |
| `agent_id` | string | はい | Agent の一意識別子 |

## クエリパラメーター

| パラメーター  | 型       | 必須  | デフォルト | 説明                                                                  |
| ------- | ------- | --- | ----- | ------------------------------------------------------------------- |
| `limit` | integer | いいえ | 20    | 1ページあたりの返却件数。範囲は 1〜100。100 を超える値は `400 invalid_request_error` を返します |
| `page`  | string  | いいえ | -     | 前回のレスポンスの `next_page` で返されたカーソル                                     |

ページネーションの詳細については[ページネーション](/ja/cloud-agents/api/conventions/pagination)を参照してください。

## リクエスト例

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

## レスポンス例

**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
}
```

## レスポンスフィールド

| フィールド       | 型                                                                                        | 説明                                                           |
| ----------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `data`      | [Agent version snapshot](/ja/cloud-agents/api/agents/schemas#agent-version-snapshot) の配列 | 現在のページのバージョンスナップショット                                         |
| `first_id`  | string                                                                                   | 現在のページの最初のレコードのバージョン識別子                                      |
| `last_id`   | string                                                                                   | 現在のページの最後のレコードのバージョン識別子                                      |
| `has_more`  | boolean                                                                                  | さらにバージョンレコードが存在するかどうか                                        |
| `next_page` | string\|null                                                                             | 次ページのカーソル。`has_more` が true の場合は `last_id` と同じ値、それ以外は `null` |

## バージョン履歴について

* Agent の作成時に version 1 が保存されます
* Agent を更新するたびに次のバージョンが保存されます
* 各バージョンにはその時点の Agent の完全なスナップショットが保存されます
* 変更履歴の監査やロールバック時の参照に利用できます

## エラー

| HTTP | type                    | 発生条件                       |
| ---- | ----------------------- | -------------------------- |
| 400  | `invalid_request_error` | `limit` が正の整数ではない          |
| 400  | `invalid_request_error` | ページネーションカーソルが不正            |
| 400  | `invalid_request_error` | `page` が正の整数のバージョンカーソルではない |
| 401  | `authentication_error`  | PAT が無効または有効期限切れ           |
| 403  | `permission_error`      | この Agent へのアクセス権限がない       |
| 404  | `not_found_error`       | 指定された ID の Agent が存在しない    |

エラーエンベロープの詳細については[エラー](/ja/cloud-agents/api/conventions/errors)を参照してください。

## 注意事項

* このエンドポイントでは、`first_id` と `last_id` はバージョン番号の文字列表現です（例: `"1"`、`"2"`）
* デフォルトではバージョン番号の降順で、最新バージョンが先頭に表示されます
* Agent のアーカイブでは新しいバージョンスナップショットは作成されません
* `POST /api/v1/cloud/agents/{agent_id}` の OCC メカニズムと組み合わせて、設定変更履歴を追跡できます

## 関連

<CardGroup cols={2}>
  <Card title="Agent の定義" icon="user-gear" href="/ja/cloud-agents/define-agent">
    再利用可能でバージョン管理された Agent 構成を作成する。
  </Card>
</CardGroup>