> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 用量 API

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

## 文档说明

本文说明如何按成员或组织维度查询 **Credits** 用量事件与汇总，以及如何查询组织的共享资源包、席位·月余额批次明细与指定周期席位·月消耗（仅三方渠道购买组织适用）。调用前请完成 **[获取 API Key](/zh/account/teams/openapi/get-api-key)**，并阅读 **[约定与规范](/zh/account/teams/openapi/conventions)**。

### 权限要求

* 使用有效的 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）                                                                                                                                                                                      |
| `nextToken`  | string  | 否  | 分页游标                                                                                                                                                                                                    |

#### 成功响应 (200 OK)

**有用量记录、有后续页：**

```json theme={null}
{
  "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`，集成时请按可选字段处理。

**无用量记录 / 最后一页：**

```json theme={null}
{

  "usages": [],

  "maxResults": 20
}
```

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

#### 响应字段说明

| 字段                   | 类型      | 说明                                                                                                                                                                                                |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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   | 本次请求的每页数量                                                                                                                                                                                         |
| `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**`**）：**

```json theme={null}
{
  "summary": {
    "IDE": 12.50,
    "CLI": 3.25
  }
}
```

**按操作汇总（**`**groupBy=operation**`**）：**

```json theme={null}
{
  "summary": {
    "Agent": 8.40,
    "Completion": 5.10,
    "Inline Chat": 2.25
  }
}
```

**无用量数据：**

```json theme={null}
{
  "summary": {}
}
```

#### 响应字段说明

| 字段              | 类型      | 说明                                     |
| --------------- | ------- | -------------------------------------- |
| `summary`       | object  | 汇总结果，key 为分组名称（来源或操作），value 为总 Credits |
| `summary.{key}` | float64 | 该分组的总 Credits 消耗（保留两位小数）               |

#### 错误响应

**缺少必填参数 (400)**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "startDate is required"
}
```

**时间范围超限 (400)**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "date range must not exceed 7 days"
}
```

**groupBy 无效 (400)**

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

**有资源包、有后续页：**

```json theme={null}
{
  "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`（如尚未激活的批次），集成时请按可选字段处理。

**无资源包 / 最后一页：**

```json theme={null}
{

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

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

**orderBy 参数非法 (400)**

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

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

```json theme={null}
{
  "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` **联合判断**：

```text theme={null}
真实可用 = status == "active" AND expiresAt > now
```

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

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

`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)

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

```json theme={null}
{
  "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`，集成时请按可选字段处理。

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

```json theme={null}
{
  "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`：

```text theme={null}
可用批次 = 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)**

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

**pageToken 参数非法 (400)**

```json theme={null}
{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "invalid pageToken"
}
```

#### 状态说明

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

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

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

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

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

按组织维度分页返回指定周期范围内的成员席位·月消耗。响应按成员和计费周期聚合，不返回席位·月批次明细。

#### 计算口径

```text theme={null}
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)

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

```json theme={null}
{
  "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。

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

```json theme={null}
{
  "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)**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "periodStart is required"
}
```

**缺少 periodEnd 参数 (400)**

```json theme={null}
{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "periodEnd is required"
}
```

**时间格式非法 (400)**

```json theme={null}
{
  "requestId": "req_ghi789",
  "code": "BadRequest",
  "message": "invalid periodStart, must be RFC3339"
}
```

**时间范围非法 (400)**

```json theme={null}
{
  "requestId": "req_jkl012",
  "code": "BadRequest",
  "message": "periodStart must be before periodEnd"
}
```

#### 口径说明

**云市场上报口径**

本接口返回的是云市场需要认账/上报的实际净消耗，不是组织内部所有席位·月流水。测试、赠送等来源非云市场购买的不需要上报的席位·月记录不会出现在响应中。

**返还扣减口径**

如果成员在当前周期被移除，且该成员在该周期未使用任何 Credits，系统会将对应席位·月返还给组织余额。满足以下条件的返还会从成员该周期消耗中扣除：

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

**排序与分页**

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

***

## 使用示例

### 列出成员用量事件

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

### 按日期范围过滤

```bash theme={null}
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>"
```

### 列出组织用量事件

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/usage-events?maxResults=20" \
  -H "Authorization: Bearer <api_key>"
```

### 按来源和操作过滤

```bash theme={null}
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>"
```

### 按来源汇总用量

```bash theme={null}
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>"
```

### 按操作汇总用量

```bash theme={null}
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>"
```

### 列出组织资源包

```bash theme={null}
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>"
```

### 资源包翻页查询

```bash theme={null}
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`）。

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

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

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

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

### 席位·月批次翻页查询

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

> `pageToken` 来自上一页响应的 `nextToken`。

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

```bash theme={null}
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>"
```

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

```bash theme={null}
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>"
```

### 席位·月消耗翻页查询

```bash theme={null}
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      | 服务器内部错误                                                                                             |

错误响应结构见 [约定与规范](/zh/account/teams/openapi/conventions) 中的「错误响应」一节。