> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ACU消費量

> 履歴期間または現在の請求サイクルにおける、チーム、グループ、ユーザーごとのACU消費量をクエリします。

<Info>
  このドキュメントは、Devinの連邦政府向け導入環境向けです。[Devinのドキュメントに戻る](/ja/get-started/devin-intro)
</Info>

Analyticsエンドポイントに対して型付きリクエストを送信し、ACU消費量をクエリします。レスポンスには、チーム全体の合計、選択した最大100件のグループごとの合計、およびチーム全体または1つのグループを対象とした、ページネーションされたユーザーごとの行を含めることができます。

```
POST https://<your-server>/api/v1/Analytics
```

**Analytics Read** 権限と、analytics API にアクセス可能なチームティアが必要です。認証、ページネーション、エラーの詳細については [API 概要](/ja/federal/api/overview) を、消費量と適用の関係については [ACU の上限](/ja/federal/acu-limits) を参照してください。

<Note>
  リクエストには、ここで説明する型付きの `acu_consumption_query` またはレガシーのカスタム `query_requests` のいずれか一方を含めることができますが、両方を含めることはできません。
</Note>

***

<div id="request">
  ## リクエスト
</div>

<ParamField body="service_key" type="string" required>
  Analytics Read 権限を持つサービスキー。
</ParamField>

<ParamField body="start_timestamp" type="string">
  RFC 3339 形式の履歴期間の開始時刻 (例: `2025-01-01T00:00:00Z`) 。`historical` クエリでは必須で、`current_cycle` クエリでは省略する必要があります。
</ParamField>

<ParamField body="end_timestamp" type="string">
  RFC 3339 形式の履歴期間の終了時刻。この期間は開始・終了時刻を含み、最大90日間まで指定できます。
</ParamField>

<ParamField body="acu_consumption_query" type="object" required>
  型付きのACU消費量クエリ。

  <Expandable title="ACU消費量クエリオブジェクト">
    <ParamField body="historical" type="object">
      最上位の `start_timestamp` と `end_timestamp` で指定した履歴期間をクエリします。空のオブジェクトを渡します: `"historical": {}`。`historical` または `current_cycle` のいずれか一方を指定する必要があります。
    </ParamField>

    <ParamField body="current_cycle" type="object">
      現在の請求サイクルの使用量をほぼリアルタイムでクエリします。空のオブジェクトを渡します: `"current_cycle": {}`。最上位のタイムスタンプは省略する必要があります。
    </ParamField>

    <ParamField body="include_team_total" type="boolean">
      チーム全体のACU合計を含めます。グループスコープのキーでは利用できません。
    </ParamField>

    <ParamField body="group_ids" type="array">
      グループごとの合計に含めるグループIDを最大100件指定します。不明なグループ、別チームのグループ、またはスコープ外のグループは `not_found` を返します。グループスコープのサービスキーでは、割り当てられたグループのみリクエストできます。
    </ParamField>

    <ParamField body="user_scope" type="object">
      1つのスコープに対するユーザーごとのACU行をリクエストします。

      <Expandable title="ユーザースコープオブジェクト">
        <ParamField body="team" type="object">
          チーム全体のユーザーごとの行。空のオブジェクトを渡します: `"team": {}`。グループスコープのキーでは利用できません。
        </ParamField>

        <ParamField body="group_id" type="string">
          1つのグループのユーザーごとの行。このグループは `group_ids` にも含める必要があります。
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="page_size" type="integer">
      1ページあたりのユーザー行数。1～1,000で指定でき、デフォルトは100です。
    </ParamField>

    <ParamField body="page_token" type="string">
      前のレスポンスの `next_page_token` で返されたトークン。ほかのすべてのクエリフィールドは変更しないでください。
    </ParamField>
  </Expandable>
</ParamField>

<div id="response">
  ## レスポンス
</div>

<ResponseField name="acu_consumption" type="object">
  <Expandable title="ACU消費量の結果">
    <ResponseField name="team" type="object">
      チーム全体の結果。`include_team_total` が設定されている場合は `total_acus` が含まれ、`user_scope.team` がリクエストされている場合は `user_rows` が設定されます。
    </ResponseField>

    <ResponseField name="groups" type="array">
      リクエストされたグループごとに 1 つのエントリ。`group_id`、`group_name`、`total_acus`、`user_rows` が含まれます (`user_rows` は `user_scope.group_id` で選択されたグループに対して設定されます) 。
    </ResponseField>

    <ResponseField name="next_page_token" type="string">
      追加のユーザー行がある場合に含まれます。24 時間有効です。
    </ResponseField>

    <ResponseField name="metadata" type="object">
      `period_start`、`period_end`、`generated_at`、`team_id`、リクエストされた `group_ids`、チームの `billing_mode`。
    </ResponseField>
  </Expandable>
