跳转到主要内容

​
文档说明

本文说明如何按成员或组织维度查询 Credits 用量事件与汇总。调用前请完成 获取 API Key，并阅读 约定与规范。

​
权限要求

  • 使用有效的 API Key。
  • API Key 须关联到目标组织。

​
概述

用量查询 API 提供成员级别的 Credits 用量明细和汇总查询，支持按日期、来源、操作和模型等级过滤。

​
主要功能

  • 用量事件列表: 分页查询成员的聚合 Credits 用量记录
  • 用量汇总: 按维度（来源或操作）汇总成员在指定时间范围内的 Credits 消耗

​
API 列表

​
1. 列出用量事件

GET /v1/organizations/{organization_id}/members/{member_id}/usage-events 分页获取指定成员的聚合 Credits 用量记录。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID

​
查询参数

参数类型必填说明
startDatestring否开始时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
endDatestring否结束时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
sourcesstring否按来源过滤，逗号分隔。可选值：IDE、CLI、JetBrains Plugin、Web、QoderWork
operationsstring否按操作过滤，逗号分隔。可选值：Inline Chat、Ask、Agent、Repo Wiki、Quest Mode、Plan Mode、Code Review、Optimize Input、Voice Input、Experts、Image
modelTiersstring否按模型等级过滤，逗号分隔。可选值：Auto、Performance、Efficient、Lite、Ultimate、Vision、Qwen-Coder-Qoder-1.0、Kimi-K2.5、GLM-5、MiniMax-M2.5、DeepSeek-V4.0、Qwen3.5-Plus、Standard、Premium、Enterprise
maxResultsinteger否每页数量（默认 20，最大 100）
nextCreditsstring否分页游标

​
成功响应 (200 OK)

有用量记录、有后续页： 
{
  "usages": [
    {
      "timestamp": 1719849600000,
      "userId": "user_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "timestamp": 1719849500000,
      "userId": "user_abc123",
      "source": "CLI",
      "operation": "Completion",
      "credits": 0.02,
      "cost": 0.02
    }
  ],
  "maxResults": 20,
  "nextCredits": "eyJwYWdlIjogMn0="
}
部分记录可能不返回 userEmail 或 modelTier，集成时请按可选字段处理。
无用量记录 / 最后一页： 
{

  "usages": [],

  "maxResults": 20
}
nextCredits 为空时不返回，表示已到最后一页。

​
响应字段说明

字段类型说明
usagesarray用量记录列表
usages[].timestampint64开始时间（Unix 毫秒时间戳）
usages[].userIdstring用户 ID
usages[].userEmailstring用户邮箱（可能为空）
usages[].sourcestring来源：IDE、CLI、JetBrains Plugin、Web、QoderWork
usages[].operationstring操作：Inline Chat、Ask、Agent、Repo Wiki、Quest Mode、Plan Mode、Code Review、Optimize Input、Voice Input、Experts、Image
usages[].modelTierstring模型等级（可能为空）：Auto、Performance、Efficient、Lite、Ultimate、Vision、Qwen-Coder-Qoder-1.0、Kimi-K2.5、GLM-5、MiniMax-M2.5、DeepSeek-V4.0、Qwen3.5-Plus、Standard、Premium、Enterprise
usages[].creditsfloat64消耗 Credits（保留两位小数）
usages[].costfloat64账单折算后的成本（保留两位小数），与计费规则相关；通常与 credits 数值一致或存在固定折算关系
maxResultsint32本次请求的每页数量
nextCreditsstring下一页游标，为空表示最后一页

​
2. 获取用量汇总

GET /v1/organizations/{organization_id}/members/{member_id}/usage-summary 按指定维度汇总成员在给定时间范围内的 Credits 消耗。时间范围不得超过 7 天。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID

​
查询参数

参数类型必填说明
startDatestring是开始时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
endDatestring是结束时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
groupBystring是分组维度：source（按来源）或 operation（按操作）

​
成功响应 (200 OK)

