Skip to main content
制御と可観測性

コストと使用量

Qoder Agent SDK は Credits 使用量データを公開します。Credits は Qoder のリソース使用量を表す単位です。このガイドでは、アカウントクォータ、リクエスト単位の Credits、現在のセッションの累計 Credits を取得する方法を説明します。 Credits の製品ルール、クォータの種類、消費順序については、Credits を参照してください。

現在のコンテキスト使用量を確認する

getContextUsage() / get_context_usage() を使用すると、新しい Agent ターンを開始せずに現在のコンテキストスナップショットを取得できます。SDK は実行中の CLI にこのスナップショットを要求し、SDK 側で使用量を再計算しません。レスポンスには、全体の使用率、CLI の /context ビューに表示されるカテゴリ別推定値、自動コンパクションの状態、重複ファイル読み取り、セッション統計、表示可能な skills が含まれます。 
const usage = await q.getContextUsage();

console.log(`Context used: ${usage.contextWindow.usedPercentage}%`);
for (const skill of usage.skills.items) {
  console.log(`${skill.name}: ${skill.percentageOfContext}% of context`);
}
すべてのパーセンテージフィールドは 0–100 の範囲です。各 skill の percentageOfContext はコンテキストウィンドウ全体を分母とします。そのため、各 skill の割合を全 skills の合計に対して表示する CLI の Skills タブとは異なります。 カテゴリ値はローカル推定であり、その合計が全体の使用率と完全に一致するとは限りません。全体の使用率は contextWindow.usedPercentage で確認し、カテゴリと skill の内訳はそれぞれの割合フィールドで確認できます。

Credits 使用量を確認する

確認する範囲に応じて、SDK はアカウントクォータ、個別のモデルリクエスト、現在のセッション累計という 3 種類の Credits 使用量を提供します。
確認する内容TypeScriptPythonデータ範囲
アカウントクォータと現在のセッション使用量q.getUsageInfo()client.get_usage_info()アカウントと現在の CLI セッションのリアルタイムスナップショット
個別のモデルリクエスト使用量message.message.usagemessage.usage完了した 1 回のモデルリクエスト
現在のセッション累計result.total_credits、result.modelUsageresult.total_credits、result.model_usage現在の CLI セッション開始時から Result メッセージまでの累計値
Agent タスクの終了を待たずにアプリケーションコードから現在のクォータだけを取得する場合は、getUsageInfo() / get_usage_info() を使用します。各モデルリクエストを記録する場合や、セッション終了時に使用量を集計する場合は、メッセージストリームから読み取ります。 TypeScript では、2 か所のセッション統計で命名規則が異なります。getUsageInfo().session は total_credits と model_usage を使用し、Result メッセージは total_credits と modelUsage を使用します。Python はどちらも snake_case です。

Credits 使用量を個別に取得する

getUsageInfo() / get_usage_info() はアカウントのクォータ情報を返します。取得可能な場合は、session に現在の CLI セッションの累計 Credits も含まれます。 
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

let releaseInput: (() => void) | undefined;

// Keep the CLI session alive without starting an Agent turn.
async function* noPrompt() {
  await new Promise<void>((resolve) => {
    releaseInput = resolve;
  });
}

const q = query({
  prompt: noPrompt(),
  options: {
    auth: accessTokenFromEnv(),
  },
});

