Skip to main content
Usage

Template 別 Usage 照会

正時で区切った指定期間内のアクティブな Session 数、アクティブな Identity 数、累積アクティブ時間、Credit を Template 別に集計します。

GET /api/v1/forward/usage/templates 正時で区切った指定期間内のアクティブな Session 数、アクティブな Identity 数、累積アクティブ時間、Credit を Template 別に集計します。
旧パラメータのサポート終了について 新版の API が利用可能になりました。start_at と end_at を使用し、正時で区切った期間の使用量を照会してください。旧タイムスタンプパラメータ start_time、end_time（Unix ミリ秒タイムスタンプ）と、Session の作成時刻に基づく旧集計ロジックは、2026 年 10 月 18 日（北京時間）にサポートを終了します。それまでの期間は互換期間です。サポート終了までに移行を完了してください。 互換期間中、旧タイムスタンプパラメータのみを使用するリクエストは従来の動作を維持し、時間フィールドも duration_seconds（整数の秒数）のままです。正時で区切った期間を指定する新しいリクエストでは、代わりに active_seconds（秒単位の数値、小数点以下の桁数は固定されません）を使用し、duration_seconds は返されません。新旧のパラメータを混在させると HTTP 400 が返されます。サポート終了後、旧タイムスタンプを使用するリクエストはサポートされず、新しいパラメータを使用するリクエストに自動変換されることもありません。エンドポイント URL は変更されません。

ヘッダー

Header必須説明
AuthorizationはいBearer <PAT または管理者 SAT>。Identity に紐付けられた SAT はサポートされません。
通常の PAT は、現在のユーザー個人の使用量を照会します。管理者 SAT は、その SAT に紐付けられた組織とワークスペースの使用量を照会します。

クエリパラメータ

中国版とグローバル版のどちらも北京時間（Asia/Shanghai、UTC+08:00）を使用します。開始時刻と終了時刻には正時（毎時 00 分 00 秒）のみ指定でき、形式は YYYY-MM-DDTHH:00:00 です。
パラメータ型必須デフォルト説明
start_atstringはい—クエリ開始時刻。この時刻を含みます。指定できるのは 1 回のみです。
end_atstringはい—クエリ終了時刻。この時刻を含みません。開始時刻より後で、期間は最大 744 時間です。指定できるのは 1 回のみです。北京時間でリクエストした日付の翌日 00:00:00 を超えることはできません。計算が完了していない時間帯は結果に含まれません。
limitintegerいいえ201 ページあたりのグループ数。範囲は 1～100 です。各ページネーションパラメータは 1 回のみ指定できます。
after_idstringいいえ—次のページに進むためのカーソル。前のページの last_id を指定します。before_id と同時には指定できません。
before_idstringいいえ—現在のページの first_id を指定して前のページに戻ります。after_id と同時には指定できません。
identity_idstringいいえ—1 つの Identity でフィルタリングします。
identity_idsstring/string[]いいえ—複数の Identity でフィルタリングします。カンマ区切り、または同じクエリパラメータの繰り返し指定をサポートします。
template_idstringいいえ—1 つの Template でフィルタリングします。
template_idsstring/string[]いいえ—複数の Template でフィルタリングします。カンマ区切り、または同じクエリパラメータの繰り返し指定をサポートします。
期間は [start_at, end_at) で、開始時刻を含み、終了時刻を含みません。例えば、2026-09-14T09:00:00 → 2026-09-14T12:00:00 は、09:00–10:00、10:00–11:00、11:00–12:00 の 3 時間を対象とします。期間は日付をまたぐことができますが、開始時刻と終了時刻はどちらも正時で、異なる時刻である必要があります。API は期間全体をグループ別に集計して返し、1 時間ごとには分割して返しません。

リクエスト例

2026 年 9 月 14 日の 09:00 から 12:00（北京時間、計 3 時間）の使用量を、2 つの Template と 2 つの Identity でフィルタリングし、Template 別に集計します。例の ID は実際のリソース ID に置き換えてください。 
curl -sS --get 'https://api.qoder.com/api/v1/forward/usage/templates' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  --data-urlencode 'start_at=2026-09-14T09:00:00' \
  --data-urlencode 'end_at=2026-09-14T12:00:00' \
  --data-urlencode 'template_ids=tmpl_123,tmpl_456' \
  --data-urlencode 'identity_ids=idn_abc,idn_efg'
複数の ID はカンマで区切るか、同名のクエリパラメータを繰り返し指定してください。角括弧や JSON 配列は使用しないでください。同じ種類の ID 間は OR、2 種類のフィルタ条件間は AND で結合されます。現在の認証情報の権限とクエリ期間の範囲内で、Template が tmpl_123 または tmpl_456 のいずれかであり、かつ Identity が idn_abc または idn_efg のいずれかであるレコードのみを集計します。

レスポンス例

