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

# 获取用量

> 查询积分或 ACU 用量数据，支持灵活的筛选、分组和分页。

<Note>
  这是一个**v2 端点**，使用 Bearer 令牌身份验证和查询参数；不同于 v1 分析 API，后者在请求体中使用服务密钥。请参阅下方的[身份验证](#authentication)。
</Note>

<Warning>
  此端点**不**适用于实时用量监控。数据按小时聚合，且
  速率限制较低 (每个团队每小时 10 个请求) 。请将其用于定期报告和批量导出。
</Warning>

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

此端点使用 **Bearer 令牌** 进行身份验证。请在 `Authorization` 标头中包含你的服务密钥：

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

服务密钥必须具备 **Analytics Read** 权限。请在[团队设置](https://windsurf.com/team/settings)中的 "Service Keys" 下创建一个。

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

响应格式取决于你团队的计费策略：

| 策略        | 已填充字段                            | 描述                     |
| --------- | -------------------------------- | ---------------------- |
| `CREDITS` | `prompt_credits`, `flex_credits` | 标准版 Enterprise SaaS 团队 |
| `ACU`     | `billed_acus`                    | 按 ACU 计费的团队            |

无论采用哪种计费策略，`message_count` 字段 (位于 `consumption` 内) 都会返回。

<div id="grouping-and-granularity">
  ## 分组与粒度
</div>

使用 `granularity` 和 `group_by` 控制返回数据的结构：

* **无粒度或分组** — 在整个日期范围内返回一条聚合结果
* **`granularity=daily`** — 每一行都包含一个格式为 `YYYY-MM-DD` 的 `timestamp`
* **`granularity=monthly`** — 每一行都包含一个格式为 `YYYY-MM` 的 `timestamp`
* **`group_by=user`** — 每一行都包含 `user_id` 和 `user_email`
* **`group_by=user,model_uid`** — 每一行都包含 `user_id`、`user_email` 和 `model_uid`
* **`group_by=ide`** — 每一行都包含一个 `ide`

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

结果采用分页返回，默认每页 1,000 行 (最多 10,000 行) 。当有更多结果时，
响应会在 `pagination` 对象中包含一个 `next_page_cursor`。将其作为 `page_cursor` 查询
参数传入，以获取下一页。

页面游标会在 24 小时后过期。后续的分页请求不会作为新的查询计入你的速率限制。

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

响应包含一个 `ETag` 标头。为避免重复传输数据，请在请求中包含上一次返回的 `ETag` 值作为 `If-None-Match` 标头
——如果数据未发生变化，服务器将返回 `304 Not Modified`。

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

此端点按团队实行速率限制：**每小时 10 次请求**。如果你超过此限制，
服务器会返回 `429 Too Many Requests`，并附带 `Retry-After` 标头。

对先前的查询结果进行分页 (即沿用 `next_page_cursor`) **不会**计入此限制——
只有每份报告的首次查询才会计入。较低的限制说明，此端点用于
定期生成报告，而非实时用量监控。


## OpenAPI

````yaml zh/desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/consumption
openapi: 3.1.0
info:
  title: Devin Desktop Analytics API v2
  version: 2.0.0
  description: |
    分析 API v2 为企业团队提供积分和 ACU 用量分析。
    数据来自按小时聚合的计费事件，并支持灵活筛选、分组和基于游标的分页。
servers:
  - url: https://server.codeium.com
security:
  - bearerAuth: []
paths:
  /api/v2alpha/analytics/consumption:
    get:
      summary: 获取用量分析
      description: >
        查询已通过身份验证的团队的 credit 或 ACU 用量数据。结果来自按小时聚合的计费事件，可按日期范围、产品、模型和组进行筛选。


        响应结构取决于团队的计费策略：

        - **按积分计费** 的团队会在每一行中返回 `prompt_credits` 和 `flex_credits`。

        - **按 ACU 计费** 的团队会在每一行中返回 `billed_acus`。


        响应会缓存 1 小时。将之前返回的 `ETag` 与 `If-None-Match` 搭配使用，即可在数据未发生变化时收到 `304 Not
        Modified`。


        这些端点适用于定期报告和批量导出。它们**不**适用于实时用量监控：数据按小时聚合，且速率限制较低（每个团队每小时 10 个请求）。
      operationId: getConsumption
      parameters:
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: 日期范围的开始日期（含），格式为 `YYYY-MM-DD`。
          example: '2026-01-01T00:00:00.000Z'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: 日期范围的结束日期（含），格式为 `YYYY-MM-DD`。范围不得超过 90 天。
          example: '2026-01-31T00:00:00.000Z'
        - name: product
          in: query
          required: true
          schema:
            type: string
            enum:
              - agent
          description: 要查询用量的产品。
          example: agent
        - name: granularity
          in: query
          required: false
          schema:
            type: string
            enum:
              - daily
              - monthly
          description: |
            用于对结果分组的时间粒度。指定后，每一行都包含 `timestamp` 字段。
            如果省略，结果会在整个日期范围内聚合。
        - name: group_by
          in: query
          required: false
          schema:
            type: string
          description: |
            用于对结果分组的维度列表，以逗号分隔。支持的维度：
            - `user` — 每一行包含 `user_id` 和 `user_email`
            - `model_uid` — 每一行包含 `model_uid`
            - `ide` — 每一行包含 `ide`
          example: user,model_uid
        - name: models
          in: query
          required: false
          schema:
            type: string
          description: 用于筛选结果的模型 UID 列表，以逗号分隔。
          example: claude-4-sonnet,gpt-4.1
        - name: group_id
          in: query
          required: false
          schema:
            type: string
          description: 将结果筛选为特定组中的用户。服务密钥必须具有对此组的访问权限。
        - name: user_id
          in: query
          required: false
          schema:
            type: string
          description: 将结果筛选为特定用户（auth UID）。
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
          description: 每页返回的最大行数。
        - name: page_cursor
          in: query
          required: false
          schema:
            type: string
          description: 来自上一个响应中 `pagination.next_page_cursor` 的不透明游标，用于获取下一页。
        - name: If-None-Match
          in: header
          required: false
          schema:
            type: string
          description: 来自上一个响应的 ETag 值。如果数据未发生变化，服务器将返回 `304 Not Modified`。
      responses:
        '200':
          description: 已成功返回用量数据。
          headers:
            ETag:
              schema:
                type: string
              description: 用于缓存验证的实体标签。在后续请求中将其作为 `If-None-Match` 传递。
            Cache-Control:
              schema:
                type: string
              description: 缓存指令（例如 `private, max-age=3600`）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumptionResponse'
              examples:
                credits:
                  summary: 按积分计费且按天统计的团队
                  value:
                    data:
                      - timestamp: '2026-01-15T00:00:00.000Z'
                        user_id: user_abc123
                        user_email: alice@example.com
                        consumption:
                          prompt_credits: 1250
                          flex_credits: 340
                          message_count: 87
                      - timestamp: '2026-01-15T00:00:00.000Z'
                        user_id: user_def456
                        user_email: bob@example.com
                        consumption:
                          prompt_credits: 980
                          flex_credits: 150
                          message_count: 52
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: CREDITS
                      data_freshness: '2026-01-16T03:00:00.000Z'
                      query_time_ms: 1423
                      team_id: team_abc123
                acu:
                  summary: 按 ACU 计费的团队
                  value:
                    data:
                      - consumption:
                          billed_acus: 42.75
                          message_count: 310
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: ACU
                      data_freshness: '2026-01-16T03:00:00.000Z'
                      query_time_ms: 892
                      team_id: team_def456
        '304':
          description: 自 `If-None-Match` 中提供的 ETag 以来，数据未发生变化。
        '400':
          description: 请求参数无效。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_param:
                  value:
                    error: start_date is required
                date_range:
                  value:
                    error: date range must not exceed 90 days
                bad_product:
                  value:
                    error: 'unsupported product: foo (supported: agent)'
        '401':
          description: 身份验证失败或权限不足。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_auth:
                  value:
                    error: missing Authorization header
                invalid_key:
                  value:
                    error: invalid service key
                insufficient_permissions:
                  value:
                    error: insufficient permissions
        '403':
          description: 提供的页面游标不属于已通过身份验证的团队或所请求的组。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                cursor_team_mismatch:
                  value:
                    error: page cursor does not belong to this team
        '405':
          description: 不允许使用该 HTTP 方法（仅支持 `GET`）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 已超出速率限制（每个团队每小时 10 个请求）。对先前查询结果进行分页不计入此限制。
          headers:
            Retry-After:
              schema:
                type: string
              description: 建议在重试前等待的时间。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error: rate limit exceeded
        '503':
          description: 分析服务不可用（例如在自托管部署中）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    ConsumptionResponse:
      type: object
      required:
        - data
        - pagination
        - metadata
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConsumptionRow'
          description: 用量数据行数组。
        pagination:
          type: object
          properties:
            next_page_cursor:
              type:
                - string
                - 'null'
              description: |
                用于获取下一页结果的不透明游标。在后续请求中，将此值作为 `page_cursor`
                查询参数传递。如果没有更多页面，则为 `null`。
                页面游标会在 24 小时后过期。
        metadata:
          type: object
          properties:
            billing_strategy:
              type: string
              enum:
                - CREDITS
                - ACU
              description: |
                已通过身份验证的团队的计费策略。它决定 `consumption` 中会填充哪些字段：
                - `CREDITS` — `prompt_credits` 和 `flex_credits`
                - `ACU` — `billed_acus`
            data_freshness:
              type: string
              format: date-time
              description: 表示底层数据上次刷新时间的时间戳（截断到小时）。
            query_time_ms:
              type: integer
              format: int64
              description: 服务器端查询执行时间（毫秒）。
            team_id:
              type: string
              description: 从已通过身份验证的服务密钥解析出的团队 ID。
            group_id:
              type: string
              description: 结果所限定到的组 ID。仅在提供了 `group_id` 时出现。
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: 便于人工阅读的错误消息。
    ConsumptionRow:
      type: object
      required:
        - consumption
      properties:
        timestamp:
          type: string
          description: |
            该行的时间桶。格式取决于 `granularity`：按天为 `YYYY-MM-DD`，按月为 `YYYY-MM`。
            仅在指定了 `granularity` 时出现。
          examples:
            - '2026-05-01T00:00:00.000Z'
            - 2026-05
        user_id:
          type: string
          description: 用户标识符（auth UID）。仅在 `group_by` 包含 `user` 时出现。
        user_email:
          type: string
          description: 用户的电子邮件地址。仅在 `group_by` 包含 `user` 时出现。
          examples:
            - alice@example.com
        model_uid:
          type: string
          description: 模型标识符。仅在 `group_by` 包含 `model_uid` 时出现。
          examples:
            - claude-4-sonnet
        ide:
          type: string
          description: IDE 名称。仅在 `group_by` 包含 `ide` 时出现。
          examples:
            - windsurf
            - jetbrains
        consumption:
          $ref: '#/components/schemas/Consumption'
    Consumption:
      type: object
      description: 该行的用量指标。字段会根据团队的计费策略填充。
      properties:
        prompt_credits:
          type: integer
          format: int64
          description: 已消耗的提示积分（仅适用于按积分计费）。
        flex_credits:
          type: integer
          format: int64
          description: 已消耗的 Flex 积分（仅适用于按积分计费）。
        billed_acus:
          type: number
          format: double
          description: 已消耗的计费 ACU（仅适用于按 ACU 计费）。
        message_count:
          type: integer
          format: int64
          description: 该行中的消息数量（计费事件）。无论采用何种计费策略，都会始终填充。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        需要一个具有 **Analytics Read** 权限的服务密钥，并通过 `Authorization` 标头以 Bearer
        令牌的形式传递。


        你可以在[团队设置](https://windsurf.com/team/settings)中的“Service Keys”部分创建服务密钥。

````