Skip to main content
GET
エージェントのツール呼び出し分析を取得
これは v2 エンドポイントです。リクエストボディでサービスキーを渡す v1 の分析 API とは異なり、Bearer トークン認証とクエリパラメーターを利用します。詳しくは下記の認証を参照してください。
このエンドポイントはリアルタイムの使用量監視を目的としたものではありません。レート制限は低く設定されています (チームごとに 1 時間あたり 10 リクエスト) 。定期的なレポート作成や一括エクスポートに利用してください。

認証

このエンドポイントでは Bearer トークン 認証を利用します。Authorization ヘッダーにあなたのトークンを含めてください:
ローカル分析APIの使用 権限を持つDevinサービスユーザーのAPIキー、または アナリティクスの読み取り 権限を持つWindsurf サービスキーのいずれかを使用してください。それぞれの作成方法については、 認証を 参照してください。 v1 の cascade_tool_usage データソースとは異なり、このエンドポイントではDevinサービスユーザーのAPIキーを使用できます。そのため、Cognition プラットフォーム上のチームは Windsurf のサービスキーがなくてもツール使用状況を取得できます。

メトリクス

metric クエリパラメーターは必須で、現在は calls(エージェントが実行したツール呼び出しの回数)のみ指定できます。 この値は、各行に整数型の calls フィールドとして含まれます。metric を指定しないリクエスト、または 他のメトリクスを指定したリクエストは 400 エラーで失敗します。 ツール呼び出しは、モデルを問わず、エージェントが Devin Desktop または Devin CLI(他のエディター内でエージェントとして動作する CLI を含む)でツールを呼び出した時点でカウントされます。 product パラメーターも必須で、現在は agent のみ指定できます。

ツール

tool でグループ化すると、呼び出しをツールのカテゴリ別に集計できます。この場合、各行には次のいずれかの値を持つ tool フィールドが含まれます。 すべてのカテゴリがすべてのクライアントで使われるわけではありません。LIST_DIRECTORY、MEMORY、PROPOSE_CODE、 PROXY_WEB_SERVER、DEPLOY_WEB_APP、MQUERY は Devin Desktop のエージェントでのみ記録されます。また、 カテゴリがまだ割り当てられていない新しい Devin CLI のツールは OTHER として集計されます。

グループ化と時間粒度

granularity と group_by を利用して、返されるデータの構造を制御します。
  • 時間粒度もグループ化も指定しない場合 — 日付範囲全体を集計した 1 行を返します
  • granularity=daily — 各行に YYYY-MM-DD 形式の timestamp が含まれます
  • granularity=monthly — 各行に YYYY-MM 形式の timestamp が含まれます
  • group_by=tool — 各行に tool が含まれます (上記の ツール を参照)
  • group_by=user — 各行に user_id が含まれます。そのユーザーの user_email が記録されている場合は、それも含まれます
  • group_by=model_uid — 各行に model_uid が含まれます
  • group_by=ide — 各行に ide が含まれます
  • group_by=ide,ide_version — 各行に ide と ide_version が含まれます (ide_version でグループ化する場合は、ide も指定する必要があります)
  • group_by=os — 各行に os が含まれます (例:darwin (macOS) 、windows、linux)
ディメンションは組み合わせて指定できます。例えば group_by=user,tool では、各ユーザーが各 ツールを呼び出した回数を集計できます。Get Output の session および source ディメンションは ここではサポートされていません。 Get Consumption と同じ models、group_id、user_id フィルターを利用できるほか、カウント対象を 1 つのツールカテゴリに絞り込む tool フィルターも指定できます (例:tool=SEARCH_WEB) 。tool を 受け付けるのはこのエンドポイントのみです。他の Analytics API v2 エンドポイントに指定すると、400 エラーで失敗します。

例

