用量 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 毫秒时间戳；同时提供起止时间时，范围不得超过 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,
      "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,
      "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[].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	下一页游标，最后一页不返回

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,
      "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,
      "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. 列出组织共享资源包

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

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?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. 列出组织共享资源包

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​错误响应

​状态说明

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

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

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

​错误响应

​状态说明

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

​计算口径

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​错误响应

​口径说明

​使用示例

​列出成员用量事件

​按日期范围过滤

​列出组织用量事件

​按来源和操作过滤

​按来源汇总用量

​按操作汇总用量

​列出组织资源包

​资源包翻页查询

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

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

​席位·月批次翻页查询

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

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

​席位·月消耗翻页查询

​错误码

文档说明

权限要求

概述

主要功能

API 列表

1. 列出用量事件

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

2. 获取用量汇总

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

错误响应

3. 列出组织用量事件

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

4. 列出组织共享资源包

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

错误响应

状态说明

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

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

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

错误响应

状态说明

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

计算口径

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

错误响应

口径说明

使用示例

列出成员用量事件

按日期范围过滤

列出组织用量事件

按来源和操作过滤

按来源汇总用量

按操作汇总用量

列出组织资源包

资源包翻页查询

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

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

席位·月批次翻页查询

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

按成员查询席位·月消耗

席位·月消耗翻页查询

错误码