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

# Analytics API v2

> Bearerトークン認証、柔軟なグループ化、カーソル方式のページネーションに対応し、消費量データをクエリできる次世代のAnalytics API。

<Warning>
  v2 API は **alpha** 版であり、今後いつでも変更される可能性があります。
</Warning>

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

Analytics API v2 は、Devin Desktop Analytics API の次世代版です。クリーンな REST エンドポイントを通じて、消費量
分析 (クレジットと ACU) を提供します。クエリパラメータによるフィルタリング、柔軟な
グループ化、カーソル方式のページネーション、レスポンスのキャッシュに対応しています。

<Note>
  API の仕様が確定するまでは、v2 エンドポイントは現在 **`/api/v2alpha`** プレフィックス
  で提供されています。ベース URL は `https://server.codeium.com` です。
</Note>

<div id="whats-new-in-v2">
  ## v2 の新機能
</div>

[v1](/ja/desktop/accounts/api-reference/analytics-api-introduction) との最大の違いは、**認証**です。

|          | v1 Analytics API                   | v2 Analytics 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. キーを `Authorization` ヘッダーの Bearer トークンとして利用します

<Warning>サービスキーは厳重に管理し、クライアントサイドのコードや公開リポジトリには絶対に公開しないでください。</Warning>

グループにスコープされたサービスキーにも対応しています。キーがグループにスコープされている場合、結果は自動的に
そのグループに限定されます。

<div id="available-endpoints">
  ## 利用可能なエンドポイント
</div>

| エンドポイント                                                                                                         | 説明                                                     |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [消費量を取得](/ja/desktop/accounts/api-reference/get-consumption) (`GET /api/v2alpha/analytics/consumption`)         | フィルタリング、グループ化、粒度、ページネーションを指定して、クレジットまたは ACU の消費量を取得します |
| [アクティブユーザーを取得](/ja/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>
  これらのエンドポイントは、リアルタイムで使用量を監視する用途**ではありません**。データは1時間単位で集計され、
  レート制限も低く設定されています (チームごとに1時間あたり10リクエスト) 。ライブ
  ダッシュボードやリクエスト単位の追跡ではなく、定期的なレポート作成や一括
  エクスポートに利用してください。
</Warning>

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

前回のクエリをページネーションする場合 (`next_page_cursor` をたどる場合) は、レート
制限には**カウントされません**。カウント対象となるのは、各レポートの最初のクエリだけです。この低い制限は、これらのエンドポイントが
リアルタイム監視ではなく、定期的なレポート作成向けであることを反映しています。