Skip to main content
OpenAPI

用量 API

成员与组织维度的 Credits 用量事件、汇总，以及共享资源包、服务账号专属资源包、席位·月余额批次与指定周期席位·月消耗查询说明。

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

主要功能

  • 组织资源包列表：分页查询组织共享资源包明细。
  • 服务账号资源包列表：分页查询组织内服务账号专属 Credits 资源包的明细，包括绑定主体、有效期、总额度、累计已用量、账面剩余额度与消费适用条件。

列出成员用量事件

GET /v1/organizations/{org_id}/members/{member_id}/usage-events
查询参数：
参数类型说明
startDatestring可选；用量事件开始时间的下界（含），支持 RFC 3339 格式或 Unix 毫秒时间戳
endDatestring可选；用量事件开始时间的上界（含），支持 RFC 3339 格式或 Unix 毫秒时间戳；同时提供起止时间时，范围不得超过 7 天
sourcesstring来源过滤，逗号分隔
operationsstring操作类型过滤，逗号分隔
modelTiersstring模型层级过滤，逗号分隔
maxResultsinteger每页条目数，默认 20，最大 100
nextTokenstring分页游标
请求示例： 
curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_001/usage-events?startDate=2025-01-01T00:00:00Z&endDate=2025-01-07T23:59:59Z&maxResults=20" \
  -H "Authorization: Bearer <api_key>"
响应示例： 
{
  "usages": [
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ab",
      "timestamp": 1736073000000,
      "beginAt": "2025-01-05T10:30:00Z",
      "finishAt": "2025-01-05T10:31:00.123Z",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "memberId": "member_001",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Standard",
      "credits": 1.5,
      "cost": 1.5
    }
  ],
  "maxResults": 20,
  "nextToken": "token_xyz"
}
事件标识与时间字段（成员和组织用量事件接口通用）：
字段类型说明
usages[].eventIdstring聚合用量记录的稳定唯一 ID
usages[].timestampint64开始时间（Unix 毫秒时间戳）
usages[].beginAtstring用量事件开始时间，使用 UTC RFC 3339 格式并保留毫秒精度，与 timestamp 表示同一时刻。
usages[].finishAtstring最新上报的用量事件结束时间，使用 UTC RFC 3339 格式并保留毫秒精度；不可用时不返回该字段。
finishAt 会随同一事件的新用量上报而更新；eventId 和 beginAt 保持不变。

获取用量汇总

GET /v1/organizations/{org_id}/members/{member_id}/usage-summary
查询参数：
参数类型说明
startDatestring开始日期（ISO 8601）
endDatestring结束日期（ISO 8601），时间范围不超过 7 天
groupBystring分组方式：source 或 operation
请求示例： 
curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_001/usage-summary?startDate=2025-01-10T00:00:00Z&endDate=2025-01-16T23:59:59Z&groupBy=source" \
  -H "Authorization: Bearer <api_key>"
响应示例： 
{
  "summary": {
    "IDE": 120.5,
    "Web": 30.0
  }
}

列出组织用量事件

GET /v1/organizations/{org_id}/usage-events
查询参数与成员用量事件接口一致（支持 startDate、endDate、sources、operations、modelTiers、maxResults、nextToken），返回组织内所有成员的用量事件。 请求示例： 
curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/usage-events?startDate=2025-01-01T00:00:00Z&endDate=2025-01-07T23:59:59Z" \
  -H "Authorization: Bearer <api_key>"
响应示例： 
{
  "usages": [
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ac",
      "timestamp": 1736073000000,
      "beginAt": "2025-01-05T10:30:00Z",
      "finishAt": "2025-01-05T10:31:00.123Z",
      "userId": "550e8400-e29b-41d4-a716-446655440005",
      "memberId": "member_005",
      "userEmail": "member5@example.com",
      "source": "IDE",
      "operation": "Inline Chat",
      "modelTier": "Premium",
      "credits": 5.0,
      "cost": 5.0
    }
  ],
  "maxResults": 20,
  "nextToken": "token_next"
}

列出组织共享资源包

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

接入说明

使用目标组织的 Organization API Key，通过 HTTPS 请求接口： 
Authorization: Bearer <ORGANIZATION_API_KEY>
Accept: application/json
API Key 所属组织必须与路径中的 organization_id 一致。两个接口均要求组织身份，不能使用个人凭证或服务账号凭证调用。查询服务账号资源包还要求组织已开通服务账号能力。 以下示例使用 BASE_URL 表示 OpenAPI 服务地址。本站接入地址为 https://api.qoder.com.cn，地址末尾不包含 /。
方法路径查询范围
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 查询参数
参数类型必填默认值说明
statusstring否不过滤active, exhausted, expired, suspended，不区分大小写
orderBystring否expiresAtexpiresAt, activatedAt, remainingValue
orderstring否ascasc 升序或 desc 降序，不区分大小写
maxResultsinteger否20每页数量，建议取值 1–100；大于 100 时按 100，无效值按 20
nextTokenstring否无上一页响应返回的分页游标，首次请求不传
相同排序值按资源包 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
}
资源包字段
字段类型说明
idstring资源包唯一标识
namestring资源包名称
sourcestring来源，取值见下表
statusstring状态，取值见“状态与用量口径”
activatedAtstring激活时间；没有激活时间时不返回该字段
expiresAtstring到期时间
limitValuenumber资源包总额度
usedValuenumber资源包累计已使用额度
remainingValuenumber资源包账面剩余额度
unitstring额度单位，例如 credits；以实际返回值为准
source含义
purchased购买
bonus运营赠送
trial试用
carryOver版本结转
refund退款补偿发放；这是资源包来源，不是退款状态
dev开发用途
sales销售用途
unknown无法识别的来源

