GET/v1/api-usage
获取 API 用量
get_api_usage
按密钥和时间步长返回使用组织 API 密钥发出的请求：请求数、错误数（4xx 和 5xx 响应）以及 p50 和 p95 延迟。day 步长最多覆盖 400 天，默认为最近 30 天，请求数和错误数为精确计数。hour 步长最多覆盖 14 天，默认为最近 24 小时；其数值来自 API 请求日志，超过每日日志上限的部分根据抽样估算。延迟来自最近 14 天的 API 请求日志。被限流器和配额拒绝的请求（api.rate_limited、api.quota_exceeded）不计入。没有请求的步长不列出。仅限部分合集（collection_ids）的 API 密钥只能看到自身的用量，以及它在 GET /v1/api-keys 中能看到的密钥的用量。需要权限 ORG_MANAGE_KEYS；API 密钥需要 admin 角色和 admin 权限范围。在 1.62.0 中新增。
身份验证
在 Authorization 请求头中传入 API 密钥：Authorization: Bearer <密钥>。
查询参数
granularitystring序列的步长：UTC 日或小时。
可选值:
dayhour默认值："day"
sincestring (date-time)时间段的开始（包含），带时区偏移的 RFC 3339；向下取整到步长的起点。
untilstring (date-time)时间段的结束（不包含），带时区偏移的 RFC 3339；默认为当前时间。
key_idinteger只统计组织的此 API 密钥。
≥ 1
响应
200成功响应
响应头
RateLimit-Policy当前生效的限制，格式遵循 IETF 草案
draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项"<name>";q=<quota>;w=<window in seconds>。key是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为user，无凭据时为ip）；minute、day和month是组织按 UTC 计算的自然分钟、自然日和自然月的配额。RateLimitRateLimit-Policy中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policy中最严格一项（剩余请求数最少的一项）的限额。X-RateLimit-Remaining最严格限制下的剩余请求数。
X-RateLimit-Reset距最严格限制重置的秒数。
application/json
granularitystring必填序列的步长。
可选值:
dayhoursincestring (date-time)必填时间段的开始：第一个步长的开始时间（UTC）。
untilstring (date-time)必填时间段的结束，不含该时刻（UTC）。
有请求的步长，按时间升序排列，同一步长内按密钥排列。
401未发送凭据（既没有会话 Cookie，也没有 API 密钥），或未找到该密钥。
响应头
RateLimit-Policy当前生效的限制，格式遵循 IETF 草案
draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项"<name>";q=<quota>;w=<window in seconds>。key是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为user，无凭据时为ip）；minute、day和month是组织按 UTC 计算的自然分钟、自然日和自然月的配额。RateLimitRateLimit-Policy中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policy中最严格一项（剩余请求数最少的一项）的限额。X-RateLimit-Remaining最严格限制下的剩余请求数。
X-RateLimit-Reset距最严格限制重置的秒数。
application/json
403不允许执行该操作：角色权限不足、无权访问合集或卡片、请求在“View as”模式下执行，或组织已被暂停或删除（`detail` 为对象，包含 `code: org_suspended | org_deleted`）。
响应头
RateLimit-Policy当前生效的限制，格式遵循 IETF 草案
draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项"<name>";q=<quota>;w=<window in seconds>。key是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为user，无凭据时为ip）；minute、day和month是组织按 UTC 计算的自然分钟、自然日和自然月的配额。RateLimitRateLimit-Policy中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policy中最严格一项（剩余请求数最少的一项）的限额。X-RateLimit-Remaining最严格限制下的剩余请求数。
X-RateLimit-Reset距最严格限制重置的秒数。
application/json
422校验错误：请求体或参数不符合定义的结构（`detail` 为校验错误列表），或参数值超出范围（`detail` 为消息）。
响应头
RateLimit-Policy当前生效的限制，格式遵循 IETF 草案
draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项"<name>";q=<quota>;w=<window in seconds>。key是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为user，无凭据时为ip）；minute、day和month是组织按 UTC 计算的自然分钟、自然日和自然月的配额。RateLimitRateLimit-Policy中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policy中最严格一项（剩余请求数最少的一项）的限额。X-RateLimit-Remaining最严格限制下的剩余请求数。
X-RateLimit-Reset距最严格限制重置的秒数。
application/json
429请求过多（`api.rate_limited`）、组织每分钟、每天或每月的配额已用完（`api.quota_exceeded`；`error.details` 中包含 `quota`、`limit` 和 `reset_at`）、已达到组织的限额，或回答服务繁忙（`answers.engine_busy`）。请等待 `Retry-After` 头中给出的时间。
响应头
Retry-After重试请求前需要等待的秒数。
RateLimit-Policy当前生效的限制，格式遵循 IETF 草案
draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项"<name>";q=<quota>;w=<window in seconds>。key是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为user，无凭据时为ip）；minute、day和month是组织按 UTC 计算的自然分钟、自然日和自然月的配额。RateLimitRateLimit-Policy中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。X-RateLimit-LimitRateLimit-Policy中最严格一项（剩余请求数最少的一项）的限额。X-RateLimit-Remaining最严格限制下的剩余请求数。
X-RateLimit-Reset距最严格限制重置的秒数。
application/json
错误码
除所有请求通用的错误码外，此接口还可能在 error.code 中返回以下错误码。
速率限制
响应带有 RateLimit 和 RateLimit-Policy 头，以及旧版的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。429 响应带有以秒为单位的 Retry-After：等待后重试。