用量 API

本统计 API 中的 Lite / lite 仅用于查询或表示历史用量，不代表当前可选模型档位。

文档说明

本文说明如何按成员或组织维度查询 Credits 用量事件与汇总，以及如何查询组织的共享资源包、服务账号专属资源包、席位·月余额批次明细与指定周期席位·月消耗（仅三方渠道购买组织适用）。调用前请完成 获取 API Key，并阅读 约定与规范。

权限要求

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

概述

用量查询 API 提供成员级别的 Credits 用量明细和汇总查询，支持按日期、来源、操作和模型等级过滤；同时提供组织维度的共享资源包、服务账号专属资源包、席位·月余额批次与指定周期席位·月消耗查询，支持按状态、周期过滤和分页。

主要功能

用量事件列表: 分页查询成员的聚合 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 毫秒时间戳；同时提供起止时间时，范围不得超过 7 天
`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）
`nextToken`	string	否	分页游标

成功响应 (200 OK)

有用量记录、有后续页：

{
  "usages": [
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ab",
      "timestamp": 1719849600000,
      "beginAt": "2024-07-01T16:00:00Z",
      "finishAt": "2024-07-01T16:01:00.123Z",
      "userId": "user_abc123",
      "memberId": "member_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ac",
      "timestamp": 1719849500000,
      "beginAt": "2024-07-01T15:58:20Z",
      "finishAt": "2024-07-01T16:00:00.456Z",
      "userId": "user_abc123",
      "memberId": "member_abc123",
      "source": "CLI",
      "operation": "Completion",
      "credits": 0.02,
      "cost": 0.02
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}

部分记录可能不返回 userEmail 或 modelTier，集成时请按可选字段处理。

无用量记录 / 最后一页：

{

  "usages": [],

  "maxResults": 20
}

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

响应字段说明

字段	类型	说明
`usages`	array	用量记录列表
`usages[].eventId`	string	聚合用量记录的稳定唯一 ID
`usages[].timestamp`	int64	开始时间（Unix 毫秒时间戳）
`usages[].beginAt`	string	用量事件开始时间，使用 UTC RFC 3339 格式并保留毫秒精度，与 `timestamp` 表示同一时刻。
`usages[].finishAt`	string	最新上报的用量事件结束时间，使用 UTC RFC 3339 格式并保留毫秒精度；不可用时不返回该字段。
`usages[].userId`	string	用户 ID
`usages[].memberId`	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	账单折算后的成本，按 `billingCredits × billingFactor` 计算并向下保留两位小数
`maxResults`	int32	本次请求的每页数量
`nextToken`	string	下一页游标，最后一页不返回

finishAt 会随同一事件的新用量上报而更新；eventId 和 beginAt 保持不变。

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 毫秒时间戳；同时提供起止时间时，范围不得超过 7 天
`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": [
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ab",
      "timestamp": 1719849600000,
      "beginAt": "2024-07-01T16:00:00Z",
      "finishAt": "2024-07-01T16:01:00.123Z",
      "userId": "user_abc123",
      "memberId": "member_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ac",
      "timestamp": 1719849500000,
      "beginAt": "2024-07-01T15:58:20Z",
      "finishAt": "2024-07-01T16:00:00.456Z",
      "userId": "user_def456",
      "memberId": "member_def456",
      "source": "CLI",
      "operation": "Ask",
      "credits": -0.02,
      "cost": -0.02
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}

部分记录可能不返回 userEmail 或 modelTier，集成时请按可选字段处理。接口默认与成员用量事件接口保持一致，不额外过滤正向 Credits 记录；退款、冲正等负向记录也可能返回。

响应字段说明

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

4. 列出组织共享资源包

查询组织共享资源包与服务账号专属 Credits 资源包的总额度、累计已用量、剩余额度和有效期，适用于额度看板、账单核对与余额提醒。

接入说明

使用目标组织的 Organization API Key，通过 HTTPS 请求接口：