try {
  await q.initializationResult();

  const usage = await q.getUsageInfo();
  if (usage === null) {
    console.log('Usage is unavailable.');
  } else {
    console.log('Plan:', usage.userType);
    console.log('Overall usage:', usage.totalUsagePercentage);
    console.log('Plan Credits remaining:', usage.userQuota?.remaining);

    if (usage.session) {
      console.log('Session Credits:', usage.session.total_credits);
      for (const [model, modelUsage] of Object.entries(
        usage.session.model_usage,
      )) {
        console.log(model, modelUsage.credits);
      }
    }
  }
} finally {
  releaseInput?.();
  await q.close();
}
主なレスポンスフィールドは次のとおりです。
フィールド説明
userQuota現在のプランに含まれるクォータ。total、used、remaining、percentage、unit を含みます
addOnQuota追加購入したクォータ。追加クォータがないアカウントでは省略される場合があります。detailUrl がある場合は使用量詳細ページを示します
orgResourcePackage組織で共有するリソースパッケージ。総クォータを cap で表し、used、remaining、percentage、available、unit を提供します
totalUsagePercentageアカウントで利用可能なすべてのクォータを合計した使用率
isQuotaExceededアカウントで利用可能なクォータを使い切ったかどうか
session.total_credits現在の CLI セッションの累計 Credits
session.model_usage現在のセッションでモデルごとに集計した Credits
アカウントのクォータ情報と session は独立したデータです。アカウントクォータのサービスが一時的に利用できない場合でも、SDK は session だけを含むオブジェクトを返すことがあります。そのため、userId や userQuota の有無でセッション使用量が利用可能かどうかを判断しないでください。 null / None が返された場合は、このリクエストでアカウントクォータとセッション Credits のどちらも取得できなかったことを示します。未認証や未対応の古い CLI バージョンに加えて、制御リクエストの失敗やサービスの一時的な停止でもこの結果になることがあります。 完全な API 定義については、SDK References を参照してください。

セッションメッセージから Credits を読み取る

メッセージストリームでは、リクエスト単位とセッション累計の両方の統計を取得できます。次の例では、以下を出力します。
  • Assistant メッセージに含まれる各モデルリクエストの Credits
  • Result メッセージに含まれる現在のセッションの累計 Credits
  • Result メッセージに含まれるモデルごとの累計 Credits
1 つの Agent タスクで複数のモデルリクエストが発生することがあるため、ストリームにはリクエスト単位の Credits を持つ Assistant メッセージが複数含まれる場合があります。現在のセッション合計だけが必要な場合は、Result メッセージの total_credits を使用し、リクエスト単位の credits を加算しないでください。 
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

for await (const message of query({
  prompt: 'Summarize this repository.',
  options: {
    auth: accessTokenFromEnv(),
  },
})) {
  if (message.type === 'assistant') {
    const usage = message.message.usage;

    if (typeof usage?.credits === 'number') {
      console.log('Request Credits:', usage.credits);
      console.log('Original Credits:', usage.original_credits);
      console.log('Billable:', usage.billable);
    }
  }

  if (message.type === 'result') {
    if (typeof message.total_credits === 'number') {
      console.log('Session Credits:', message.total_credits);
    }

    for (const [model, modelUsage] of Object.entries(message.modelUsage)) {
      if (typeof modelUsage.credits === 'number') {
        console.log(model, modelUsage.credits);
      }
    }
  }
}

フィールドの意味

フィールド集計範囲説明
credits個別のモデルリクエストキャンペーンや割引の適用後の Credits
original_credits個別のモデルリクエストキャンペーンや割引の適用前の Credits。データがない場合は省略されます
billable個別のモデルリクエストこのリクエストをユーザーの Credits 使用量に加算するかどうか
total_credits現在のセッション累計現在の CLI セッション開始時から累計した Credits
TypeScript modelUsage[model].credits現在のセッション累計指定したモデルが現在のセッションで使用した累計 Credits
Python model_usage[model]["credits"]現在のセッション累計指定したモデルが現在のセッションで使用した累計 Credits
注意: Result メッセージの usage フィールドからリクエスト単位の Credits を読み取らないでください。credits、original_credits、billable は Assistant メッセージから、セッション累計の Credits は total_credits またはモデルごとの統計から読み取ってください。

互換性

  • Credits 関連フィールドは、古い CLI バージョンとの互換性のためにオプションです。読み取り前にフィールドの有無を確認し、欠損値を 0 として扱わないでください。
  • total_credits はセッションの累計値です。複数の Result メッセージに含まれる値を加算すると、重複して集計される可能性があります。
  • リクエスト単位の credits と Result メッセージのセッション累計 Credits は、同じ消費を異なる範囲で集計したものです。両者を加算しないでください。
  • アカウントの残りクォータを表示する場合は、セッションメッセージを加算して推計するのではなく、getUsageInfo() / get_usage_info() が返すクォータ情報を使用してください。

次のステップ

  • Credits — Credits の種類、消費順序、使用量の確認方法
  • SDK References — メッセージと制御 API の完全な定義
クイックスタート
基本概念
会話とセッション
拡張機能
制御と可観測性
リファレンス