> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexrex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 匯出

> 執行非同步資料匯出並下載結果。

匯出功能讓你以 CSV、JSON 或兩者兼備的格式，提取機構活動資料的完整套件——
用於分析、報告或遷移。匯出為**非同步**執行：你建立一個任務，輪詢直到完成，
再下載簽名後的檔案。

## 流程

<Steps>
  <Step title="建立任務">
    使用 `exports:create` 範圍對 `POST /exports` 發送請求。回傳 `202 Accepted` 及狀態為
    `pending` 的任務。

    ```bash theme={null}
    curl -X POST https://api.nexrex.ai/api/v1/developer/v1/exports \
      -H "Authorization: Bearer nrx_prod_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "format": "both",
        "start_date": 1748736000000,
        "end_date": 1751328000000
      }'
    ```
  </Step>

  <Step title="輪詢等待完成">
    使用 `exports:read` 範圍對 `GET /exports/{export_id}` 發送請求。`status` 欄位會從
    `pending` → `running` → `completed`（或 `failed`）依序推進。每隔幾秒輪詢一次。
  </Step>

  <Step title="下載">
    狀態變為 `completed` 後，對 `GET /exports/{export_id}/download` 發送請求，
    回傳一個**短暫有效的簽名 URL** 及其到期秒數：

    ```json theme={null}
    {
      "success": true,
      "data": {
        "download_url": "https://storage.googleapis.com/…",
        "expires_in_seconds": 600
      }
    }
    ```

    請盡快取得 `download_url`——有效期約 10 分鐘。在匯出存在期間，你可以隨時請求新的 URL。
  </Step>
</Steps>

## 請求選項

| 欄位            | 預設值    | 說明                       |
| ------------- | ------ | ------------------------ |
| `format`      | `both` | `csv`、`json` 或 `both`    |
| `start_date`  | 所有時間   | 時間範圍起點，**epoch 毫秒（UTC）** |
| `end_date`    | 所有時間   | 時間範圍終點，**epoch 毫秒（UTC）** |
| `athlete_ids` | 所有運動員  | 限制為特定機構運動員；若省略則包含全部學員名單  |

## 任務生命週期與保留

* 狀態包含 `pending`、`running`、`completed`、`failed` 及 `deleted`。
* 已完成的匯出保留 **7 天**，到期後自動刪除。`expires_at` 欄位會告知到期時間。
  到期後請重新建立匯出。
* 一個金鑰只能看到**它在自身機構內建立**的匯出——在網頁主控台建立或由其他金鑰建立的匯出不可見。

## 無法納入的運動員會被略過，不會導致失敗

匯出不會因為某位運動員無法被納入而失敗。已離開機構（或因其他原因無法存取）的運動員
會被**略過並列入**任務的 `skipped_athletes` 陣列，每筆記錄包含 `uid` 和 `reason`，
並也記錄在匯出的清單中。其餘匯出內容正常完成。

## 運動員會收到通知

當匯出包含某位運動員的資料時，該運動員會收到一則應用程式內的**透明通知**，
告知其機構已匯出包含其活動的訓練資料，並引導他們前往機構的稽核記錄。
每次匯出也會連同建立它的金鑰一起寫入機構稽核記錄。
這是[資料可攜承諾](https://nexrex.ai/data-portability)的核心：資料可以移動，但絕不靜默移動。

<Note>
  請求頻率限制：`POST /exports` 在每個金鑰的標準限制之上，額外有**每小時 5 個請求**的上限。
  詳見[請求頻率限制](/zh-Hant/api-reference/rate-limits)。
</Note>