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

# ファイル一覧

> 現在のアカウント配下のファイル一覧をページネーションとフィルタ付きで取得します。

`GET /api/v1/cloud/files`

現在のアカウント配下のファイルを取得します。

## ヘッダー

| ヘッダー          | 必須 | 説明                  |
| ------------- | -- | ------------------- |
| Authorization | はい | `Bearer $QODER_PAT` |

## クエリパラメータ

| パラメータ       | 型       | 必須  | 説明                                                                             |
| ----------- | ------- | --- | ------------------------------------------------------------------------------ |
| `limit`     | integer | いいえ | 1 ページあたりの最大件数。デフォルト 20、範囲は 1〜100。100 を超える値は `400 invalid_request_error` を返します。 |
| `page`      | string  | いいえ | Claude スタイルの前方カーソル。`after_id` と同等。`before_id` および `after_id` と排他               |
| `after_id`  | string  | いいえ | カーソルページネーション：この ID 以降のファイルを返す。`page` および `before_id` と排他                       |
| `before_id` | string  | いいえ | カーソルページネーション：この ID 以前のファイルを返す。`page` および `after_id` と排他                        |
| `name`      | string  | いいえ | ファイル名の前方一致検索（大文字小文字を区別しない）                                                     |
| `scope_id`  | string  | いいえ | リソーススコープ（現在は Session ID）に関連付けられたファイルでフィルタ                                      |

## リクエスト例

```bash theme={null}
# 基本一覧
curl -X GET "https://api.qoder.com/api/v1/cloud/files" \
  -H "Authorization: Bearer $QODER_PAT"

# Session スコープでフィルタ + 件数制限
curl -X GET "https://api.qoder.com/api/v1/cloud/files?scope_id=sess_019e3bb8e6c47d18&limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

# カーソルページネーション
curl -X GET "https://api.qoder.com/api/v1/cloud/files?limit=10&page=file_019e3bb8e6c47d18" \
  -H "Authorization: Bearer $QODER_PAT"
```

## レスポンス例

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "file_019e3bb8e6c47d189212a79642136696",
      "type": "file",
      "filename": "report.txt",
      "mime_type": "text/plain",
      "size_bytes": 110,
      "downloadable": true,
      "scope": {
        "id": "sess_019e3bb8e6c47d18",
        "type": "session"
      },
      "metadata": {
        "project": "demo"
      },
      "created_at": "2026-05-18T15:33:53Z"
    }
  ],
  "next_page": null,
  "first_id": "file_019e3bb8e6c47d189212a79642136696",
  "has_more": false,
  "last_id": "file_019e3bb8e6c47d189212a79642136696"
}
```

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

| フィールド       | 型              | 説明                                                              |
| ----------- | -------------- | --------------------------------------------------------------- |
| `data`      | array          | [ファイルオブジェクト](/ja/cloud-agents/api/files/schemas#file-object)の配列 |
| `next_page` | string \| null | 次ページの前方カーソル。`has_more` が `true` の場合に `page` として使用               |
| `first_id`  | string \| null | 現在ページ先頭ファイルの ID。`data` が空の場合は `null`                            |
| `last_id`   | string \| null | 現在ページ末尾ファイルの ID。`data` が空の場合は `null`                            |
| `has_more`  | boolean        | さらにファイルがあるかどうか                                                  |

## ページネーション

結果は `created_at` と `id` でソートされます。ファイルをページングするには:

1. 初回リクエストで `limit` を設定し、最初のページを取得します。
2. `has_more` が `true` の場合、`page=<next_page>` で次のページを取得します。
3. `before_id=<first_id>` で前方ページネーションが可能です。

## エラーレスポンス

| HTTP | type                    | 説明                                                          |
| ---- | ----------------------- | ----------------------------------------------------------- |
| 400  | `invalid_request_error` | `limit` が無効、または `page`、`before_id`、`after_id` のうち複数が指定されている |
| 401  | `authentication_error`  | 認証トークンが欠落または無効                                              |

[エラー](/ja/cloud-agents/api/conventions/errors)で完全なエラーエンベロープを参照してください。

## 関連項目

<CardGroup cols={2}>
  <Card title="ファイルの添付とダウンロード" icon="paperclip" href="/ja/cloud-agents/files">
    Agent にコンテキストを提供するファイルをアップロードし、Agent が生成したファイルをダウンロードします。
  </Card>
</CardGroup>