按来源汇总（**groupBy=source**）： 
{
  "summary": {
    "IDE": 12.50,
    "CLI": 3.25
  }
}
按操作汇总（**groupBy=operation**）： 
{
  "summary": {
    "Agent": 8.40,
    "Completion": 5.10,
    "Inline Chat": 2.25
  }
}
无用量数据： 
{
  "summary": {}
}

​
响应字段说明

字段类型说明
summaryobject汇总结果，key 为分组名称（来源或操作），value 为总 Credits
summary.{key}float64该分组的总 Credits 消耗（保留两位小数）

​
错误响应

缺少必填参数 (400) 
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "startDate is required"
}
时间范围超限 (400) 
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "date range must not exceed 7 days"
}
groupBy 无效 (400) 
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "groupBy is required and must be 'source' or 'operation'"
}

​
3. 列出组织用量事件

GET /v1/organizations/{organization_id}/usage-events 分页获取指定组织下所有成员的聚合 Token 用量记录。返回结构与成员用量事件接口一致。

​
路径参数

参数类型必填说明
organization_idstring是组织 ID

​
查询参数

参数类型必填说明
startDatestring否开始时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
endDatestring否结束时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
sourcesstring否按来源过滤，逗号分隔。可选值：IDE、CLI、JetBrains Plugin、Web、QoderWork
operationsstring否按操作过滤，逗号分隔。可选值：Inline Chat、Ask、Agent、Repo Wiki、Quest Mode、Plan Mode、Code Review、Optimize Input、Voice Input、Experts
modelTiersstring否按模型等级过滤，逗号分隔。可选值：Auto、Performance、Efficient、Lite、Ultimate、Vision、Qwen-Coder-Qoder-1.0、Kimi-K2.5、GLM-5、MiniMax-M2.5、DeepSeek-V4.0、Qwen3.5-Plus、Standard、Premium、Enterprise
maxResultsinteger否每页数量（默认 20，最大 100）
nextTokenstring否分页游标

​
成功响应 (200 OK)

{
  "usages": [
    {
      "timestamp": 1719849600000,
      "userId": "user_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "timestamp": 1719849500000,
      "userId": "user_def456",
      "source": "CLI",
      "operation": "Ask",
      "credits": -0.02,
      "cost": -0.02
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}
部分记录可能不返回 userEmail 或 modelTier，集成时请按可选字段处理。接口默认与成员用量事件接口保持一致，不额外过滤正向 Credits 记录；退款、冲正等负向记录也可能返回。

​
响应字段说明

响应字段定义与 「1. 列出成员用量事件」 完全一致。

​
使用示例

​
列出成员用量事件

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-events?maxResults=20" \
  -H "Authorization: Bearer <api_key>"

​
按日期范围过滤

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-events?startDate=2025-06-01T00:00:00Z&endDate=2025-06-30T23:59:59Z" \
  -H "Authorization: Bearer <api_key>"

​
列出组织用量事件

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/usage-events?maxResults=20" \
  -H "Authorization: Bearer <api_key>"

​
按来源和操作过滤

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-events?sources=IDE&operations=Ask,Agent" \
  -H "Authorization: Bearer <api_key>"

​
按来源汇总用量

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-summary?startDate=2026-03-13T00:00:00Z&endDate=2026-03-20T00:00:00Z&groupBy=source" \
  -H "Authorization: Bearer <api_key>"

​
按操作汇总用量

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-summary?startDate=2026-03-13T00:00:00Z&endDate=2026-03-20T00:00:00Z&groupBy=operation" \
  -H "Authorization: Bearer <api_key>"

​
错误码

错误码HTTP 状态码说明
BadRequest400请求参数无效（如 member_id 为空、日期格式错误、时间范围超限、groupBy 无效）
Unauthorized401API Key 缺失或无效
Forbidden403无权限访问该组织
NotFound404成员不存在
InternalError500服务器内部错误
错误响应结构见 约定与规范 中的「错误响应」一节。