查询服务账号资源包

GET /v1/organizations/{organization_id}/service-accounts/resource-packages 查询组织内服务账号专属的 big_model_credits 资源包，额度单位固定为 credits。 查询参数
参数类型必填默认值说明
statusstring否不过滤active, exhausted, expired, suspended, refunded，不区分大小写
maxResultsinteger否20每页数量，建议取值 1–100；大于 100 时按 100，无效值按 20
nextTokenstring否无上一页响应返回的分页游标，首次请求不传
固定按到期时间、创建时间、资源包 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
}
资源包字段
字段类型说明
idstring资源包唯一标识
namestring资源包名称
targetIdstring为空字符串时，组织内服务账号共享该专属包；非空时，为绑定的服务账号 ID
quotaKeystring固定为 big_model_credits
statusstring状态，取值见“状态与用量口径”
createdAtstring创建时间
expiresAtstring到期时间
limitValuenumber资源包总额度
usedValuenumber资源包累计已使用额度
remainingValuenumber资源包账面剩余额度，最低为 0
unitstring固定为 credits
applicabilityConditionsarray资源包的消费适用条件；空数组表示不限定消费维度
applicabilityConditions[].dimensionstring适用维度名称，如 model
applicabilityConditions[].allowedValuesstring[]该维度允许的值或匹配表达式
applicabilityConditions[].matchTypestringexact 精确匹配或 regex 正则匹配；无法识别时为 unknown
targetId 为空的包，其累计用量由共享该包的服务账号共同产生，不能将此数值当成某一个账号的独立消费。服务账号资源包没有 source、activatedAt 字段。

状态与用量口径

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

分页

两个接口采用相同的响应结构：
字段类型说明
resourcePackagesarray当前页资源包列表；无记录时为 []
maxResultsinteger本次请求实际采用的每页数量
nextTokenstring下一页游标，可省略；不存在或为空表示结束
  1. 首次查询不传 nextToken。
  2. 响应有非空 nextToken 时，原样传给同一接口的下一次请求。
  3. 翻页期间保持组织、筛选条件、排序参数和 maxResults 不变。
  4. 游标是服务端生成的不透明字符串，不应自行生成或解析。查询参数需做 URL 编码。
  5. 翻页不提供跨请求快照。拉取期间发生新增、状态或用量变化时，可能影响分页结果；需要重新开始查询以刷新数据。
第二页请求示例： 
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 和空数组。

席位·月余额批次

GET /v1/organizations/{org_id}/seat-month-batches
仅适用于通过三方渠道购买的组织。
请求示例： 
curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/seat-month-batches" \
  -H "Authorization: Bearer <api_key>"
响应示例： 
{
  "batches": [
    {
      "batchId": "batch_001",
      "totalSeatMonths": 120,
      "remainingSeatMonths": 80,
      "effectiveAt": "2025-01-01T00:00:00Z",
      "expiresAt": "2025-12-31T23:59:59Z"
    }
  ]
}

指定周期席位·月消耗

GET /v1/organizations/{org_id}/seat-month-usages
仅适用于通过三方渠道购买的组织。
查询参数：
参数类型说明
periodStartstring必填；周期范围开始时间，RFC 3339 格式
periodEndstring必填；周期范围结束时间，RFC 3339 格式，必须晚于 periodStart
memberIdstring可选；按组织成员 ID 过滤
userIdstring可选；按用户 ID 过滤
pageSizeinteger可选；每页数量，默认 100，最大 500
pageTokenstring可选；传入上一次响应的 nextToken
请求示例： 
curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/seat-month-usages?periodStart=2025-01-01T00:00:00Z&periodEnd=2025-04-01T00:00:00Z&pageSize=100" \
  -H "Authorization: Bearer <api_key>"
响应示例： 
{
  "seatMonthUsages": [
    {
      "memberId": "member_001",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "periodStart": "2025-01-01T00:00:00Z",
      "periodEnd": "2025-02-01T00:00:00Z",
      "consumedSeatMonths": 20.0,
      "refundedSeatMonths": 5.0,
      "netSeatMonths": 15.0
    }
  ],
  "pageSize": 100,
  "nextToken": "2"
}
快速入门
组织管理
安全
购买与计费
OpenAPI
解决方案