> ## 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 <token>` ヘッダー**                            |
| 認証情報     | Windsurf サービスキー                    | Windsurf サービスキー **または Devin サービスユーザー APIキー**                        |
| 権限       | エンドポイントごとに異なる                      | **Analytics Read** (Windsurf) / **Use Local Analytics API** (Devin) |
| ページネーション | なし                                 | カーソル方式 (`next_page_cursor` / `page_cursor`)                         |
| キャッシュ    | なし                                 | `ETag` + `If-None-Match` (`304 Not Modified`)                       |

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

v2 では **Bearer トークン** 認証を利用します。認証情報はリクエストボディではなく、`Authorization` ヘッダーに渡してください：

```
Authorization: Bearer <your_token>
```

利用できる認証情報は 2 種類です。**Devin サービスユーザー APIキー** (推奨 — [Devin API](/ja/api-reference/authentication) で利用する
`cog_` キーと同じもの) または **Windsurf サービスキー**です。

<div id="devin-service-user-api-keys">
  ### Devin サービスユーザー APIキー
</div>

すでに Devin のサービスユーザーを管理している場合、Windsurf 用に別途認証情報を作成する必要はありません。

1. 組織の場合は **Settings > Devin API** (**サービスユーザー** タブ)、Enterprise の場合は
   **Enterprise settings > Devin API** (**サービスユーザー** タブ) でサービスユーザーをプロビジョニングします
2. **Use Local Analytics API** 権限を含む[カスタムロール](/ja/enterprise/security-access/custom-roles)を割り当てます (組み込みの管理者ロールにはすでにこの権限が含まれています)
3. プロビジョニング後に表示される APIキーをコピーします。このキーは `cog_` で始まります
4. このキーを Bearer トークンとして使用します

```bash theme={null}
curl "https://server.codeium.com/api/v2alpha/analytics/consumption?start_date=2026-08-01&end_date=2026-08-07&product=agent" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

結果はサービスユーザーが所属する Devin アカウント全体を対象とし、`metadata.team_id` は
アカウントの Devin チーム識別子 (`devin-team$<account_id>`) です。

<Note>
  `group_id` フィルターは Windsurf Teams の概念であり、Devin の認証情報ではサポートされていません —
  両方を組み合わせたリクエストは `400 Bad Request` を返します。
</Note>

<div id="windsurf-service-keys">
  ### Windsurf サービスキー
</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` をたどる場合) は、レート
制限には**カウントされません**。カウント対象となるのは、各レポートの最初のクエリだけです。この低い制限は、これらのエンドポイントが
リアルタイム監視ではなく、定期的なレポート作成向けであることを反映しています。