# 查询推理用量

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

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

查询推理用量，支持按时间范围、接入点、模型等多维度过滤，返回 token 消耗及请求数等用量数据。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [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 参数

**EndTime** `string` `必选` | 结束日期

查询结束日期，格式为 `yyyy-MM-dd`，时区为北京时间（UTC+8）。需大于等于 *StartTime*。

**QueryInterval** `string` `必选` | 查询粒度

查询粒度。可取值：

- `Day`：按天统计
- `Hour`：按小时统计

**StartTime** `string` `必选` | 起始日期

查询起始日期，格式为 `yyyy-MM-dd`，时区为北京时间（UTC+8）。

**Filters** `object[]` | 过滤条件

过滤条件数组，支持按鉴权 token、模型名称、接入点 ID、批量任务 ID 等字段过滤。多个过滤项之间为「与」关系。

**Key** `string` `必选` | 过滤字段

`Filters.Key`

过滤字段。目前支持：

> **注意**
>
> 由于安全升级，用量查询能力将调整为基于 `ApiKeyID` 的查询方式。
>
> * 2026-08-12 及之后创建的 API Key，仅支持通过 `ApiKeyID` 查询用量，不再支持 `AuthToken` 查询方式。
> * 2026-08-12 之前创建的存量 API Key，当前同时兼容 `AuthToken` 与 `ApiKeyID` 两种用量查询方式；其中 `AuthToken` 查询方式即将下线。**为避免业务受影响，请您尽快将业务逻辑切换至 `ApiKeyID` 进行用量查询。**

- `AuthToken`：鉴权 token。
    - 若为 jwt token 鉴权，则默认为 `****`
    - 若为 apikey 鉴权：
        - 传统格式 API Key：取前 8 位 + `****` + 后 12 位字符，示例：`37efcc63****92c8fe4c880e`
        - 新版方舟 API Key：取前 3 位 + `****` + 后 5 位字符，示例：`ark****d5b88`
- `ApikeyID`：API Key 对应的资源 ID

> **说明**
>
> 在按 API Key 维度统计用量的场景中，会出现不同命名，**实际指向同一个 API Key 唯一标识**，仅命名存在差异，对应关系如下：
>
> * 资源 ID（Resource ID）：火山方舟控制台 **API Key 管理** 页面展示的列名。
> * `ApikeyID` / `apikey_id`：分账账单系统中的分账维度名称，以及查账单 API 过滤条件 *Filters* 的键名。
>
> 您可以前往方舟控制台的 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apikey) 页面，在对应 API Key 的详情中查看并复制“资源 ID”。请注意，资源 ID 并非 API Key 密钥本身，请勿将 API Key 密钥作为 `ApiKeyID` 传入。

- `ModelUnitID`：模型单元 ID
- `BillingStatus`：计费方式。可取值：`no_need_billing`（无需付费，一般为客户未开通前体验的用量）、`free_for_model_unit`（模型单元用量）、`free_for_free_quota` / `free_for_limit_boundary`（超过安心体验边界的用量）、`normal`（正常后付费按量计费）、`free_for_viptier`（TPM 保障包用量）
- `ModelName`：模型名称
- `ModelVersion`：模型版本
- `ModelEndpoint`：接入点 ID
- `BatchJobID`：批量任务 ID
- `EndpointName`：接入点名称
- `BatchType`：批量推理类型

**ValueLike** `string` `必选` | 相似匹配值

`Filters.ValueLike`

相似匹配值，按前缀/包含等近似规则过滤。*Values* 与 *ValueLike* 不能同时传递。

**Values** `string[]` `必选` | 过滤值列表

`Filters.Values`

过滤值列表。若 *Values* 长度为 0，则表示不按 *Key* 过滤，但返回结果列中仍包含该 *Key*。

**ProjectName** `string` `默认值 default` | 项目名称

资源所属的项目名称。若资源不在默认项目中，需填写正确的项目名称。

**ShowWindowDetail** `boolean` `默认值 false` | 展示窗口详情

是否在返回结果中展示计费窗口详情（如窗口序列、窗口描述、窗口 token 上限等）。

## 响应参数

**Data** `string[]` | 用量数据

用量数据，二维数组。每行对应一条记录，列顺序与 *Fields* 一致。

**DataCount** `integer` | 数据行数

返回的数据行数，即 *Data* 数组的长度。

**Fields** `object[]` | 列定义

返回数据的列定义，描述 *Data* 数组中每一列的类型与名称。

**Name** `string` | 列名称

`Fields.Name`

列名称。包括请求参数 *Filters* 内的所有字段。默认包括：

- `AccountID`：账户 ID
- `Day`：日期
- `Hour`：小时
- `InputTokens`：输入 token 数
- `OutputTokens`：输出 token 数
- `TotalTokens`：总 token 数
- `ReqCnt`：请求数

若返回按窗口划分的数据，则额外包含：

- `BillingStatus`：计费类型
- `WindowMatchOrder`：窗口序列
- `WindowDescription`：窗口描述
- `WindowMaxInputTokens`：窗口输入 token 上限
- `WindowMaxOutputTokens`：窗口输出 token 上限

**Type** `string` | 列类型

`Fields.Type`

列数据类型，如 `string`、`integer` 等。


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=GetInferenceUsage&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 '{
    "QueryInterval": "Hour",
    "StartTime": "2025-09-17",
    "EndTime": "2025-09-19",
    "Filters": [
        {
            "Key": "ModelEndpoint",
            "Values": [
                "ep-20xxxx-xxx"
            ]
        }
    ]
}
'
```

#### Response

```
{
    "ResponseMetadata": {
        "RequestId": "202509231425196F1F971FFFC20F544E6A",
        "Action": "GetInferenceUsage",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
    },
    "Result": {
        "Fields": [
            {
                "Name": "AccountID",
                "Type": "BIGINT"
            },
            {
                "Name": "ModelEndpoint",
                "Type": "STRING"
            },
            {
                "Name": "Day",
                "Type": "DATE"
            },
            {
                "Name": "Hour",
                "Type": "STRING"
            },
            {
                "Name": "InputTokens",
                "Type": "BIGINT"
            },
            {
                "Name": "OutputTokens",
                "Type": "BIGINT"
            },
            {
                "Name": "ImageCount",
                "Type": "BIGINT"
            },
            {
                "Name": "TotalTokens",
                "Type": "BIGINT"
            },
            {
                "Name": "ReqCnt",
                "Type": "BIGINT"
            }
        ],
        "Data": [
            [
                "2100339946",
                "ep-20xxxx-xxx",
                "2025-09-18",
                "16",
                "3062",
                "914",
                "0",
                "3976",
                "1"
            ],
            [
                "2100339946",
                "ep-20xxxx-xxx",
                "2025-09-17",
                "14",
                "6955",
                "1921",
                "0",
                "8876",
                "4"
            ]
        ],
        "DataCount": 2
    }
}
```