Authorization: Bearer <ORGANIZATION_API_KEY>
Accept: application/json

API Key 所属组织必须与路径中的 organization_id 一致。两个接口均要求组织身份，不能使用个人凭证或服务账号凭证调用。查询服务账号资源包还要求组织已开通服务账号能力。以下示例使用 BASE_URL 表示 OpenAPI 服务地址。本站接入地址为 https://api.qoder.com，地址末尾不包含 /。

方法	路径	查询范围
GET	`/v1/organizations/{organization_id}/resource-packages`	组织共享资源包
GET	`/v1/organizations/{organization_id}/service-accounts/resource-packages`	组织内服务账号专属 Credits 资源包

两类资源包分别查询。返回结果是资源包明细，不包含个人资源包，也不包含跨资源包汇总字段。

organization_id 为必填路径参数，类型为 string。
响应为 JSON，字段使用 lowerCamelCase；时间采用 UTC 的 RFC 3339 字符串，如 2027-09-01T00:00:00Z。
额度字段为 JSON number，可包含小数。计算、存储和展示时保留精度，不应直接取整。
成功响应使用 HTTP 200，并返回 Cache-Control: no-store。默认查询全部状态；无符合条件的资源包时返回空数组。

查询组织共享资源包

GET /v1/organizations/{organization_id}/resource-packages 查询参数

参数	类型	必填	默认值	说明
`status`	string	否	不过滤	`active`, `exhausted`, `expired`, `suspended`，不区分大小写
`orderBy`	string	否	`expiresAt`	`expiresAt`, `activatedAt`, `remainingValue`
`order`	string	否	`asc`	`asc` 升序或 `desc` 降序，不区分大小写
`maxResults`	integer	否	20	每页数量，建议取值 1–100；大于 100 时按 100，无效值按 20
`nextToken`	string	否	无	上一页响应返回的分页游标，首次请求不传

相同排序值按资源包 ID 确定顺序，方向与 order 一致。默认包含已过期、已用完和已暂停的记录，已删除的资源包不返回。 请求示例

curl --get "${BASE_URL}/v1/organizations/${ORGANIZATION_ID}/resource-packages" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  -H 'Accept: application/json' \
  --data-urlencode 'status=active' \
  --data-urlencode 'orderBy=expiresAt' \
  --data-urlencode 'order=asc' \
  --data-urlencode 'maxResults=20'

成功响应示例

{
  "resourcePackages": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Organization Shared Credits Pack",
      "source": "purchased",
      "status": "active",
      "activatedAt": "2026-09-01T00:00:00Z",
      "expiresAt": "2027-09-01T00:00:00Z",
      "limitValue": 3000,
      "usedValue": 800.25,
      "remainingValue": 2199.75,
      "unit": "credits"
    }
  ],
  "maxResults": 20
}

资源包字段

字段	类型	说明
`id`	string	资源包唯一标识
`name`	string	资源包名称
`source`	string	来源，取值见下表
`status`	string	状态，取值见“状态与用量口径”
`activatedAt`	string	激活时间；没有激活时间时不返回该字段
`expiresAt`	string	到期时间
`limitValue`	number	资源包总额度
`usedValue`	number	资源包累计已使用额度
`remainingValue`	number	资源包账面剩余额度
`unit`	string	额度单位，例如 `credits`；以实际返回值为准

`source`	含义
`purchased`	购买
`bonus`	运营赠送
`trial`	试用
`carryOver`	版本结转
`refund`	退款补偿发放；这是资源包来源，不是退款状态
`dev`	开发用途
`sales`	销售用途
`unknown`	无法识别的来源

查询服务账号资源包

GET /v1/organizations/{organization_id}/service-accounts/resource-packages 查询组织内服务账号专属的 big_model_credits 资源包，额度单位固定为 credits。 查询参数

参数	类型	必填	默认值	说明
`status`	string	否	不过滤	`active`, `exhausted`, `expired`, `suspended`, `refunded`，不区分大小写
`maxResults`	integer	否	20	每页数量，建议取值 1–100；大于 100 时按 100，无效值按 20
`nextToken`	string	否	无	上一页响应返回的分页游标，首次请求不传

固定按到期时间、创建时间、资源包 ID 升序排列。不支持指定排序字段、时间范围或单个服务账号过滤条件。 请求示例

curl --get "${BASE_URL}/v1/organizations/${ORGANIZATION_ID}/service-accounts/resource-packages" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  -H 'Accept: application/json' \
  --data-urlencode 'status=active' \
  --data-urlencode 'maxResults=20'

成功响应示例

{
  "resourcePackages": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "Service Account Credits Pack",
      "targetId": "",
      "quotaKey": "big_model_credits",
      "status": "active",
      "createdAt": "2026-09-01T00:00:00Z",
      "expiresAt": "2027-09-01T00:00:00Z",
      "limitValue": 300000,
      "usedValue": 12.75,
      "remainingValue": 299987.25,
      "unit": "credits",
      "applicabilityConditions": []
    }
  ],
  "maxResults": 20
}

资源包字段

字段	类型	说明
`id`	string	资源包唯一标识
`name`	string	资源包名称
`targetId`	string	为空字符串时，组织内服务账号共享该专属包；非空时，为绑定的服务账号 ID
`quotaKey`	string	固定为 `big_model_credits`
`status`	string	状态，取值见“状态与用量口径”
`createdAt`	string	创建时间
`expiresAt`	string	到期时间
`limitValue`	number	资源包总额度
`usedValue`	number	资源包累计已使用额度
`remainingValue`	number	资源包账面剩余额度，最低为 0
`unit`	string	固定为 `credits`
`applicabilityConditions`	array	资源包的消费适用条件；空数组表示不限定消费维度
`applicabilityConditions[].dimension`	string	适用维度名称，如 `model`
`applicabilityConditions[].allowedValues`	string[]	该维度允许的值或匹配表达式
`applicabilityConditions[].matchType`	string	`exact` 精确匹配或 `regex` 正则匹配；无法识别时为 `unknown`

targetId 为空的包，其累计用量由共享该包的服务账号共同产生，不能将此数值当成某一个账号的独立消费。服务账号资源包没有 source、activatedAt 字段。

状态与用量口径

状态	共享资源包	服务账号资源包	含义
`active`	支持	支持	生效中；仍需结合到期时间及其他消费条件判断
`exhausted`	支持	支持	额度已用完
`expired`	支持	支持	已过期
`suspended`	支持	支持	已暂停
`refunded`	不支持此筛选值	支持	已退款，停止后续消费，保留累计用量
`unknown`	可能返回	可能返回	无法识别的状态；不可作为查询参数

usedValue 表示资源包生命周期内的累计消费，不是当天用量，也不按组织订阅周期重置。此接口不提供按天、按成员或按服务账号拆分的消费明细。 remainingValue 是账面未消费额度，不保证当前可消费。已过期、已暂停或已退款的资源包即使仍有余额，也不能继续使用；生效中的包还受绑定主体、适用条件和预算等限制。状态更新可能存在延迟，判断有效性时应同时检查 status 和 expiresAt。用于余额提醒时，可筛选 status=active，再检查有效期和适用范围；跨包汇总时须拉取全部分页，并确保单位与统计范围一致。累计用量可能超过总额度，调用方应使用接口返回的原始数值，不要强制将 usedValue 截断为 limitValue。

分页

两个接口采用相同的响应结构：

字段	类型	说明
`resourcePackages`	array	当前页资源包列表；无记录时为 `[]`
`maxResults`	integer	本次请求实际采用的每页数量
`nextToken`	string	下一页游标，可省略；不存在或为空表示结束

首次查询不传 nextToken。
响应有非空 nextToken 时，原样传给同一接口的下一次请求。
翻页期间保持组织、筛选条件、排序参数和 maxResults 不变。
游标是服务端生成的不透明字符串，不应自行生成或解析。查询参数需做 URL 编码。
翻页不提供跨请求快照。拉取期间发生新增、状态或用量变化时，可能影响分页结果；需要重新开始查询以刷新数据。

