ACU消費量 - Devin Docs

このドキュメントは、Devinの連邦政府向け導入環境向けです。Devinのドキュメントに戻る

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

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

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

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

リクエスト

string

必須

Analytics Read 権限を持つサービスキー。

string

RFC 3339 形式の履歴期間の開始時刻 (例: 2025-01-01T00:00:00Z) 。historical クエリでは必須で、current_cycle クエリでは省略する必要があります。

string

RFC 3339 形式の履歴期間の終了時刻。この期間は開始・終了時刻を含み、最大90日間まで指定できます。

object

必須

型付きのACU消費量クエリ。

表示 ACU消費量クエリオブジェクト

object

最上位の start_timestamp と end_timestamp で指定した履歴期間をクエリします。空のオブジェクトを渡します: "historical": {}。historical または current_cycle のいずれか一方を指定する必要があります。

object

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

boolean

チーム全体のACU合計を含めます。グループスコープのキーでは利用できません。

array

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

object

1つのスコープに対するユーザーごとのACU行をリクエストします。

表示ユーザースコープオブジェクト

object

チーム全体のユーザーごとの行。空のオブジェクトを渡します: "team": {}。グループスコープのキーでは利用できません。

string

1つのグループのユーザーごとの行。このグループは group_ids にも含める必要があります。

integer

1ページあたりのユーザー行数。1～1,000で指定でき、デフォルトは100です。

string

前のレスポンスの next_page_token で返されたトークン。ほかのすべてのクエリフィールドは変更しないでください。

レスポンス

object

表示 ACU消費量の結果

object

チーム全体の結果。include_team_total が設定されている場合は total_acus が含まれ、user_scope.team がリクエストされている場合は user_rows が設定されます。

array

リクエストされたグループごとに 1 つのエントリ。group_id、group_name、total_acus、user_rows が含まれます (user_rows は user_scope.group_id で選択されたグループに対して設定されます) 。

string

追加のユーザー行がある場合に含まれます。24 時間有効です。

object

period_start、period_end、generated_at、team_id、リクエストされた group_ids、チームの billing_mode。

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

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

動作

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

使用例

現在のサイクルにおけるTeam合計行とユーザー別行

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": {}}
    }
  }'

{
  "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"
    }
  }
}

グループ別の過去の内訳

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"}
    }
  }'

{
  "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"
    }
  }
}

​リクエスト

​レスポンス

​動作

​使用例

​現在のサイクルにおけるTeam合計行とユーザー別行

​グループ別の過去の内訳

リクエスト

レスポンス

動作

使用例

現在のサイクルにおけるTeam合計行とユーザー別行

グループ別の過去の内訳