# 查询调用用量趋势

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

按时间统计当前用户的调用次数、Token 用量和费用。

```text
GET https://billing.moi.matrixorigin.cn/api/v1/taas/usage-logs/trend
```

## 调用前准备

准备个人访问令牌。创建和管理方法参阅[创建和管理个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)。

查询范围为当前用户有权访问的数据。

## 查询参数

将示例中的 `$MOI_PERSONAL_ACCESS_TOKEN` 替换为个人访问令牌。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --get "https://billing.moi.matrixorigin.cn/api/v1/taas/usage-logs/trend" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN" \
  --data-urlencode "granularity=day"
```

:::::
:::::{tab-item} 参数说明

::::{div} mo-api-parameter-table

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `start_time` | integer | 否 | 开始时间，非负 Unix 秒；不能晚于结束时间。 |
| `end_time` | integer | 否 | 结束时间，非负 Unix 秒。 |
| `model_id` | string | 否 | 模型目录对象 ID。 |
| `model_type` | string | 否 | 模型类型。 |
| `requested_model` | string | 否 | 调用请求填写的模型名称。 |
| `status` | string | 否 | 调用状态，例如 `success` 或 `failed`。 |
| `error_type` | string | 否 | 调用错误类别。 |
| `caller_ip` | string | 否 | 调用方 IP。 |
| `token_key_id` | string | 否 | TaaS 本地密钥 ID。 |
| `token_key_ids` | string | 否 | TaaS 本地密钥 ID 列表；可重复传递或用逗号分隔。 |
| `credential_type` | string | 填写 `credential_id` 时必填 | 凭据类别：`taas_token_key`、`personal_access_token` 或 `service_account_api_key`；必须同时填写 `credential_id`。 |
| `credential_id` | string | 填写 `credential_type` 时必填 | 凭据对象 ID；必须同时填写 `credential_type`。 |
| `billing_event_id` | string | 否 | 计费用量事件 ID。 |
| `billing_record_id` | string | 否 | 计费记录 ID。 |
| `pricing_mode` | string | 否 | 计价方式。 |
| `settlement_method` | string | 否 | 结算方式：genesis 或 `ai_service`。 |
| `enterprise_plan_id` | string | 否 | 企业方案 ID。 |
| `enterprise_contract_no` | string | 否 | 企业合同编号。 |
| `enterprise_plan_model_id` | string | 否 | 企业方案模型 ID。 |
| `response_id` | string | 否 | Responses 响应 ID。 |
| `conversation_id` | string | 否 | Conversation ID。 |
| `ids` | string | 否 | 请求日志 ID 列表；可重复传递或用逗号分隔。 |
| `usage_ids` | string | 否 | ids 的兼容参数；与 ids 合并。 |
| `provider_id` | string | 否 | 供应商 ID；查询仍限定为当前用户的调用。 |
| `granularity` | string | 否 | 统计粒度：`hour` 或 `day`；默认 `hour`。 |

::::

:::::
::::::
:::::::

## 成功响应

返回 HTTP `200`，响应包含按时间分桶的调用统计。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "points": [
    {
      "timestamp": 1788710400,
      "time": "2026-09-07T00:00:00Z",
      "calls": 2,
      "total_calls": 2,
      "input_tokens": 12,
      "output_tokens": 8,
      "total_input_tokens": 12,
      "total_output_tokens": 8,
      "total_user_tokens": 20,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "total_cost": "0.0001",
      "total_channel_cost": "0.00005",
      "total_channel_tokens": 20,
      "total_cache_read_tokens": 0,
      "total_cache_creation_tokens": 0
    }
  ],
  "granularity": "day",
  "start_time": 1788710400,
  "end_time": 1788796799,
  "truncated": false
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `points` | array of object | 按时间升序排列的有数据时间桶；不补齐空桶。 |
| `points[].timestamp` | integer | 时间桶起点，Unix 秒。 |
| `points[].time` | string | 时间桶起点的 UTC 时间，RFC 3339。 |
| `points[].calls` | integer | 该时间桶的调用次数。 |
| `points[].total_calls` | integer | 与 calls 相同。 |
| `points[].input_tokens` | integer | 输入 Token 数。 |
| `points[].output_tokens` | integer | 输出 Token 数。 |
| `points[].total_input_tokens` | integer | 与 `input_tokens` 相同。 |
| `points[].total_output_tokens` | integer | 与 `output_tokens` 相同。 |
| `points[].total_user_tokens` | integer | 输入、输出、缓存读取和缓存写入 Token 之和。 |
| `points[].cache_read_tokens` | integer | 缓存读取 Token 总数。 |
| `points[].cache_creation_tokens` | integer | 缓存写入 Token 总数。 |
| `points[].total_cost` | string | 调用费用合计，十进制字符串。 |
| `points[].total_channel_cost` | string | 关联上游请求的成本合计。 |
| `points[].total_channel_tokens` | integer | 关联上游请求的输入、输出及缓存 Token 总数。 |
| `points[].total_cache_read_tokens` | integer | 与 `cache_read_tokens` 相同。 |
| `points[].total_cache_creation_tokens` | integer | 与 `cache_creation_tokens` 相同。 |
| `granularity` | string | 使用的统计粒度。 |
| `start_time` | integer | 实际统计开始时间，Unix 秒。 |
| `end_time` | integer | 实际统计结束时间，Unix 秒。 |
| `truncated` | boolean | 开始时间缺省或范围超过 999 个间隔时，缩短范围并返回 `true`。 |

字段路径中的 `[]` 表示数组中的每一项。

:::::
::::::
:::::::

结束时间缺省或晚于当前时间时，按当前时间计算。超过范围上限时保留最近的统计区间。

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 400,
  "message": "start_time must be a non-negative unix timestamp"
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | HTTP 错误状态码。 |
| `message` | string | 错误说明。 |

:::::
::::::
:::::::