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

# アクティブユーザー数を取得

> 時間粒度やユーザーごとのグループ化を任意で指定して、チーム内の重複を除いたアクティブユーザー数をクエリします。

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

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

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

このエンドポイントでは **Bearer トークン** 認証を利用します。`Authorization` ヘッダーにサービスキーを含めてください。

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

サービスキーには **Analytics Read** 権限が必要です。[チーム設定](https://windsurf.com/team/settings)の「Service Keys」から作成してください。

<div id="what-counts-as-an-active-user">
  ## アクティブユーザーと見なされる条件
</div>

ある時間バケット内に課金イベントが1件でもある場合、そのユーザーはその時間バケットにおいて**アクティブ**としてカウントされます。`active_users`
フィールドには、重複のないユーザー数が記録されます。

<Note>
  アクティブユーザー数には、**Devin CLI と Devin Desktop の両方**の使用量が含まれます。いずれか一方
  (または両方) でアクティブなユーザーはカウントされ、時間バケットごとに1回だけ計上されます。
</Note>

<div id="grouping-and-granularity">
  ## グループ化と粒度
</div>

返されるデータの形式を制御するには、`granularity` と `group_by` を利用します。

* **粒度やグループ化の指定なし** — 指定した日付範囲全体におけるアクティブユーザーの合計数を 1 行で返します
* **`granularity=daily`** — 各行に `YYYY-MM-DD` 形式の `timestamp` が含まれます (デイリーアクティブユーザー)
* **`granularity=monthly`** — 各行に `YYYY-MM` 形式の `timestamp` が含まれます (マンスリーアクティブユーザー)
* **`group_by=user`** — アクティブユーザーごとに 1 行ずつ返し、各行に `user_id` が含まれます。各行の `active_users` は `1` です

<Note>
  [消費量を取得](/ja/desktop/accounts/api-reference/get-consumption) とは異なり、アクティブユーザー エンドポイントでは
  `group_by` に指定できるのは `user` のみです。その他のディメンション (`model_uid`、`ide`) はここでは無効です。
</Note>

<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/active-users
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/active-users:
    get:
      summary: アクティブユーザー分析を取得する
      description: >
        認証されたチームの重複しないアクティブユーザー数をクエリします。ユーザーは、ある時間バケット内に請求イベントが 1
        件でもあれば、その時間バケットでアクティブとしてカウントされます。結果は時間単位で集計された請求イベントに基づいており、日付範囲、product、model、group
        で絞り込めます。


        `granularity` を利用すると、日単位または月単位で件数を内訳表示できます。また、`group_by=user`
        を指定すると、ユーザーごとに 1 行を返します（各行の `active_users` は `1` になります）。


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


        これらのエンドポイントは、定期レポートや一括エクスポート向けに設計されています。リアルタイムの使用量監視を目的としたものでは**ありません**。データは時間単位で集計されており、レート制限も低く設定されています（チームごとに
        1 時間あたり 10 リクエスト）。
      operationId: getActiveUsers
      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
            enum:
              - user
          description: |
            結果をグループ化するディメンション。アクティブユーザー endpoint でサポートされているのは `user` のみで、この場合は
            アクティブユーザーごとに 1 行（各行の `active_users` = `1`）が返されます。
          example: user
        - 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 に属するユーザーに絞り込みます。サービスキーにはこの group へのアクセス権が必要です。
        - 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: 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 値。データが変更されていない場合、server は `304 Not Modified` を返します。
      responses:
        '200':
          description: アクティブユーザーデータが正常に返されました。
          headers:
            ETag:
              schema:
                type: string
              description: キャッシュ検証用のエンティティタグ。後続の request では、これを `If-None-Match` として渡します。
            Cache-Control:
              schema:
                type: string
              description: 'キャッシュディレクティブ（例: `private, max-age=3600`）。'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveUsersResponse'
              examples:
                aggregate:
                  summary: 期間内のアクティブユーザー総数
                  value:
                    data:
                      - active_users: 142
                    pagination:
                      next_page_cursor: null
                    metadata:
                      data_freshness: '2026-01-16T03:00:00.000Z'
                      query_time_ms: 612
                      team_id: team_abc123
                daily:
                  summary: 日次アクティブユーザー数
                  value:
                    data:
                      - timestamp: '2026-01-15T00:00:00.000Z'
                        active_users: 138
                      - timestamp: '2026-01-16T00:00:00.000Z'
                        active_users: 145
                    pagination:
                      next_page_cursor: null
                    metadata:
                      data_freshness: '2026-01-16T03:00:00.000Z'
                      query_time_ms: 734
                      team_id: team_abc123
                by_user:
                  summary: ユーザーごとにグループ化
                  value:
                    data:
                      - user_id: user_abc123
                        active_users: 1
                      - user_id: user_def456
                        active_users: 1
                    pagination:
                      next_page_cursor: null
                    metadata:
                      data_freshness: '2026-01-16T03:00:00.000Z'
                      query_time_ms: 845
                      team_id: team_abc123
        '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
                bad_group_by:
                  value:
                    error: 'unsupported group_by dimension for active-users: model_uid'
                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: 指定されたページカーソルは、認証済みの Team または要求された 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: >-
            レート制限を超えました（Team ごとに 1 時間あたり 10 request）。以前のクエリのページネーションは、この limit
            にはカウントされません。
          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:
    ActiveUsersResponse:
      type: object
      required:
        - data
        - pagination
        - metadata
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ActiveUsersRow'
          description: アクティブユーザーデータ行の配列。
        pagination:
          type: object
          properties:
            next_page_cursor:
              type:
                - string
                - 'null'
              description: |
                結果の次のページを取得するための不透明なカーソル。後続のリクエストで、この値を `page_cursor`
                クエリパラメータとして渡してください。以降のページがない場合は `null` です。
                ページカーソルは 24 時間で期限切れになります。
        metadata:
          type: object
          properties:
            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: 人が読んで理解できるエラーメッセージ。
    ActiveUsersRow:
      type: object
      required:
        - active_users
      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` が含まれる場合にのみ存在します。
        active_users:
          type: integer
          format: int64
          description: |
            この行内の一意のアクティブユーザー数。ある時間バケット内に請求イベントが1件でもあれば、
            そのユーザーはその時間バケットでアクティブとしてカウントされます。`user` でグループ化した場合、これは常に `1` です。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        `Authorization` ヘッダーで Bearer トークンとして渡す、**Analytics Read** 権限を持つサービスキー。


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

````