</ResponseField>

各ユーザー行には次の項目が含まれます。

| フィールド            | 説明                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------ |
| `user_id`        | 変更されない、シークレットではないユーザー ID。                                                            |
| `email`          | 解決できる場合のユーザーのメールアドレス。                                                                |
| `current_member` | ユーザーが現在チームのアクティブなメンバーかどうか。グループスコープの行は現在のグループメンバーシップから選択されますが、このフラグはチームのメンバーシップを示します。 |
| `total_acus`     | 対象期間中にユーザーが消費した ACU。                                                                 |

<div id="behavior">
  ## 動作
</div>

* **グループへの割り当てには現在のメンバーシップが使用されます。** グループの合計値とユーザー行には、期間中にグループに所属していたユーザーではなく、現在グループに所属しているユーザーが反映されます。リクエスト対象の複数のグループに所属するユーザーは、それぞれのグループでカウントされます。
* **チーム行には以前のユーザーも含まれます。** チームスコープのユーザー行には、その後チームを離れたユーザーや解決できなかったユーザーも含まれます。これらのユーザーの `current_member` フラグは `false` です。
* **ACU使用量があるユーザーのみ表示されます。** 期間中にACU消費量がないユーザーは、ユーザー行には表示されません。
* **履歴と現在のサイクル。** 履歴期間には、記録済みの使用量のうち最大90日分 (両端を含む) が含まれます。`current_cycle` は、アクティブな請求サイクルのほぼリアルタイムの使用量を返します。チームにアクティブなサイクル境界がない場合、メタデータの期間フィールドにもその状態が反映されます。
* **整合性。** 1つのレスポンス内の合計値とユーザー行ページは、同一の一貫したスナップショットから計算されます。

<div id="examples">
  ## 使用例
</div>

<div id="team-total-and-per-user-rows-for-the-current-cycle">
  ### 現在のサイクルにおけるTeam合計行とユーザー別行
</div>

```bash theme={null}
curl -X POST https://<your-server>/api/v1/Analytics \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "acu_consumption_query": {
      "current_cycle": {},
      "include_team_total": true,
      "user_scope": {"team": {}}
    }
  }'
```

```json theme={null}
{
  "acuConsumption": {
    "team": {
      "totalAcus": 1240.5,
      "userRows": [
        {"userId": "user_abc", "email": "dev@agency.gov", "currentMember": true, "totalAcus": 310.2}
      ]
    },
    "nextPageToken": "…",
    "metadata": {
      "periodStart": "2025-03-01T00:00:00Z",
      "periodEnd": "2025-03-14T18:22:05Z",
      "generatedAt": "2025-03-14T18:22:05Z",
      "teamId": "team_123",
      "billingMode": "ACU_CREDIT"
    }
  }
}
```

<div id="historical-per-group-breakdown">
  ### グループ別の過去の内訳
</div>

```bash theme={null}
curl -X POST https://<your-server>/api/v1/Analytics \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "start_timestamp": "2025-01-01T00:00:00Z",
    "end_timestamp": "2025-03-31T23:59:59Z",
    "acu_consumption_query": {
      "historical": {},
      "group_ids": ["group_a", "group_b"],
      "user_scope": {"group_id": "group_a"}
    }
  }'
```

```json theme={null}
{
  "acuConsumption": {
    "groups": [
      {
        "groupId": "group_a",
        "groupName": "Engineering",
        "totalAcus": 512.0,
        "userRows": [
          {"userId": "user_abc", "email": "dev@agency.gov", "currentMember": true, "totalAcus": 96.4}
        ]
      },
      {"groupId": "group_b", "groupName": "Data Science", "totalAcus": 288.7}
    ],
    "metadata": {
      "periodStart": "2025-01-01T00:00:00Z",
      "periodEnd": "2025-03-31T23:59:59Z",
      "generatedAt": "2025-04-02T10:15:00Z",
      "teamId": "team_123",
      "groupIds": ["group_a", "group_b"],
      "billingMode": "ACU_CREDIT"
    }
  }
}
```