セッション予算

セッション予算は、セッションを作成する際に設定できるオプションの厳格な支出上限です。プラットフォームは、セッションが消費するすべてのものを公開定価（セッションのリストコスト）で継続的に計算し、そのコストが予算に達すると新しいモデルリクエストの発行を停止します。上限を超えた時点で処理中のリクエストは完了まで実行されるため、最終的なリストコストは予算をわずかに超えることがあります。予算に達したセッションは終了せず、一時停止してアイドル状態になります。予算を変更または削除すると、作業は自動的に再開されます。デプロイメントも同じ予算を受け入れ、開始する各セッションに適用します。詳細はデプロイメントの予算を参照してください。



セッション作成時に予算を設定する

セッションを作成する際に、オプションの budget フィールドを渡します。

session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

budget オブジェクトには2つのフィールドがあります。

• type は常に "limit" です。
• max_list_cost は上限そのものです。amount は米セント単位の整数を、先頭にゼロを付けない文字列として記述します（"2500" は $25.00、"50" は 50 セント）。ゼロより大きい値でなければなりません。"25.00" のような小数形式は拒否されます。浮動小数点の丸めが適用されないように、amount は数値ではなく文字列です。currency は大文字の ISO-4217 通貨コードで、サポートされている通貨は USD のみです。

予算はセッション作成時にのみ設定できます。予算を持たない既存のセッションに予算を追加しようとすると、400 エラーで拒否されます。予算が設定されたセッションの上限は、いつでも変更または削除できます。



リストコストの計測方法

プラットフォームは、セッションが消費するものを公開定価で継続的に計算します。

• モデルトークン：提供される各モデルの定価
• ウェブ検索：1,000 検索あたり $10
• セッション実行時間：1 時間あたり $0.08

この累積ドル合計がセッションのリストコストであり、予算はこれと比較されます。リストコストは契約価格ではありません。組織が割引を交渉している場合、セッションは定価の合計が上限に達した時点で上限に達しますが、請求される支出は上限より低くなる可能性があります。

適用には、丸められていない正確なリストコストが使用されます。セッションおよびそのイベントで報告される list_cost の数値は、最も近いセントに丸められた整数セントであるため、報告される数値は適用に使用される正確な金額から最大 0.5 セント前後する可能性があります。



セッションが予算に達したとき

上限はリクエストの途中ではなく、モデルリクエスト間で適用されます。各モデルリクエストの前に、プラットフォームはセッションの消費済みリストコストを確認し、その合計が上限に達すると、すべてのスレッドは次のリクエストの前に一時停止します。合計を上限超えに押し上げたリクエストは、セッションがまだ上限未満だったときに受け入れられたもので、完了まで実行されます。そのため、一時停止したセッションの記録された list_cost は max_list_cost と同じか、わずかに超えた値になります。たとえば、"50"（50 セント）で上限設定されたセッションは、list_cost が "53" で一時停止することがあります。これは想定された動作であり、請求エラーではありません。超過分はスレッドごとに 1 つのモデルリクエスト分に制限されます。予算は正確な停止点ではなく、新しい作業に対する上限として扱い、この 1 リクエスト分の余裕を考慮して上限を設定してください。

予算に達したセッションは、stop_reason が budget_reached でアイドル状態になります。終了はせず、他のアイドルセッションと同様に履歴とサンドボックスが保持されます。イベントストリームでは、次の順序で表示されます。

1. 各スレッドが一時停止すると、stop_reason が budget_reached の session.thread_status_idle イベント。
2. セッションの累積使用量とリストコストを含む session.usage イベント。
3. stop_reason が budget_reached の session.status_idle イベント。usage イベントは常にこのアイドルイベントの直前に発生します。

最後のリクエストが上限を超えると同時にターンを完了したスレッドは、自身の session.thread_status_idle イベントで end_turn を報告しますが、セッションは引き続き budget_reached を報告します。セッションが予算で一時停止したことを示すシグナルとしては、セッションレベルの stop_reason を使用してください。



上限到達時に受け入れられるイベント

セッションが予算以上の状態にある間は、すでに進行中の作業を完了させるイベントのみを受け入れます。

• user.tool_confirmation
• user.tool_result
• user.custom_tool_result
• user.interrupt

user.message など、新しい作業を開始するイベントは、このリストを示す 400 エラーで拒否されます。完了した結果は新しいモデルリクエストをトリガーすることなく記録され、セッションは予算で一時停止したままになります。

セッションが予算で一時停止している間（すべてのスレッドが上限で一時停止している状態）に送信された user.interrupt は受け入れられますが無視されます。イベントリストには表示されず、何も変更されません。続行するには予算を変更または削除してください。



予算に達したセッションを再開する

