> ## 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 一覧を取得します。デフォルトではアーカイブ済み Agent は含まれません。`include_archived=true` を指定するとアーカイブ済み Agent も含まれます。

## リクエストヘッダー

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

## クエリパラメーター

| パラメーター             | 型       | 必須  | デフォルト   | 説明                                                                  |
| ------------------ | ------- | --- | ------- | ------------------------------------------------------------------- |
| `limit`            | integer | いいえ | 20      | 1ページあたりの取得件数。範囲は 1〜100。100 を超える値は `400 invalid_request_error` を返します |
| `page`             | string  | いいえ | -       | 前回のレスポンスの `next_page` で返されたカーソル                                     |
| `include_archived` | boolean | いいえ | `false` | `true` に設定するとアーカイブ済み Agent を含めます                                    |
| `created_at[gte]`  | string  | いいえ | -       | この RFC 3339 タイムスタンプ以降に作成された Agent のみを返します                           |
| `created_at[lte]`  | string  | いいえ | -       | この RFC 3339 タイムスタンプ以前に作成された Agent のみを返します                           |

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

## リクエスト例

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

## レスポンス例

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

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

| フィールド       | 型                                                                   | 説明                                                           |
| ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------ |
| `data`      | [Agent オブジェクト](/ja/cloud-agents/api/agents/schemas#agent-object)の配列 | 現在のページの Agent                                                |
| `first_id`  | string                                                              | 現在のページの最初のレコードの ID                                           |
| `last_id`   | string                                                              | 現在のページの最後のレコードの ID                                           |
| `has_more`  | boolean                                                             | さらにデータが存在するかどうか                                              |
| `next_page` | string\|null                                                        | 次ページのカーソル。`has_more` が true の場合は `last_id` と同じ値、それ以外は `null` |

## ページネーション

次のページを取得する：

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

## エラー

| HTTP | type                    | 発生条件                                                     |
| ---- | ----------------------- | -------------------------------------------------------- |
| 400  | `invalid_request_error` | `limit` が正の整数でない                                         |
| 400  | `invalid_request_error` | ページネーションカーソルが不正                                          |
| 400  | `invalid_request_error` | `created_at[gte]` または `created_at[lte]` が RFC 3339 形式でない |
| 401  | `authentication_error`  | PAT が無効または期限切れ                                           |
| 403  | `permission_error`      | この操作を実行する権限がない                                           |

エラーレスポンスの完全な形式については[エラー](/ja/cloud-agents/api/conventions/errors)を参照してください。

## 注意事項

* デフォルトでは ID の降順で返されます。
* アーカイブ済み Agent はデフォルトの一覧には表示されません。`include_archived=true` を指定するとアーカイブ済み Agent を含めることができます。
* カーソルベースのページネーション（cursor-based pagination）を使用しており、オフセット方式には対応していません。

## 関連

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