第二页请求示例：

curl --get "${BASE_URL}/v1/organizations/${ORGANIZATION_ID}/service-accounts/resource-packages" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  --data-urlencode 'status=active' \
  --data-urlencode 'maxResults=20' \
  --data-urlencode "nextToken=${NEXT_TOKEN}"

无匹配记录的响应：

{
  "resourcePackages": [],
  "maxResults": 20
}

错误处理

错误响应使用 requestId、code、message，部分错误还可能返回 details。排查问题时保留 HTTP 状态码及 requestId。

{
  "requestId": "req-example-001",
  "code": "BadRequest",
  "message": "invalid nextToken"
}

HTTP 状态码	典型原因	处理建议
400	无效的 `status`、`nextToken`，或共享包接口的 `orderBy`	按接口约定修正参数；游标失效时重新开始查询
401	缺少认证信息或身份认证失败	检查 Organization API Key 是否有效
403	访问其他组织、使用非组织身份，或组织未开通服务账号能力	检查组织 ID、凭证类型及组织能力；能力不足时可能返回 `OrganizationPlanCapabilityForbidden`
500	服务内部错误	保留 `requestId`，稍后重试；持续失败时联系支持
503	服务暂时不可用	使用退避策略重试

无资源包或筛选结果为空属于正常结果，返回 HTTP 200 和空数组。

5. 列出组织席位·月余额批次

本接口仅适用于通过三方渠道（如云市场兑换码）购买的组织。

GET /v1/organizations/{organization_id}/seat-month-batches 按组织维度分页返回席位·月余额批次明细。响应只包含每个批次的具体信息，不返回汇总。席位·月余额不同于成员统计里的 remainingSeats。remainingSeats 仅适用于非三方渠道购买的组织，表示已购席位中剩余可用席位数；席位·月余额表示组织还剩多少可消费的席位·月批次。一个组织可能多次充值席位·月余额，每一笔批次都有独立的剩余数量和到期时间。

路径参数

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

查询参数

参数	类型	必填	说明
`status`	string	否	按状态过滤。可选值：`active`、`exhausted`、`expired`、`refunded`。不传时返回组织下全部批次
`pageSize`	integer	否	每页数量（默认 100，最大 500）
`pageToken`	string	否	页码游标。翻页时传入上一次响应的 `nextToken` 字段

成功响应 (200 OK)

有席位·月批次、有后续页：

{
  "seatMonthBatches": [
    {
      "id": "batch-001",
      "redemptionCodeId": "rc-001",
      "status": "active",
      "sourceChannel": "REDEMPTION_CODE",
      "thirdPartyInstanceId": "inst_xxx",
      "productCode": "qoder_team_seat_month",
      "reportRequired": true,
      "totalSeatMonths": 120.0,
      "usedSeatMonths": 30.0,
      "remainingSeatMonths": 90.0,
      "effectiveAt": "2026-06-01T00:00:00Z",
      "expiresAt": "2026-09-01T00:00:00Z",
      "createdAt": "2026-06-01T00:00:00Z",
      "updatedAt": "2026-06-10T00:00:00Z"
    },
    {
      "id": "batch-002",
      "redemptionCodeId": "rc-002",
      "status": "exhausted",
      "sourceChannel": "ANNUAL_RETURN",
      "totalSeatMonths": 30.0,
      "usedSeatMonths": 30.0,
      "remainingSeatMonths": 0.0,
      "effectiveAt": "2026-05-01T00:00:00Z",
      "expiresAt": "2026-08-01T00:00:00Z",
      "createdAt": "2026-05-01T00:00:00Z",
      "updatedAt": "2026-05-20T00:00:00Z"
    }
  ],
  "pageSize": 100,
  "nextToken": "2"
}

