用量 API

权限要求

• 使用有效的 API Key。

• API Key 须关联到目标组织。

主要功能

• 用量事件列表: 分页查询成员的聚合 Credits 用量记录

• 用量汇总: 按维度（来源或操作）汇总成员在指定时间范围内的 Credits 消耗

• 组织资源包列表: 分页查询组织名下所有共享资源包的明细，包括激活时间、有效期、初始/已用/剩余额度与状态

• 席位·月余额批次列表: 分页查询组织名下所有席位·月余额批次的明细，包括来源渠道、剩余数量、生效/到期时间与状态

• 指定周期席位·月消耗列表: 分页查询组织成员在指定周期内的席位·月消耗情况

1. 列出用量事件

GET /v1/organizations/{organization_id}/members/{member_id}/usage-events

分页获取指定成员的聚合 Credits 用量记录。

路径参数

查询参数

成功响应 (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,
  "nextToken": "eyJwYWdlIjogMn0="
}

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

响应字段说明

2. 获取用量汇总

GET /v1/organizations/{organization_id}/members/{member_id}/usage-summary

按指定维度汇总成员在给定时间范围内的 Credits 消耗。时间范围不得超过 7 天。

查询参数

成功响应 (200 OK)

按来源汇总：

{
  "summary": {
    "IDE": 12.50,
    "CLI": 3.25
  }
}

按操作汇总：

{
  "summary": {
    "Agent": 8.40,
    "Completion": 5.10,
    "Inline Chat": 2.25
  }
}

响应字段说明

3. 列出组织用量事件

GET /v1/organizations/{organization_id}/usage-events

分页获取指定组织下所有成员的聚合 Token 用量记录。返回结构与成员用量事件接口一致。

路径参数

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

4. 列出组织共享资源包

GET /v1/organizations/{organization_id}/resource-packages

按组织维度分页返回所有共享资源包明细。

查询参数

成功响应 (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"
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}

响应字段说明

状态说明

如需做精确的「真实可用」判定，建议在客户端结合 status 与 expiresAt 联合判断：真实可用 = status == "active" AND expiresAt > now

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

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

GET /v1/organizations/{organization_id}/seat-month-batches

按组织维度分页返回席位·月余额批次明细。

查询参数

成功响应 (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"
    }
  ],
  "pageSize": 100,
  "nextToken": "2"
}

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

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

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

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

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

GET /v1/organizations/{organization_id}/seat-month-usages

按组织维度分页返回指定周期范围内的成员席位·月消耗。

计算口径

netSeatMonths = max(consumedSeatMonths - refundedSeatMonths, 0)

查询参数

成功响应 (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
    }
  ],
  "pageSize": 100,
  "nextToken": "2"
}

响应字段说明

列出成员用量事件

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

按日期范围过滤

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

按来源汇总用量

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

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

curl -X GET "https://api.qoder.com.cn/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>"