# 取得單一知識版本的檔案列表

此 API 用於查詢指定 Fileset 中所包含的所有檔案，以及每個檔案在此 Fileset 內的 commit 狀態（Fileset File State）與實際採用的解析品質（`used_quality`）。

```bash
curl -X 'GET' \
  'http://127.0.0.1:8000/v1/filesets/{fileset_id}/files?limit=20&order=desc' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY"
```

#### Request Headers

| Key | Value |
| --- | --- |
| Request Method | GET |
| accept | application/json |
| Authorization | `Bearer $PRIVAI_API_KEY` |

#### Path Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| fileset_id | string | uuid | true |

#### Query Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| limit | int | 1 - 10000，預設為 10000 | false |
| order | string | 依檔案的 `created_at` 排序，`asc` 或 `desc`，預設為 `desc` | false |
| after | string | uuid，分頁游標（檔案 ID），取得此檔案之後的資料。不可與 `before` 同時使用 | false |
| before | string | uuid，分頁游標（檔案 ID），取得此檔案之前的資料。不可與 `after` 同時使用 | false |
| files_state | string | 依檔案在此 Fileset 內的狀態篩選，可用值：`draft`、`queued`、`processing`、`completed`、`failed` | false |

:::warning[⚠️]

篩選參數名稱為 `files_state`（複數 files）。

:::

#### Response Body

```json
{
  "object": "list",
  "first_id": "18b8b0f0-83c1-41a0-ba58-40774c8dfb99",
  "last_id": "18b8b0f0-83c1-41a0-ba58-40774c8dfb99",
  "has_more": false,
  "data": [
    {
      "object": "fileset.file",
      "id": "18b8b0f0-83c1-41a0-ba58-40774c8dfb99",
      "filename": "2024清明.pdf",
      "filetype": "application/pdf",
      "bytes": 200273,
      "metadata": {
        "parsed_results": {
          "HQ": {
            "parsing_state": "completed",
            "character_count": 2639,
            "page_count": 5,
            "failed_page_numbers": []
          },
          "LQ": {
            "parsing_state": "draft"
          }
        },
        "fail_detail": []
      },
      "state": "completed",
      "used_quality": "HQ",
      "purpose": "user_data",
      "created_at": "2025-12-02T03:15:01.975741Z",
      "expires_at": null
    }
  ]
}
```

**Field Explanation**

| Field | Detail |
| --- | --- |
| object | 固定為 `list` |
| data[] | Fileset File 物件列表，欄位見下表 |
| first_id | 本頁第一個檔案的 ID，無資料時為 null |
| last_id | 本頁最後一個檔案的 ID，無資料時為 null |
| has_more | 此知識版本是否還有更多的檔案 |

**Fileset File 物件（data[]）**  
包含「[檔案物件](https://privstation-docs.apmic.ai/latest/privai-400/檔案物件.md)」的所有欄位，差異如下：

| Field | Detail |
| --- | --- |
| object | 固定為 `fileset.file` |
| state | 該檔案在此 Fileset 內的 commit 狀態（Fileset File State）：`draft`、`queued`、`processing`、`completed`、`failed` |
| used_quality | 此檔案在該 Fileset commit 時實際採用的解析品質，可能為 null、`HQ`、`LQ`、`STD` |

狀態定義詳見「File Parse State、Fileset File State 與 Fileset State 的差異」章節。

#### 常見錯誤代碼

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| FILESET_001 | 404 | 指定的 Fileset 不存在 |
| VAL_001 | 422 | 同時帶入 `after` 與 `before` |
| VAL_002 | 404 | `after`／`before` 指定的檔案 ID 不存在 |
| — | 422 | `files_state` 不是允許的值 |

身份驗證錯誤（`AUTH_001`～`AUTH_003`）詳見「錯誤代碼說明-身份驗證類」章節；知識版本相關錯誤碼完整說明請參考 [錯誤代碼說明-知識版本管理類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-知識版本管理類.md)。