部分批次可能不返回 redemptionCodeId、sourceChannel、thirdPartyInstanceId 或 productCode，集成时请按可选字段处理。

无席位·月批次 / 最后一页：

{
  "seatMonthBatches": [],
  "pageSize": 100
}

nextToken 为空时不返回，表示已到最后一页。翻页时请把响应里的 nextToken 原样作为下一次请求的 pageToken。

响应字段说明

字段	类型	说明
`seatMonthBatches`	array	席位·月余额批次列表
`seatMonthBatches[].id`	string	席位·月批次 ID
`seatMonthBatches[].redemptionCodeId`	string	关联兑换码记录 ID，不是兑换码明文，可能为空
`seatMonthBatches[].status`	string	批次状态：`active`、`exhausted`、`expired`、`refunded`
`seatMonthBatches[].sourceChannel`	string	来源渠道，例如兑换码、年包返还、云市场等，可能为空
`seatMonthBatches[].thirdPartyInstanceId`	string	三方实例 ID，可能为空
`seatMonthBatches[].productCode`	string	三方商品码，可能为空
`seatMonthBatches[].reportRequired`	boolean	是否参与云市场用量上报
`seatMonthBatches[].totalSeatMonths`	float64	该批次原始席位·月总量
`seatMonthBatches[].usedSeatMonths`	float64	该批次已消耗席位·月
`seatMonthBatches[].remainingSeatMonths`	float64	该批次剩余席位·月
`seatMonthBatches[].effectiveAt`	string	生效时间（RFC 3339 / ISO 8601 格式，UTC）
`seatMonthBatches[].expiresAt`	string	到期时间（RFC 3339 / ISO 8601 格式，UTC）
`seatMonthBatches[].createdAt`	string	创建时间（RFC 3339 / ISO 8601 格式，UTC）
`seatMonthBatches[].updatedAt`	string	更新时间（RFC 3339 / ISO 8601 格式，UTC）
`pageSize`	int32	本次请求的每页数量
`nextToken`	string	下一页游标，为空时不返回，表示已到最后一页

如何计算当前可用席位·月余额

接口不直接返回总余额。可以按以下条件筛选批次，再汇总 remainingSeatMonths：

可用批次 = status == "active"
        AND effectiveAt <= now
        AND expiresAt > now
        AND remainingSeatMonths > 0

例如当前返回 3 个批次：

批次	状态	剩余席位·月	生效时间	到期时间	是否计入可用余额
A	`active`	90.0	已生效	未过期	是
B	`exhausted`	0.0	已生效	未过期	否
C	`active`	20.0	未生效	未过期	否

当前可用席位·月总余额为 90.0。

错误响应

status 参数非法 (400)

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

pageToken 参数非法 (400)

{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "invalid pageToken"
}

状态说明

状态	说明	进入条件
`active`	生效中	批次创建后默认进入，且尚未被耗尽、过期或退款作废
`exhausted`	已用尽	批次剩余额度归零
`expired`	已过期	系统过期回收后进入
`refunded`	已退款作废	退款或作废流程进入

由于过期状态由后台任务异步刷新，真实到期时刻到状态翻转之间可能存在延迟。如果客户需要精确判断「当前是否可用」，建议同时判断 status、effectiveAt、expiresAt 和 remainingSeatMonths。

6. 查询指定周期席位·月消耗

本接口仅适用于通过三方渠道（如云市场兑换码）购买的组织。返回的是云市场需要认账/上报的实际净消耗，不是组织内部所有席位·月流水（如测试、赠送的额度）。

GET /v1/organizations/{organization_id}/seat-month-usages 按组织维度分页返回指定周期范围内的成员席位·月消耗。响应按成员和计费周期聚合，不返回席位·月批次明细。

计算口径

netSeatMonths = max(consumedSeatMonths - refundedSeatMonths, 0)

字段	说明
`consumedSeatMonths`	成员在该周期原始消耗的席位·月
`refundedSeatMonths`	成员在该周期已返还、且可归因到原席位和原周期的席位·月
`netSeatMonths`	成员在该周期的实际净消耗

历史边界：接口上线时间为 2026-06-24T16:00:00Z。上线前因缺少部分周期信息，数据无法保证完整性，请以上线后的周期计算为准。

路径参数

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

查询参数

参数	类型	必填	说明
`periodStart`	string	是	周期范围开始时间，RFC 3339 格式，例如 `2026-06-01T00:00:00Z`
`periodEnd`	string	是	周期范围结束时间，RFC 3339 格式，必须晚于 `periodStart`
`memberId`	string	否	按组织成员 ID 过滤
`userId`	string	否	按用户 ID 过滤
`pageSize`	integer	否	每页数量（默认 100，最大 500）
`pageToken`	string	否	页码游标。翻页时传入上一次响应的 `nextToken` 字段

查询结果只包含满足 periodStart >= 请求 periodStart 且 periodEnd <= 请求 periodEnd 的完整计费周期。建议使用实际计费周期边界查询。

成功响应 (200 OK)

有席位·月消耗记录、有后续页：

{
  "seatMonthUsages": [
    {
      "memberId": "member_abc123",
      "userId": "user_abc123",
      "periodStart": "2026-06-01T00:00:00Z",
      "periodEnd": "2026-07-01T00:00:00Z",
      "consumedSeatMonths": 20.0,
      "refundedSeatMonths": 5.0,
      "netSeatMonths": 15.0
    },
    {
      "memberId": "member_def456",
      "userId": "user_def456",
      "periodStart": "2026-06-01T00:00:00Z",
      "periodEnd": "2026-07-01T00:00:00Z",
      "consumedSeatMonths": 1.0,
      "refundedSeatMonths": 1.0,
      "netSeatMonths": 0.0
    }
  ],
  "pageSize": 100,
  "nextToken": "2"
}

全额返还后 netSeatMonths 可能为 0。例如成员被分配席位后未使用 Credits，后续移除成员时席位·月返还给组织，该成员该周期净消耗为 0。

无席位·月消耗记录 / 最后一页：

{
  "seatMonthUsages": [],
  "pageSize": 100
}

nextToken 为空时不返回，表示已到最后一页。翻页时请把响应里的 nextToken 原样作为下一次请求的 pageToken。

响应字段说明

字段	类型	说明
`seatMonthUsages`	array	成员席位·月消耗列表
`seatMonthUsages[].memberId`	string	组织成员 ID
`seatMonthUsages[].userId`	string	用户 ID
`seatMonthUsages[].periodStart`	string	计费周期开始时间，RFC 3339 / ISO 8601 格式
`seatMonthUsages[].periodEnd`	string	计费周期结束时间，RFC 3339 / ISO 8601 格式
`seatMonthUsages[].consumedSeatMonths`	float64	该成员该周期原始消耗的席位·月
`seatMonthUsages[].refundedSeatMonths`	float64	该成员该周期已返还的席位·月
`seatMonthUsages[].netSeatMonths`	float64	该成员该周期实际净消耗的席位·月
`pageSize`	int32	本次请求的每页数量
`nextToken`	string	下一页页码游标，为空时不返回，表示已到最后一页

错误响应

缺少 periodStart 参数 (400)

{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "periodStart is required"
}

缺少 periodEnd 参数 (400)

{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "periodEnd is required"
}

时间格式非法 (400)

{
  "requestId": "req_ghi789",
  "code": "BadRequest",
  "message": "invalid periodStart, must be RFC3339"
}

时间范围非法 (400)

{
  "requestId": "req_jkl012",
  "code": "BadRequest",
  "message": "periodStart must be before periodEnd"
}

口径说明

云市场上报口径 本接口返回的是云市场需要认账/上报的实际净消耗，不是组织内部所有席位·月流水。测试、赠送等来源非云市场购买的不需要上报的席位·月记录不会出现在响应中。 返还扣减口径 如果成员在当前周期被移除，且该成员在该周期未使用任何 Credits，系统会将对应席位·月返还给组织余额。满足以下条件的返还会从成员该周期消耗中扣除：

