m4
2.2 KiB
Usage API v1
该契约服务于同机集成启动模式。events、sources/heartbeat 和 capabilities 使用
Authorization: Bearer <EVOSCIENTIST_USAGE_SINK_TOKEN>；该 token 只认证服务端 sender，
不表示用户、角色或 workspace 权限。请求和响应均为 UTF-8 JSON，禁止缓存。
Collector
| Endpoint | 成功响应 | 其他响应 |
|---|---|---|
GET /api/usage/capabilities |
200，schema versions、collector ID、durable ingest | 401 |
POST /api/usage/events |
200 accepted/duplicate |
409 conflict；400/413/422 rejected；401；426 |
POST /api/usage/sources/heartbeat |
200 accepted |
400/413/422；401 |
事件响应至少包含 status、event_id 和稳定的 reason_code。只有 200
accepted/duplicate 允许 sender 删除 inflight 文件。409、400、413、422 移入
quarantine；401、403、426、429、5xx 和网络错误保留并重试或重新协商。
单事件请求上限为 262144 bytes，不接受数组。支持的唯一外部事件版本为
usage-event-v1.schema.json。capabilities 没有共同 schema version 时 sender 不发送事件。
查询
GET /api/usage/status 返回 available、degraded、offline 或 unavailable。
GET /api/usage/summary 与 GET /api/usage/calls 支持 deployment、workspace、thread、turn、
workspace path、provider、model、scope 和 UTC from/to 过滤。默认 7 天，最大 90 天，
超界返回 422。calls 默认 50、最大 500，使用 opaque stable cursor。
所有 Token 合计和调用计数均为十进制字符串。未知调用独立计数，不计入 confirmed Token。
运行参数
默认值：heartbeat interval 15s、TTL 45s、connect/read timeout 1s/3s、retry 1s..60s、 unsupported/schema reprobe 300s/60s、inflight lease 120s、event 262144 bytes、spool 100000 files/1073741824 bytes、query 7/90 days、calls 50/500。