用量 API - Qoder

文档说明

本文说明如何按成员或组织维度查询 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_id`	string	是	组织 ID
`member_id`	string	是	成员 ID

查询参数

参数	类型	必填	说明
`startDate`	string	否	开始时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
`endDate`	string	否	结束时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
`sources`	string	否	按来源过滤，逗号分隔。可选值：`IDE`、`CLI`、`JetBrains Plugin`、`Web`、`QoderWork`
`operations`	string	否	按操作过滤，逗号分隔。可选值：`Inline Chat`、`Ask`、`Agent`、`Repo Wiki`、`Quest`、`Plan Mode`、`Code Review`、`Optimize Input`、`Voice Input`、`Experts`、`Image`
`modelTiers`	string	否	按模型等级过滤，逗号分隔。可选值：`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`
`maxResults`	integer	否	每页数量（默认 20，最大 100）
`nextCredits`	string	否	分页游标

成功响应 (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 为空时不返回，表示已到最后一页。

响应字段说明

字段	类型	说明
`usages`	array	用量记录列表
`usages[].timestamp`	int64	开始时间（Unix 毫秒时间戳）
`usages[].userId`	string	用户 ID
`usages[].userEmail`	string	用户邮箱（可能为空）
`usages[].source`	string	来源：`IDE`、`CLI`、`JetBrains Plugin`、`Web`、`QoderWork`
`usages[].operation`	string	操作：`Inline Chat`、`Ask`、`Agent`、`Repo Wiki`、`Quest`、`Plan Mode`、`Code Review`、`Optimize Input`、`Voice Input`、`Experts`、`Image`
`usages[].modelTier`	string	模型等级（可能为空）：`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[].credits`	float64	消耗 Credits（保留两位小数）
`usages[].cost`	float64	账单折算后的成本（保留两位小数），与计费规则相关；通常与 `credits` 数值一致或存在固定折算关系
`maxResults`	int32	本次请求的每页数量
`nextCredits`	string	下一页游标，为空表示最后一页

2. 获取用量汇总

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

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID
`member_id`	string	是	成员 ID

查询参数

参数	类型	必填	说明
`startDate`	string	是	开始时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
`endDate`	string	是	结束时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
`groupBy`	string	是	分组维度：`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": {}
}

响应字段说明