条件	说明
同一组织	返还记录属于同一个组织
同一席位分配	返还记录可以关联到原席位分配 ID
同一计费周期	返还记录带有原周期开始和结束时间
返还类型	返还流水为 `REFUND` / `INCREASE`

排序与分页 结果默认按 periodStart 倒序（较新周期在前）、memberId 升序、userId 升序排列。pageToken 使用响应里的 nextToken 继续翻页；未返回 nextToken 表示没有下一页。

使用示例

列出成员用量事件

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-07T23: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?status=active&orderBy=expiresAt&order=asc&maxResults=20&nextToken=eyJwYWdlIjogMn0%3D" \
  -H "Authorization: Bearer <api_key>"

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

列出组织席位·月余额批次

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-batches?pageSize=100" \
  -H "Authorization: Bearer <api_key>"

仅查询生效中的席位·月余额批次

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-batches?status=active&pageSize=100" \
  -H "Authorization: Bearer <api_key>"

席位·月批次翻页查询

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-batches?pageToken=2" \
  -H "Authorization: Bearer <api_key>"

pageToken 来自上一页响应的 nextToken。

查询指定周期内的席位·月消耗

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-usages?periodStart=2026-06-01T00:00:00Z&periodEnd=2026-07-01T00:00:00Z&pageSize=100" \
  -H "Authorization: Bearer <api_key>"

按成员查询席位·月消耗

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-usages?periodStart=2026-06-01T00:00:00Z&periodEnd=2026-07-01T00:00:00Z&memberId=member_xxx&pageSize=100" \
  -H "Authorization: Bearer <api_key>"

席位·月消耗翻页查询

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-usages?periodStart=2026-06-01T00:00:00Z&periodEnd=2026-08-01T00:00:00Z&pageSize=20&pageToken=2" \
  -H "Authorization: Bearer <api_key>"

pageToken 来自上一页响应的 nextToken。

错误码

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

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

​文档说明

​权限要求

​概述

​主要功能

​API 列表

​1. 列出用量事件

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​2. 获取用量汇总

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​错误响应

​3. 列出组织用量事件

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

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

​接入说明

​查询组织共享资源包

​查询服务账号资源包

​状态与用量口径

​分页

​错误处理

​5. 列出组织席位·月余额批次

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​如何计算当前可用席位·月余额

​错误响应

​状态说明

​6. 查询指定周期席位·月消耗

​计算口径

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​错误响应

​口径说明

​使用示例

​列出成员用量事件

​按日期范围过滤

​列出组织用量事件

​按来源和操作过滤

​按来源汇总用量

​按操作汇总用量

​列出组织资源包

​资源包翻页查询

​列出组织席位·月余额批次

​仅查询生效中的席位·月余额批次

​席位·月批次翻页查询

​查询指定周期内的席位·月消耗

​按成员查询席位·月消耗

​席位·月消耗翻页查询

​错误码

文档说明

权限要求

概述

主要功能

API 列表

1. 列出用量事件

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

2. 获取用量汇总

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

错误响应

3. 列出组织用量事件

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

4. 列出组织共享资源包

接入说明

查询组织共享资源包

查询服务账号资源包

状态与用量口径

分页

错误处理

5. 列出组织席位·月余额批次

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

如何计算当前可用席位·月余额

错误响应

状态说明

6. 查询指定周期席位·月消耗

计算口径

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

错误响应

口径说明

使用示例

列出成员用量事件

按日期范围过滤

列出组织用量事件

按来源和操作过滤

按来源汇总用量

按操作汇总用量

列出组织资源包

资源包翻页查询

列出组织席位·月余额批次

仅查询生效中的席位·月余额批次

席位·月批次翻页查询

查询指定周期内的席位·月消耗

按成员查询席位·月消耗

席位·月消耗翻页查询

错误码