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