ユーザーごとのウェブ検索回数を1週間分集計します:
各行は、ユーザー1人あたりの SEARCH_WEB の件数を表します。ユーザーごとにすべてのカテゴリを表示したい場合は、tool フィルターを外し、代わりに group_by=user,tool を追加してください。

ページネーション

結果はページ分割され、デフォルトのページサイズは 1,000 行(最大 10,000 行)です。さらに結果がある場合は、 レスポンスの pagination オブジェクトに next_page_cursor が含まれます。元のクエリパラメーターはそのままにして、この値を page_cursor クエリ パラメーターとして追加したリクエストを送信してください。カーソルは発行元のエンドポイントに紐付けられているため、/consumption や /output から取得したカーソルは 400 で拒否されます。 ページカーソルの有効期限は 24 時間です。後続ページのリクエストは、レート制限上の新しいクエリとしてはカウントされません。

レート制限

このエンドポイントのレート制限は、Team ごとに 1 時間あたり 10 リクエスト です。この制限を超えると、 サーバーは Retry-After ヘッダー付きで 429 Too Many Requests を返します。 以前のクエリのページング (next_page_cursor をたどる操作) は、この制限にカウントされません。 カウントされるのは、各レポートの最初のクエリのみです。制限値が低めに設定されているのは、このエンドポイントが リアルタイムの使用量監視ではなく、定期的なレポート作成向けであるためです。

承認

Authorization
string
header
必須

Authorization ヘッダーで Bearer トークンとして渡す、Analytics Read 権限を持つサービスキー。

サービスキーは、チーム設定 の「Service Keys」セクションで作成します。

クエリパラメータ

metric
string
必須

返すメトリクス。各行にフィールドとして含まれます。サポートされるメトリクス:

  • calls — エージェントが行ったツール呼び出し数
start_date
string<date>
必須

日付範囲の開始日(当日を含む)。YYYY-MM-DD 形式。

end_date
string<date>
必須

日付範囲の終了日(当日を含む)。YYYY-MM-DD 形式。範囲は90日以内である必要があります。

product
enum<string>
必須

ツール呼び出しをクエリする対象の製品。

利用可能なオプション:
agent
granularity
enum<string>

結果をグループ化する際の時間粒度。指定すると、各行に timestamp フィールドが含まれます。 省略すると、日付範囲全体で結果が集計されます。

利用可能なオプション:
daily,
monthly
group_by
string

結果のグループ化に利用するディメンションのカンマ区切りリスト。対応するディメンション:

  • tool — 各行にtool(SEARCH_WEBやRUN_COMMANDなどのツールカテゴリ)を含めます
  • user — 各行にuser_idを含めます。ユーザーのuser_emailが記録されている場合は、それも含めます
  • model_uid — 各行にmodel_uidを含めます
  • ide — 各行にideを含めます
  • ide_version — 各行にide_versionを含めます。ideも含める必要があります
  • os — 各行にosを含めます
models
string

結果の絞り込みに利用するモデルUIDのカンマ区切りリスト。

tool
string

集計対象をSEARCH_WEBやRUN_COMMANDなどの単一のツールカテゴリに限定します(完全一致)。 このエンドポイントでのみ指定できます。

group_id
string

結果を特定のグループに属するユーザーに絞り込みます。サービスキーには、このグループへのアクセス権が必要です。DevinサービスユーザーのAPIキーでは利用できません。

user_id
string

結果を特定のユーザー(認証UID)に絞り込みます。

page_size
integer
デフォルト:1000

1ページあたりに返す最大行数。

必須範囲: 1 <= x <= 10000
page_cursor
string

次のページを取得するための不透明なカーソル。前の応答のpagination.next_page_cursorから取得します。カーソルを発行したリクエストと同じmetricを渡してください。他のエンドポイントで発行されたカーソルは拒否されます。

レスポンス

ツール呼び出しデータが正常に返されました。

data
object[]
必須

ツール呼び出しのデータ行の配列。

pagination
object
必須
metadata
object
必須