セッション更新で予算を変更または削除します。更新が受け入れられると、セッションの一時停止した作業は自動的に再開されます。クライアント側での追加操作は不要です。



予算を変更する

新しい max_list_cost でセッションを更新します。新しい値は現在の上限より高くても低くても構いませんが、セッションの消費済みリストコストより厳密に大きくなければなりません。そうでない場合、更新は 400 エラー budget.max_list_cost must be greater than the session's consumed list cost で拒否されます。セッションが一時停止したとき、消費済みコストは通常古い上限をわずかに超えているため、新しい値は古い max_list_cost ではなく、セッションの報告された usage.list_cost に基づいて設定してください。その数値より 1 セント以上高く設定してください。報告される値は丸められており、チェックに使用される正確な消費済みコストよりわずかに低い場合があります。

curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "4000", "currency": "USD"}
  }
}
EOF



予算を削除する

budget を null に設定すると、上限が完全に削除されます。セッションの一時停止した作業が再開され、結果として生成される session.updated イベントには null に設定された budget が含まれます。

curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"budget": null}'



支出を監視する

セッションオブジェクトには budget と、追跡された支出を含む usage オブジェクトが含まれます。usage.list_cost はセッションの消費済みリストコスト、usage.active_seconds はランタイムコストの計算対象となる実行時間です。budget_reached で一時停止したセッションでは、usage.list_cost が max_list_cost と同じか、わずかに超えた値になることが想定されます。上限を超えたリクエストは一時停止前に完了しているためです。セッションレベルの active_seconds は、並行スレッドの重複するアクティビティを 1 回としてカウントします。スレッド取得レスポンスには、スレッド自身の usage に同じ 2 つのフィールドが含まれ、スレッドごとに計算されます。スレッドごとの数値は独立して丸められ、セッションの実行時間コストを含まないため、合計してもセッションの list_cost と正確には一致しません。予算が適用されるのはセッションの数値です。

session.usage イベントは、セッションの累積使用量と追跡されたリストコストのスナップショットです。セッションのトークン合計、list_cost、active_seconds、server_tool_use リクエスト数（リクエストごとにリストコストに計上される web_search_requests と、ウェブフェッチリクエストにはリクエストごとの料金がなく計測されないため 0 と表示される web_fetch_requests）、およびセッションの budget のエコー（セッションに予算がない場合は null）が含まれます。これはイベントリストとセッションストリームに表示されます。セッションは、停止理由に関係なく、アイドル状態になる直前に必ず 1 つ発行するため、予算に達したセッションは常に budget-reached アイドルイベントの直前に 1 つ発行します。

ストリームとセッションオブジェクトから使用量を読み取る方法については、使用量の追跡を参照してください。



マルチエージェントセッションの予算

マルチエージェントセッションには、すべてのスレッドで共有される単一の予算があります。スレッドごとの上限はありません。各スレッドの消費は、それぞれの提供モデルで計算され、共有上限に達するとスレッドは独立して一時停止します。アドバイザーへの相談も同じ予算にカウントされ、アドバイザーモデルの料金で計算されます。あるスレッドが budget_reached で一時停止している間に、別のスレッドが処理中のリクエストを完了することがあります。

保留中の確認要求は上限より優先されます。あるスレッドが requires_action で待機し、別のスレッドが budget_reached で一時停止しているセッションは、セッションレベルで requires_action を報告します。保留中のリクエストには依然として応答が必要であり、それに応答することは予算がブロックしない完了イベントです。



デプロイメントの予算

デプロイメントは、作成または更新時に同じ budget オブジェクトを受け入れます。

{
  "budget": {
    "type": "limit",
    "max_list_cost": { "amount": "2000", "currency": "USD" }
  }
}

上限はデプロイメントが開始する各セッションにコピーされるため、デプロイメントの累積支出ではなく、各実行を個別に制限します。デプロイメントの予算を変更すると、その後にデプロイメントが開始するセッションに適用され、すでに実行中のセッションには適用されません。セッションとは異なり、デプロイメントの予算は null でクリアし、後で再設定できます。各実行に予算を設定するを参照してください。



定価のないモデル

予算は、プラットフォームが価格を計算できる消費のみを追跡できます。エージェント、またはマルチエージェントロスター上のいずれかのエージェントやアドバイザーが公開定価のないモデルを使用している場合、予算付きセッションの作成は、そのモデルに定価がないことを示す 400 エラーで拒否されます。

予算付きセッションの使用量に定価のないモデルが含まれるようになった場合、予算はセッションの支出を測定できなくなります。セッションは stop_reason が budget_reached で一時停止することがあり、予算の変更は拒否されます。セッションを再開するには予算を削除してください。



エラーリファレンス

予算関連のリクエストは、次の場合に拒否されます。