# 获取单个/多个席位的模型调用数据明细

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=GetSeatUsageDetails&Version=2024-01-01`

查询企业版 `AgentPlanTeam` 模式下，单个或多个席位的模型调用用量明细。用量按 *QueryInterval* 指定的时间粒度（天或小时）聚合。个人版套餐用量请改用 *GetUsageDetails* 接口。

> **说明：注意**
>
> 仅适用于企业版 Agent Plan 套餐；个人版套餐用量请改用 GetUsageDetails。单次请求最多传入 1000 个席位 ID，返回的用量按 QueryInterval 指定的时间粒度（按天或按小时）聚合，时间戳为 epoch 毫秒。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**QueryInterval** `string` `必选` | 聚合粒度

用量数据的聚合粒度。可选值：`Day`（按天）、`Hour`（按小时）。

**SeatIDs** `string[]` `必选` | 席位 ID 列表

待查询的席位 ID 列表，单次请求最多支持传入 1000 个。

**Filter** `object` | 过滤条件

用量明细的过滤条件，可按模型、绑定用户、套餐档位以及时间范围筛选。

**EndTime** `string` `必选` | 结束时间

`Filter.EndTime`

查询时间窗口的结束时间，日期字符串，格式 `YYYY-MM-DD`。

**StartTime** `string` `必选` | 起始时间

`Filter.StartTime`

查询时间窗口的起始时间，日期字符串，格式 `YYYY-MM-DD`。

**ModelID** `string` | 模型 ID

`Filter.ModelID`

限定要查询的模型 ID。

**ModelName** `string` | 模型卡片名

`Filter.ModelName`

限定要查询的模型卡片名称。

**ObjectName** `string[]` | 限定要查询的

`Filter.ObjectName`

对外展示的 Model 、 Harness 名称列表，不传则返回全部

**PlanType** `string` | 套餐档位

`Filter.PlanType`

限定要查询的套餐档位。取值：`Small`、`Medium`、`Large`、`Max`。

**UserName** `string` | 绑定用户名

`Filter.UserName`

限定席位绑定的子用户名，用于过滤该用户绑定期间的用量数据。

## 响应参数

**SeatUsageDetails** `object[]` | 明细列表

按请求顺序返回的席位用量明细列表。

**Details** `object[]` | 调用明细

`SeatUsageDetails.Details`

该席位下各时间点、各模型的调用明细列表。

**BillingType** `string` | 计费类型

`SeatUsageDetails.Details.BillingType`

用量的计费类型。可选值：`WithinPlan`（套餐内用量）、`OutsideOfPlan`（套餐外用量）。

**ObjectName** `string` | 模型/Harness

`SeatUsageDetails.Details.ObjectName`

限定要查询的 Model、Harness 名称列表，不传则返回全部。

**Time** `integer` | 时间点

`SeatUsageDetails.Details.Time`

该条用量记录所属的时间点，Unix 毫秒时间戳。

**Unit** `string` | 用量单位

`SeatUsageDetails.Details.Unit`

*Usage* 的计量单位。常见取值：`Tokens`、`Images`。

**Usage** `integer` | 用量数值

`SeatUsageDetails.Details.Usage`

该时间点上的计费用量，单位由 *Unit* 字段决定。

**SeatID** `string` | 席位 ID

`SeatUsageDetails.SeatID`

该条明细对应的席位 ID。


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=GetSeatUsageDetails&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'X-Date: <X-Date>' \
  -H 'X-Content-Sha256: <X-Content-Sha256>' \
  -H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
  -d '{
  "SeatIDs": ["S7HQ2KP"],
  "QueryInterval": "Day",
  "Filter": {
    "ObjectName": ["doubao-seed-2-1-pro"],
    "UserName": ["zhang_san"],
    "PlanType": ["Max"],
    "StartTime": "2026-05-01",
    "EndTime": "2026-05-10"
  }
}
'
```

#### Response

```
{
  "ResponseMetadata": {
    "RequestId": "20260511051233E9D8204B71C385A6F0",
    "Action": "GetSeatUsageDetails",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "SeatUsageDetails": [
      {
        "SeatID": "seat-agt-mx-001",
        "Details": [
          {
            "Time": 1778284800000,
            "ObjectName": "doubao-seed-2-1-pro-260915",
            "Usage": 48200,
            "Unit": "Tokens",
            "BillingType": "WithinPlan"
          },
          {
            "Time": 1778371200000,
            "ObjectName": "doubao-seed-2-1-pro-260915",
            "Usage": 65300,
            "Unit": "Tokens",
            "BillingType": "WithinPlan"
          },
          {
            "Time": 1778457600000,
            "ObjectName": "doubao-seed-2-1-pro-260915",
            "Usage": 113400,
            "Unit": "Tokens",
            "BillingType": "OutsideOfPlan"
          }
        ]
      }
    ]
  }
}
```