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

# 用戶日誌與用量統計

> 透過 API 取得使用記錄（Usage Logs）、儀表板資訊與帳單資訊，由 /api/log/self 與 /api/log/self/stat 兩個介面提供。

## 簡介

MixRoute 控制台提供兩個介面，用於查詢目前帳號下的用量與計費資訊，涵蓋以下需求：

* 查看 Usage Logs（使用記錄）
* 查看 Dashboard 資訊（模型分析、請求次數、Token 統計等）
* 查看帳單資訊（某個 API Key 使用了哪些模型、對應輸入/輸出 Token、各模型用量佔比等）
* 依模型維度了解實際消費情況

## 認證

所有請求需要在請求標頭攜帶兩個欄位：

| 請求標頭            | 說明                                    |
| --------------- | ------------------------------------- |
| `Authorization` | `Bearer <you-api-key>`，你的系統存取 API Key |
| `New-Api-User`  | `<you-user-id>`，目前帳號的使用者 ID           |

## 取得使用者日誌 GET `/api/log/self`

回傳目前帳號的使用日誌，日誌條目依時間倒序排列，可透過分頁參數控制輸出內容。

### 請求參數

<ParamField query="p" type="integer">
  頁碼，從 1 開始。
</ParamField>

<ParamField query="page_size" type="integer">
  每頁回傳的日誌條目數。
</ParamField>

例如 `/api/log/self?p=1&page_size=20` 表示取得第一頁、每頁 20 條日誌。

### 請求範例

```bash cURL theme={null}
curl --request GET \
  --url 'https://console.mixroute.ai/api/log/self?p=1&page_size=20' \
  --header 'authorization: Bearer <you-api-key>' \
  --header 'new-api-user: <you-user-id>'
```

### 回應範例

```json Response theme={null}
{
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 2821,
    "items": [
      {
        "id": 1,
        "user_id": 81,
        "created_at": 1787215542,
        "type": 2,
        "content": "",
        "username": "<you-user-name>",
        "token_name": "<your-token-name>",
        "model_name": "deepseek-v4-flash-0731",
        "quota": 768,
        "prompt_tokens": 23144,
        "completion_tokens": 2948,
        "use_time": 38,
        "is_stream": true,
        "channel": 239,
        "channel_name": "",
        "token_id": 202,
        "group": "default",
        "ip": "",
        "request_id": "202608200845041208627278268d9d63W55TNWu",
        "other": "{\"billing_source\":\"wallet\",\"cache_ratio\":0.02,\"cache_tokens\":18432,\"completion_ratio\":2,\"frt\":1245,\"group_ratio\":1,\"model_price\":-1,\"model_ratio\":0.07,\"reasoning_effort\":\"max\",\"request_conversion\":[\"OpenAI Responses\"],\"request_path\":\"/v1/responses\",\"user_group_ratio\":-1}"
      }
    ]
  },
  "message": "",
  "success": true
}
```

### 日誌欄位說明

| 欄位                               | 型別      | 說明                                              |
| -------------------------------- | ------- | ----------------------------------------------- |
| `data.page`                      | integer | 目前頁碼                                            |
| `data.page_size`                 | integer | 每頁條目數                                           |
| `data.total`                     | integer | 日誌總條數                                           |
| `data.items[]`                   | array   | 日誌條目清單                                          |
| `data.items[].id`                | integer | 日誌 ID                                           |
| `data.items[].user_id`           | integer | 使用者 ID                                          |
| `data.items[].created_at`        | integer | 建立時間（Unix 時間戳記，秒）                               |
| `data.items[].type`              | integer | 記錄類型                                            |
| `data.items[].content`           | string  | 備註或錯誤資訊，通常為空                                    |
| `data.items[].username`          | string  | 使用者名稱                                           |
| `data.items[].token_name`        | string  | 使用的 API Key 名稱                                  |
| `data.items[].model_name`        | string  | 模型名稱                                            |
| `data.items[].quota`             | integer | 本次消費的 quota（**1 USD = 500,000 quota（5 × 10⁵）**） |
| `data.items[].prompt_tokens`     | integer | 輸入 token 數                                      |
| `data.items[].completion_tokens` | integer | 輸出 token 數                                      |
| `data.items[].use_time`          | integer | 請求耗時（秒）                                         |
| `data.items[].is_stream`         | boolean | 是否為串流請求                                         |
| `data.items[].channel`           | integer | 管道 ID                                           |
| `data.items[].channel_name`      | string  | 管道名稱，可能為空                                       |
| `data.items[].token_id`          | integer | API Key ID                                      |
| `data.items[].group`             | string  | 群組名稱                                            |
| `data.items[].ip`                | string  | 請求 IP                                           |
| `data.items[].request_id`        | string  | 請求 ID                                           |
| `data.items[].other`             | string  | 計費中繼資料 JSON 字串，見下方說明                            |

`data.items[].other` 為 JSON 字串，主要包含以下計費與請求資訊：

| 欄位                   | 說明                          |
| -------------------- | --------------------------- |
| `billing_source`     | 計費來源，如 `wallet`             |
| `model_price`        | 模型單價，未指定時為 `-1`             |
| `model_ratio`        | 模型倍率                        |
| `cache_ratio`        | 快取倍率                        |
| `cache_tokens`       | 快取 token 數                  |
| `completion_ratio`   | 輸出倍率                        |
| `group_ratio`        | 群組倍率                        |
| `user_group_ratio`   | 使用者群組倍率                     |
| `reasoning_effort`   | 推理強度設定                      |
| `request_conversion` | 請求轉換方式，如 `OpenAI Responses` |
| `request_path`       | 實際請求路徑，如 `/v1/responses`    |
| `frt`                | 首個 token 回應時間（毫秒）           |

## 取得使用者總消費統計 GET `/api/log/self/stat`

回傳目前帳號的累計消費與速率限制狀態資料，無請求參數。

### 請求範例

```bash cURL theme={null}
curl --request GET \
  --url 'https://console.mixroute.ai/api/log/self/stat' \
  --header 'authorization: Bearer <you-api-key>' \
  --header 'new-api-user: <you-user-id>'
```

### 回應範例

```json Response theme={null}
{
  "data": {
    "quota": 32892251,
    "rpm": 0,
    "tpm": 0
  },
  "message": "",
  "success": true
}
```

### 欄位說明

| 欄位           | 型別      | 說明              |
| ------------ | ------- | --------------- |
| `data.quota` | integer | 累計消費 quota      |
| `data.rpm`   | integer | 每分鐘請求數限制狀態      |
| `data.tpm`   | integer | 每分鐘 token 數限制狀態 |
| `message`    | string  | 錯誤訊息，成功時為空      |
| `success`    | boolean | 是否請求成功          |