Reporting Access Key

Reporting Access Key 是在控制檯管理的只讀報表密鑰，用于从内部系统查詢 API Key、用量、Token 消耗、任務記錄和費用数据。它适合财务對賬、客戶用量核对、監控和内部 BI 管道，不用于调用模型。

1. 适用场景

当你需要以下能力时，可以使用 Reporting Access Key：

将发票或账单金额与任務级用量記錄做核对
将用量数据同步到内部 BI、FinOps 或監控系统
按 API Key、模型、任務类型、狀態或日期統計 Token 与費用
在不共享控制檯權限的情况下排查单个任務記錄

它不是模型调用密鑰，只能访问本文档中的 /api/open/v1/* 報表接口。

2. 創建与管理

打开控制檯頁面：

/dashboard/apikeys

在 Reporting Access Key 卡片中：

点击 Generate 生成密鑰。
複製密鑰，并保存到安全的密鑰管理系统中。
需要再次複製完整值时，点击 Copy。
需要停用时，点击 Revoke。

安全规则：

頁面默认只展示脫敏后的 key。
完整 key 只会在点击 Copy 时临时獲取。
不要把完整 key 存入 localStorage、analytics、截图、工单或客戶端日誌。
當前每个用户最多只有一个 active Reporting Access Key。
revoke 后密鑰会立即失效，但記錄不会被 hard delete。

3. 认证方式

在請求头中携带 Reporting Access Key：

Authorization: Bearer <REPORTING_ACCESS_KEY>
Accept: application/json

所有響應使用统一结构：

{
  "code": 200,
  "msg": "",
  "data": {}
}

4. 接口列表

Endpoint	Purpose	Max date range
`GET /api/open/v1/apikeys`	List visible API keys and their last usage time	Not applicable
`GET /api/open/v1/usage/summary`	Aggregate requests, tokens, credits, and USD amount	31 days
`GET /api/open/v1/usage/daily`	Daily usage breakdown, optionally grouped by API key and model	31 days
`GET /api/open/v1/usage/tasks`	Paginated task-level usage records	7 days
`GET /api/open/v1/usage/tasks/{task_id}`	Single task detail	Not applicable

Base URL:

https://reachapi.ai/api/open/v1

本地開發可使用：

http://localhost:3000/api/open/v1

5. 查詢 API Key 列表

curl -sS "https://reachapi.ai/api/open/v1/apikeys?page=1&page_size=20&status=active" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

查詢参数：

Field	Type	Required	Description
`page`	integer	No	Page number. Default: `1`
`page_size`	integer	No	Page size. Default: `50`, maximum: `200`
`status`	string	No	Filter API keys by status, for example `active`

Example response:

{
  "code": 200,
  "msg": "",
  "data": {
    "total": 3,
    "page": 1,
    "page_size": 20,
    "items": [
      {
        "apikey_id": "ak_123",
        "apikey_name": "Production gateway",
        "status": "active",
        "created_at": "2026-06-27T08:00:00.000Z",
        "last_used_at": "2026-06-27T09:15:00.000Z",
        "hourly_limit_usd": "5.00000000",
        "daily_limit_usd": "20.00000000",
        "total_limit_usd": "100.00000000",
        "quota_timezone": "Asia/Shanghai"
      }
    ]
  }
}

每個條目包含：

欄位	說明
`apikey_id`	API key ID
`apikey_name`	API key 名稱
`status`	API key 狀態（`active` / `deleted`）
`created_at`	建立時間
`last_used_at`	最近使用時間（未使用過則為 `null`）
`hourly_limit_usd`	小時消費限額（USD），未設定則為 `null`
`daily_limit_usd`	每日消費限額（USD），未設定則為 `null`
`total_limit_usd`	累計消費限額（USD），未設定則為 `null`
`quota_timezone`	限額視窗時區（預設 `Asia/Shanghai`）

6. 用量彙總

curl -sS "https://reachapi.ai/api/open/v1/usage/summary?start_date=2026-06-01&end_date=2026-06-07&timezone=Asia/Shanghai" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

查詢参数：

Field	Type	Required	Description
`start_date`	string	Yes	Date in `YYYY-MM-DD` format
`end_date`	string	Yes	Date in `YYYY-MM-DD` format. Maximum 31-day range
`timezone`	string	No	IANA timezone. Default: `UTC`
`apikey_id`	string	No	Filter by one visible API key
`model`	string	No	Filter by model ID
`task_type`	string	No	Filter by task type
`status`	string	No	Filter by task status
`finance_status`	string	No	Filter by billing status
`provider_job_id`	string	No	Filter by upstream provider job ID

響應中会包含請求数、成功/失败数、各类 token、actual_credits 和 USD 字符串 total_amount。

7. 按日統計

curl -sS "https://reachapi.ai/api/open/v1/usage/daily?start_date=2026-06-01&end_date=2026-06-07&group_by=apikey,model" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

group_by 支持：

Value	Description
`none`	One row per day
`apikey`	Group by day and API key
`model`	Group by day and model
`apikey,model`	Group by day, API key, and model

8. 任務列表

curl -sS "https://reachapi.ai/api/open/v1/usage/tasks?start_date=2026-06-01&end_date=2026-06-07&page=1&page_size=50" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

任務列表支持与 usage/summary 相同的篩選参数。为了保证查詢稳定，日期範圍限制为 7 天。

每条任務記錄包含：

Field	Description
`task_id`	Internal task ID
`created_at`, `completed_at`	Task timestamps
`model`, `task_type`	Model and workload type
`apikey_id`, `apikey_name`	API key attribution
`provider_job_id`	Upstream provider job ID when available
`status`, `finance_status`	Execution and billing state
token fields	Input, output, cache, reasoning, image, audio, and video token usage
`total_amount`, `actual_credits`	USD amount string and internal credit amount

9. 任務详情

curl -sS "https://reachapi.ai/api/open/v1/usage/tasks/task_123" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

任務详情接口返回单个任務的金额、Token 和错误信息，适合核对某个客戶工单、provider job 或账单明细。

10. 錯誤碼

HTTP status	`msg` example	Scenario
`401`	`Unauthorized`	Missing, malformed, invalid, or revoked Reporting Access Key
`400`	`Invalid pagination`	`page` or `page_size` is not a positive integer
`400`	`Invalid start_date` / `Invalid end_date`	Date format is not `YYYY-MM-DD`
`400`	`Date range is too large`	Date range exceeds the endpoint limit
`400`	`Invalid group_by`	Unsupported daily grouping value
`403`	`Forbidden`	The requested `apikey_id` is not visible to this Reporting Access Key
`404`	`Task not found`	Task does not exist or is not visible

11. 使用日誌

客戶使用 Reporting Access Key 调用 Open API 时，服务端会写入独立的 accesskey 使用日誌。

日誌用于运维排查和用量审计，只記錄脫敏后的請求元信息，例如 event、request ID、key prefix、user ID、method、path、安全 query、status code、duration、IP、user agent 和 error code。

日誌不会記錄完整 access key、Authorization header、cookie、password、key hash、ciphertext 或數據庫连接串。

Reporting Access Key

On this page