> ## 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 エンドポイント**で、リクエストボディでサービスキーを使用する v1 Analytics API とは異なり、Bearerトークン認証とクエリパラメータを使用します。詳細は以下の[Authentication](#authentication)を参照してください。
</Note>

<Warning>
  このエンドポイントは**リアルタイムの使用量監視向けではありません**。データは1時間単位で集計され、
  レート制限も低く設定されています (チームごとに1時間あたり10リクエスト) 。定期レポートや一括エクスポートに利用してください。
</Warning>

<div id="authentication">
  ## 認証
</div>

このエンドポイントでは、**Bearer token**認証を利用します。`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`                    | Agent Compute Units で課金されるチーム |

`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>

このエンドポイントには、チームごとに**1時間あたり10リクエスト**のレート制限があります。この
制限を超えると、サーバーは `Retry-After` ヘッダーとともに `429 Too Many Requests` を返します。

前にクエリした結果のページネーション (`next_page_cursor` に従うこと) は、この制限には**カウントされません**—
カウントされるのは、各レポートに対して初回にクエリする場合のみです。制限値が低く設定されているのは、このエンドポイントが
定期的なレポート用であり、リアルタイムの使用量監視を目的としたものではないためです。


## OpenAPI

````yaml ja/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: |
    Analytics API v2 は、Enterprise チーム向けにクレジットおよび ACU消費量の分析を提供します。
    データは時間単位で集計された請求イベントに基づいており、柔軟なフィルタリング、グループ化、
    カーソル方式のページネーションをサポートします。
servers:
  - url: https://server.codeium.com
security:
  - bearerAuth: []
paths:
  /api/v2alpha/analytics/consumption:
    get:
      summary: 消費量分析を取得する
      description: >
        認証されたチームのクレジットまたは ACU
        の消費データをクエリします。結果は時間単位で集計された請求イベントに基づいており、日付範囲、product、model、group
        で絞り込めます。


        レスポンスの形式は、チームの請求方式によって異なります。

        - **クレジットベース** チームでは、各行に `prompt_credits` と `flex_credits` が含まれます。

        - **ACUベース** チームでは、各行に `billed_acus` が含まれます。


        レスポンスは 1 時間キャッシュされます。以前に返された `ETag` とともに `If-None-Match`
        を使用すると、データが変更されていない場合に `304 Not Modified` を受け取れます。


        これらのエンドポイントは、定期レポートや一括エクスポート向けに設計されています。リアルタイムの使用量監視を目的としたものでは**ありません**。データは時間単位で集計されており、レート制限も低く設定されています（チームごとに
        1 時間あたり 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: 消費量をクエリする対象の product。
          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: 結果の絞り込み対象とする model UID のカンマ区切りリスト。
          example: claude-4-sonnet,gpt-4.1
        - name: group_id
          in: query
          required: false
          schema:
            type: string
          description: 結果を特定の group に属する user に絞り込みます。サービスキーにはこの group へのアクセス権が必要です。
        - name: user_id
          in: query
          required: false
          schema:
            type: string
          description: 結果を特定の user（auth UID）に絞り込みます。
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
          description: 1 ページあたりに返す最大行数。
        - 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: 指定されたページカーソルは、認証されたチームまたは要求された group に属していません。
          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: >-
            レート制限を超過しました（チームごとに 1 時間あたり 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: 'analytics サービスは利用できません（例: セルフホスト型 deployment）。'
          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: >
        `Authorization` ヘッダーで Bearer トークンとして渡す、**Analytics Read** 権限を持つサービスキー。


        サービスキーは、[チーム設定](https://windsurf.com/team/settings) の「Service
        Keys」セクションで作成します。

````