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

# 用量日誌查詢 API

> 以帳戶級系統存取令牌低頻讀取 NexusAPI 的用量明細。

`api.nexusapi.link` 是與模型轉發、控制台分離的**唯讀用量查詢閘道**。它只能讀取憑證所屬帳戶的消費日誌，不能呼叫模型、充值或執行管理操作。

## 基本資訊

| 項目       | 值                           |
| -------- | --------------------------- |
| Base URL | `https://api.nexusapi.link` |
| 端點       | `GET /v1/logs`              |
| 建議憑證     | 系統存取令牌                      |
| 排序       | 最新記錄在前                      |

在控制台 **個人設定 → 生成令牌** 建立系統存取令牌，並只透過下列 Header 傳送：

```http theme={"system"}
Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN
```

<Warning>
  模型呼叫使用令牌管理中建立的 API Key；用量查詢應使用系統存取令牌。後者不能呼叫模型，但能讀取帳戶級明細，同樣必須視為敏感憑證。
</Warning>

## 查詢參數

| 參數           | 說明                             |
| ------------ | ------------------------------ |
| `start_time` | Unix 秒或 RFC3339 起始時間。          |
| `end_time`   | Unix 秒或 RFC3339 結束時間，不能早於起始時間。 |
| `page`       | 頁碼，從 `1` 開始。                   |
| `page_size`  | 每頁筆數，預設 `10`，最大 `50`。          |

日常對帳建議以日或週為區間。服務端目前不支援按模型、群組或令牌名篩選；請在取得的帳戶資料中自行篩選。`page × page_size` 不得超過 `100000`。

## 範例

```bash theme={"system"}
curl -G 'https://api.nexusapi.link/v1/logs' \
  -H 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --data-urlencode 'start_time=2026-06-01T00:00:00Z' \
  --data-urlencode 'end_time=2026-06-02T00:00:00Z' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=50'
```

當 `data` 為空或少於 `page_size`，即已到最後一頁。此端點不回傳總筆數。

## 常用回應欄位

| 欄位                                  | 說明                              |
| ----------------------------------- | ------------------------------- |
| `time`                              | UTC／RFC3339 請求時間。               |
| `token_name`                        | 本次使用的 API Key 名稱。               |
| `group`／`model`                     | 實際記錄的群組與模型。                     |
| `prompt_tokens`／`completion_tokens` | 輸入與輸出 Token。                    |
| `cost`                              | 記錄的美元消費。                        |
| `request_id`                        | 對帳用的請求識別碼。                      |
| `request_path`                      | 實際路徑，例如 `/v1/chat/completions`。 |

429 或 503 時，遵循 `Retry-After` 後再試；請用排程增量拉取，不要進行秒級輪詢。疑似帳務問題時，同時保留查詢時間範圍和模型請求的 Request ID。