获取 API 使用情况

OpenAPI 契约

方法

GET

路径

/api/v1/analytics/api-usage

认证

jwtBearer (bearer) OR automationKey (bearer)

响应状态

200 400 401 403 429 500

请求与响应 Schema

JSON

{
  "requestBody": {},
  "responses": {
    "200": {
      "description": "API usage analytics",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiUsageResponse"
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/RequestError"
        }
      }
    },
    "401": {
      "description": "Authentication required or invalid",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "403": {
      "description": "Authenticated but not permitted",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

如需自定义时间范围，请同时提供 ISO-8601 格式的 from 和 to。它们覆盖 range，结束时间必须晚于开始时间，跨度不得超过 366 天。请使用每个指标的 total 作为所选时间范围的汇总值；各时间桶的构建次数不同时，对每桶平均 NCU 再取平均会产生错误结果。

GET /api/v1/analytics/api-usage 接受 JWT 或带 analytics:read 的 nfy_ 密钥。range 可为 7d、30d（默认）、90d 或 1y；granularity 可为 hour（默认）或 day。

响应包含五个按时间分桶的指标，每个都带有整个范围的汇总值及其数据点：已消耗 NCU、构建次数、构建分钟数（仅统计成功构建）、每次构建的平均 NCU，以及最大并发构建数。响应还包含 grantLine，显示相对于每月赠送额度已使用的 NCU，与所选范围无关。

http

GET /api/v1/analytics/api-usage?range=30d&granularity=hour
Authorization: Bearer <access token>