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

# 分析 API v2

> 新一代分析 API，用于查询用量数据，支持 Bearer 令牌身份验证、灵活分组和基于游标的分页。

<Warning>
  v2 API 目前处于 **alpha** 阶段，内容可能随时变更。
</Warning>

<div id="overview">
  ## 概览
</div>

分析 API v2 是 Devin Desktop 分析 API 的新一代版本。它通过简洁的 REST 端点提供用量
分析 (credits 和 ACU) ，并支持按查询参数过滤、灵活分组、基于游标的分页以及响应缓存。

<Note>
  在 API 设计最终敲定之前，v2 端点当前使用 **`/api/v2alpha`** 前缀提供服务。基础 URL 为 `https://server.codeium.com`。
</Note>

<div id="whats-new-in-v2">
  ## v2 的新变化
</div>

与 [v1](/zh/desktop/accounts/api-reference/analytics-api-introduction) 相比，最大的变化是**身份验证**。

|      | v1 分析 API                  | v2 分析 API                                     |
| ---- | -------------------------- | --------------------------------------------- |
| 传输   | 使用 JSON 请求体的 `POST`        | 带查询参数的 `GET`                                  |
| 身份验证 | **请求体中的** `service_key` 字段 | **`Authorization: Bearer <service_key>` 标头**  |
| 权限   | 因端点而异                      | **Analytics Read**                            |
| 分页   | 无                          | 基于游标 (`next_page_cursor` / `page_cursor`)     |
| 缓存   | 无                          | `ETag` + `If-None-Match` (`304 Not Modified`) |

<div id="authentication">
  ## 身份验证
</div>

v2 使用 **Bearer 令牌** 进行身份验证。请将你的服务密钥放在 `Authorization` 标头中，而不是放在请求体中：

```
Authorization: Bearer <your_service_key>
```

服务密钥必须具有 **Analytics Read** 权限。

<div id="creating-a-service-key">
  ### 创建服务密钥
</div>

1. 前往你的[团队设置](https://windsurf.com/team/settings)
2. 进入“Service Keys”部分
3. 创建一个具有 **Analytics Read** 权限的新服务密钥
4. 将该密钥作为 Bearer 令牌放在 `Authorization` 标头中

<Warning>请妥善保管你的服务密钥，切勿在客户端代码或公共代码仓库中暴露它们。</Warning>

支持组作用域的服务密钥——当某个密钥的作用域限定为某个组时，结果会自动
限制在该组内。

<div id="available-endpoints">
  ## 可用端点
</div>

| 端点                                                                                                        | 描述                               |
| --------------------------------------------------------------------------------------------------------- | -------------------------------- |
| [获取用量](/zh/desktop/accounts/api-reference/get-consumption) (`GET /api/v2alpha/analytics/consumption`)     | 查询 credit 或 ACU 用量，支持筛选、分组、粒度和分页 |
| [获取活跃用户](/zh/desktop/accounts/api-reference/get-active-users) (`GET /api/v2alpha/analytics/active-users`) | 统计去重后的活跃用户数，可选按天/月或按用户维度查看       |

<div id="billing-strategy">
  ## 计费策略
</div>

响应会根据你团队的计费策略而变化，该策略会在 `metadata.billing_strategy` 中返回：

* **`CREDITS`** — 行中包含 `prompt_credits` 和 `flex_credits`
* **`ACU`** — 行中包含 `billed_acus`

无论采用哪种策略，都会返回 `message_count` 字段。

<div id="pagination">
  ## 分页
</div>

列表响应采用分页形式返回。当有更多数据时，响应中会包含
`pagination.next_page_cursor`；将其作为 `page_cursor` 查询参数传回，以获取下一
页。游标会在 24 小时后失效。

<div id="caching">
  ## 缓存
</div>

响应中会包含一个 `ETag` 标头。在后续请求中，通过 `If-None-Match` 标头将其发回；
如果数据未发生变化，则会收到 `304 Not Modified`。

<div id="rate-limits">
  ## 速率限制
</div>

<Warning>
  这些端点**不**适用于实时用量监测。数据按小时聚合，
  且速率限制较低 (每个团队每小时 10 次请求) 。请将它们用于定期报告和批量
  导出，而不是实时仪表板或逐请求跟踪。
</Warning>

v2 端点的速率限制为**每个团队每小时 10 次请求**。超出限制时会返回
`429 Too Many Requests`，并附带 `Retry-After` 标头。

对先前查询的分页请求 (沿用 `next_page_cursor`) **不会**计入速率
限制——只有每份报告的初始查询才会计入。较低的限制也说明这些端点
用于定期报告，而非实时监控。