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

# 获取用量

> 获取 API 用量分析和成本追踪数据。

获取用量分析数据，包括请求次数、令牌消耗、按模式/模型划分的成本明细，以及延迟百分位数。

## 身份验证

需要 Bearer 令牌。参见[身份验证](/api-reference/authentication)。

## 查询参数

<ParamField query="from" type="string">
  起始日期（ISO 8601 格式，例如 `"2026-04-01"`）。
</ParamField>

<ParamField query="to" type="string">
  结束日期（ISO 8601 格式，例如 `"2026-04-14"`）。
</ParamField>

<ParamField query="scope" type="string">
  `"user"`（在团队之外时为默认值）或 `"org"`（在团队内部时为默认值）。当取值为
  `"org"` 时，响应会反映团队的共享额度池、所有成员的交易记录，以及每一行对应操作者的显示名称
  / 邮箱。需要在当前团队中拥有 `viewUsage` 权限。
</ParamField>

## 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.hitheo.ai/api/v1/usage?from=2026-04-01&to=2026-04-14&scope=org" \
    -H "Authorization: Bearer $THEO_API_KEY"
  ```

  ```typescript SDK theme={null}
  const usage = await theo.usage({ from: "2026-04-01", to: "2026-04-14", scope: "org" });
  ```
</CodeGroup>

## 响应

返回的用量数据包括：

* **总请求数** —— 按天/周/月统计
* **成本明细** —— 按模式、模型和技能划分
* **模型分布** —— 处理你请求的引擎分布情况
* **延迟百分位数** —— p50、p95、p99 响应时间
* **缓存命中率** —— 由语义缓存提供服务的请求所占比例

## 端点

`GET /api/v1/usage`

需要通过 Bearer 令牌进行身份验证。参见[身份验证](/api-reference/authentication)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.