字段	类型	说明
`summary`	object	汇总结果，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_id`	string	是	组织 ID

查询参数

参数	类型	必填	说明
`startDate`	string	否	开始时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
`endDate`	string	否	结束时间，支持 RFC 3339 格式或 Unix 毫秒时间戳
`sources`	string	否	按来源过滤，逗号分隔。可选值：`IDE`、`CLI`、`JetBrains Plugin`、`Web`、`QoderWork`
`operations`	string	否	按操作过滤，逗号分隔。可选值：`Inline Chat`、`Ask`、`Agent`、`Repo Wiki`、`Quest`、`Plan Mode`、`Code Review`、`Optimize Input`、`Voice Input`、`Experts`
`modelTiers`	string	否	按模型等级过滤，逗号分隔。可选值：`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`
`maxResults`	integer	否	每页数量（默认 20，最大 100）
`nextToken`	string	否	分页游标

成功响应 (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. 列出成员用量事件」完全一致。

4. 列出组织共享资源包

GET /v1/organizations/{organization_id}/resource-packages 按组织维度分页返回所有共享资源包明细。响应只包含每个资源包的具体批次信息，不返回汇总（如需汇总，可在客户端对返回的 limitValue / usedValue / remainingValue 自行求和）。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID

查询参数

参数	类型	必填	说明
`status`	string	否	按状态过滤。可选值：`active`、`exhausted`、`expired`、`suspended`。不传时返回组织下全部未删除的资源包
`orderBy`	string	否	排序字段。可选值：`expiresAt`（默认）、`activatedAt`、`remainingValue`
`order`	string	否	排序方向。可选值：`asc`（默认）、`desc`
`maxResults`	integer	否	每页数量（默认 20，最大 100）
`nextToken`	string	否	分页游标。从上一次响应的 `nextToken` 字段透传

成功响应 (200 OK)

有资源包、有后续页：

{
  "resourcePackages": [
    {
      "id": "pkg-001",
      "name": "Enterprise Annual Pack",
      "source": "purchased",
      "status": "active",
      "activatedAt": "2025-01-01T00:00:00Z",
      "expiresAt": "2026-01-01T00:00:00Z",
      "limitValue": 3000.0,
      "usedValue": 800.0,
      "remainingValue": 2200.0,
      "unit": "credits"
    },
    {
      "id": "pkg-002",
      "name": "Trial Pack",
      "source": "trial",
      "status": "exhausted",
      "activatedAt": "2025-03-15T00:00:00Z",
      "expiresAt": "2025-09-15T00:00:00Z",
      "limitValue": 500.0,
      "usedValue": 500.0,
      "remainingValue": 0.0,
      "unit": "credits"
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}

部分资源包可能不返回 activatedAt（如尚未激活的批次），集成时请按可选字段处理。

无资源包 / 最后一页：

{

  "resourcePackages": [],

  "maxResults": 20
}

nextToken 为空时不返回，表示已到最后一页。

响应字段说明

字段	类型	说明
`resourcePackages`	array	资源包列表
`resourcePackages[].id`	string	资源包唯一 ID
`resourcePackages[].name`	string	资源包名称
`resourcePackages[].source`	string	资源包来源：`purchased`（购买）、`bonus`（赠送）、`trial`（试用）、`carryOver`（结转）、`refund`（退款）、`dev`（开发测试）、`sales`（销售配置）
`resourcePackages[].status`	string	资源包状态：`active`（生效中）、`exhausted`（额度已用尽）、`expired`（已过期）、`suspended`（已暂停）
`resourcePackages[].activatedAt`	string	激活时间（RFC 3339 / ISO 8601 格式，UTC，可能为空）
`resourcePackages[].expiresAt`	string	到期时间（RFC 3339 / ISO 8601 格式，UTC）
`resourcePackages[].limitValue`	float64	资源包初始总额度
`resourcePackages[].usedValue`	float64	已消耗额度
`resourcePackages[].remainingValue`	float64	剩余额度（= `limitValue - usedValue`）
`resourcePackages[].unit`	string	额度单位，常见为 `credits`
`maxResults`	int32	本次请求的每页数量
`nextToken`	string	下一页游标，为空时不返回，表示已到最后一页

错误响应

status 参数非法 (400)

{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "invalid status, must be one of: active, exhausted, expired, suspended"
}

orderBy 参数非法 (400)

{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "invalid orderBy field, must be one of: expiresAt, activatedAt, remainingValue"
}

组织不存在或无权限 (404)

{
  "requestId": "req_jkl012",
  "code": "NotFound",
  "message": "organization not found or not accessible"
}

状态说明

资源包状态机如下：

状态	说明	进入条件
`active`	生效中，可消费	资源包激活后默认进入
`exhausted`	已用尽	剩余额度归零（注意：已用尽的资源包到期后状态不会自动变为 `expired`，仍保持 `exhausted`）
`expired`	已过期	由系统每小时执行一次的定时任务，将到期的 `active` 资源包翻转为 `expired`
`suspended`	已暂停	管理端手动操作，暂停后不可消费

由于 expired 状态由小时级定时任务异步刷新，真实到期时刻 → 状态翻转之间存在最长约 1 小时的窗口期，在窗口期内资源包 status 仍为 active 但 expiresAt < now。如需做精确的「真实可用」判定，建议在客户端结合 status 与 expiresAt 联合判断：

真实可用 = status == "active" AND expiresAt > now

使用示例

列出成员用量事件

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>"

列出组织资源包

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/resource-packages?status=active&orderBy=expiresAt&order=asc&maxResults=20" \
  -H "Authorization: Bearer <api_key>"

资源包翻页查询

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/resource-packages?nextToken=eyJwYWdlIjogMn0%3D" \
  -H "Authorization: Bearer <api_key>"

nextToken 中可能包含 URL 保留字符，作为 query 参数传递时请做 URL Encode（例如 = → %3D）。

错误码

错误码	HTTP 状态码	说明
`BadRequest`	400	请求参数无效（如 member_id 为空、日期格式错误、时间范围超限、groupBy 无效）
`Unauthorized`	401	API Key 缺失或无效
`Forbidden`	403	无权限访问该组织
`NotFound`	404	成员不存在
`InternalError`	500	服务器内部错误

错误响应结构见约定与规范中的「错误响应」一节。

Documentation Index

​文档说明

​权限要求

​概述

​主要功能

​API 列表

​1. 列出用量事件

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​2. 获取用量汇总

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​错误响应

​3. 列出组织用量事件

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​4. 列出组织共享资源包

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​错误响应

​状态说明

​使用示例

​列出成员用量事件

​按日期范围过滤

​列出组织用量事件

​按来源和操作过滤

​按来源汇总用量

​按操作汇总用量

​列出组织资源包

​资源包翻页查询

​错误码

文档说明

权限要求

概述

主要功能

API 列表

1. 列出用量事件

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

2. 获取用量汇总

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

错误响应

3. 列出组织用量事件

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

4. 列出组织共享资源包

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

错误响应

状态说明

使用示例

列出成员用量事件

按日期范围过滤

列出组织用量事件

按来源和操作过滤

按来源汇总用量

按操作汇总用量

列出组织资源包

资源包翻页查询

错误码