> ## 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.