HTTP 200 OK 以下の値はレスポンス構造を示すための例です。2 つの Template の両方に一致するレコードがあると仮定しています。 
{
  "type": "template_usage.list",
  "start_at": "2026-09-14T09:00:00",
  "end_at": "2026-09-14T12:00:00",
  "has_more": false,
  "first_id": "tmpl_123",
  "last_id": "tmpl_456",
  "data": [
    {
      "type": "template_usage",
      "template_id": "tmpl_123",
      "active_identities": 2,
      "session_count": 3,
      "active_seconds": 900.321,
      "credits": 3.45
    },
    {
      "type": "template_usage",
      "template_id": "tmpl_456",
      "active_identities": 2,
      "session_count": 2,
      "active_seconds": 300.123,
      "credits": 1.23
    }
  ]
}
フィルタリング後に Template 別に集計し、各結果の template_id は文字列で返されます。例えば、tmpl_123 の行は、上記 2 つの Identity の一致するレコードのみを集計します。active_identities も、これらの Identity のうち実際に一致するレコードがあるものを重複排除した数です。Template と Identity の 4 通りの組み合わせごとに結果が返されるわけではありません。グループは返される credits の降順で並び、Credit が同じ場合は ID の昇順で並びます。その後、limit に従ってページ分割されます。 一致するレコードがない Template のグループは返されず、ゼロで埋められることもありません。一致するレコードがまったくない場合は、data: []、has_more: false が返され、first_id と last_id はどちらも null になります。既存のグループで未収集の Credit は 0 として扱われます。

レスポンスフィールド

フィールド型説明
typestring固定値 template_usage.list。
start_atstringリクエストされた開始時刻。形式は YYYY-MM-DDTHH:00:00 で、この時刻を含み、北京時間として解釈されます。
end_atstringリクエストされた終了時刻。形式は YYYY-MM-DDTHH:00:00 で、この時刻を含まず、北京時間として解釈されます。
has_moreboolean現在のページネーション方向に、さらに結果があるかどうか。初回クエリでは次のページに進む方向で判定します。
first_idstring/nullこのページの最初のグループの公開 ID。before_id に指定して前のページに戻れます。空のページでは null。
last_idstring/nullこのページの最後のグループの公開 ID。after_id に指定して次のページに進めます。空のページでは null。
dataarrayTemplate の使用量リスト。1 ページには最大 limit 個の一致するグループが返され、各グループはクエリ期間全体を集計します。
data[].typestring固定値 template_usage。
data[].template_idstringこの行の Template ID。
data[].active_identitiesintegerクエリ期間全体で、この Template 内にアクティビティがあった、空でない Identity ID の重複を除いた数。
data[].session_countintegerクエリ期間内にアクティビティがあった、このグループの Session の重複を除いた数。
data[].active_secondsnumberクエリ期間内の、このグループに属するすべてのセッションの累積アクティブ時間（秒）。ミリ秒を先に合計し、1000 で割って秒に換算します。小数点以下の桁数は固定されず、追加の四捨五入や切り捨ては行いません。時間がゼロの場合は 0 を返します。
data[].creditsnumberグループ内のモデル Credit と実行 Credit の合計。集計後に小数点以下 2 桁まで切り下げます。未収集の Credit は 0 として扱われます。

データ更新について

北京時間の毎時 05 分を過ぎてから、直前の 1 時間の使用量の計算を開始し、計算完了後に照会できるようになります。例えば、10:05 を過ぎてから [09:00, 10:00) の使用量の計算を開始します。結果には、指定期間内で計算が完了した時間帯のみが集計されます。計算が完了していない時間帯は含まれないため、後のクエリでは結果が更新される場合があります。データは 北京時間 2026-09-07 22:00:00 以降について完全に揃っています。

エラーコード

HTTPTypeCodeトリガー条件
400invalid_request_error—必須の時刻が未指定、空、または重複している、形式が不正、正時でない、開始時刻が終了時刻より前でない、期間が 744 時間を超える、終了時刻が北京時間でリクエストした日付の翌日午前 0 時を超える、または timezone、start_date、end_date が指定されている。
400invalid_request_error—旧タイムスタンプパラメータと、新しい正時区間パラメータが混在している。値が空でも、そのパラメータが指定されたとみなされます。
400invalid_request_error—新しい正時区間パラメータを使用するリクエストで、limit が不正または 1～100 の範囲外、ページネーションパラメータが重複、after_id と before_id の両方が指定されている、またはカーソルが 64 バイトを超える、有効な UTF-8 でない、制御文字を含む。
400invalid_request_error—互換期間中、旧タイムスタンプパラメータが従来の検証ルールを満たしていない。
401authentication_error—有効な認証情報がない、または有効期限が切れている。
403permission_error—現在の認証情報に API が要求する権限がない。
500api_error—サーバー側のクエリに失敗した。

関連

Identity 別 Usage 照会

セッション一覧

はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス