Session-Budgets

Ein Session-Budget ist eine optionale harte Ausgabenobergrenze, die du beim Erstellen einer Session festlegst. Die Plattform bepreist kontinuierlich alles, was die Session verbraucht, zu öffentlichen Listenpreisen (die Listenkosten der Session) und stellt keine neuen Modellanfragen mehr, sobald diese Kosten das Budget erreichen. Die Anfrage, die gerade läuft, wenn die Obergrenze überschritten wird, wird noch abgeschlossen, sodass die endgültigen Listenkosten geringfügig über dem Budget liegen können. Eine Session, die ihr Budget erreicht hat, pausiert und wechselt in den Zustand idle, anstatt beendet zu werden; das Ändern oder Entfernen des Budgets setzt ihre Arbeit automatisch fort. Deployments akzeptieren dasselbe Budget und wenden es auf jede Session an, die sie starten; siehe Budgets für Deployments.



Ein Budget bei der Session-Erstellung festlegen

Übergib das optionale Feld budget, wenn du die Session erstellst:

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")

Das budget-Objekt hat zwei Felder:

• type ist immer "limit".
• max_list_cost ist die Obergrenze selbst: amount ist eine ganze Zahl von US-Cents, geschrieben als String ohne führende Nullen ("2500" entspricht 25,00 $ und "50" entspricht 50 Cent) und muss größer als null sein. Dezimalformen wie "25.00" werden abgelehnt. Der Betrag ist ein String und keine Zahl, damit niemals Float-Rundungen darauf angewendet werden. currency ist ein ISO-4217-Währungscode in Großbuchstaben; USD ist die einzige unterstützte Währung.

Ein Budget kann nur beim Erstellen der Session angehängt werden. Das Hinzufügen eines Budgets zu einer bestehenden Session, die keines hat, wird mit einem 400-Fehler abgelehnt. Die Obergrenze einer Session mit Budget kann jederzeit geändert oder entfernt werden.



Wie Listenkosten gemessen werden

Die Plattform bepreist kontinuierlich, was die Session verbraucht, zu öffentlichen Listenpreisen:

• Modell-Tokens, zum Listenpreis des jeweils verwendeten Modells
• Websuchen, zu 10 $ pro 1.000 Suchen
• Session-Laufzeit, zu 0,08 $ pro Stunde

Diese laufende Dollar-Summe sind die Listenkosten der Session, und das ist der Wert, mit dem das Budget verglichen wird. Listenkosten sind nicht dein vertraglich vereinbarter Preis: Wenn deine Organisation Rabatte ausgehandelt hat, erreicht die Session ihre Obergrenze, wenn die Listenpreis-Summe sie erreicht, und deine abgerechneten Ausgaben können niedriger als die Obergrenze sein.

Die Durchsetzung verwendet die exakten, ungerundeten Listenkosten. Die list_cost-Werte, die für die Session und ihre Events gemeldet werden, sind ganze Cents, gerundet auf den nächsten Cent, sodass ein gemeldeter Wert bis zu einem halben Cent in beide Richtungen vom exakten Betrag abweichen kann, den die Durchsetzung verwendet.



Wenn eine Session ihr Budget erreicht

Die Obergrenze wird zwischen Modellanfragen durchgesetzt, nicht während einer Anfrage. Vor jeder Modellanfrage prüft die Plattform die verbrauchten Listenkosten der Session, und sobald diese Summe die Obergrenze erreicht, pausiert jeder Thread vor seiner nächsten Anfrage. Die Anfrage, die die Summe über die Obergrenze gebracht hat, wurde zugelassen, während die Session noch darunter lag, und läuft bis zum Abschluss, sodass die aufgezeichneten list_cost einer pausierten Session bei oder geringfügig über max_list_cost liegen: Eine Session mit einer Obergrenze von "50" (50 Cent) kann mit list_cost von "53" pausieren. Das ist erwartet und kein Abrechnungsfehler, und die Überschreitung ist auf eine Modellanfrage pro Thread begrenzt. Betrachte das Budget als Grenze für neue Arbeit und nicht als exakten Stopppunkt, und bemesse die Obergrenze mit diesem Spielraum von einer Anfrage im Hinterkopf.

Eine Session, die ihr Budget erreicht, wechselt in den Zustand idle mit einem stop_reason von budget_reached; sie wird nicht beendet, und ihr Verlauf und ihre Sandbox bleiben wie bei jeder anderen idle-Session erhalten. Im Event-Stream siehst du in dieser Reihenfolge:

1. Ein session.thread_status_idle-Event mit einem stop_reason von budget_reached, wenn jeder Thread pausiert.
2. Ein session.usage-Event mit der kumulativen Nutzung und den Listenkosten der Session.
3. Ein session.status_idle-Event mit einem stop_reason von budget_reached. Das Usage-Event geht diesem Idle-Event immer unmittelbar voraus.

Ein Thread, dessen letzte Anfrage sowohl die Obergrenze überschreitet als auch seinen Turn abschließt, meldet end_turn in seinem eigenen session.thread_status_idle-Event, während die Session weiterhin budget_reached meldet; betrachte den stop_reason auf Session-Ebene als das Signal dafür, dass die Session an ihrem Budget pausiert hat.



An der Obergrenze akzeptierte Events

Während die Session an oder über ihrem Budget ist, akzeptiert sie nur Events, die bereits laufende Arbeit abschließen:

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

Jedes Event, das neue Arbeit starten würde, wie user.message, wird mit einem 400-Fehler abgelehnt, der diese Liste nennt. Abgeschlossene Ergebnisse werden aufgezeichnet, ohne eine neue Modellanfrage auszulösen; die Session bleibt an ihrem Budget pausiert.

Ein user.interrupt, das gesendet wird, während die Session an ihrem Budget pausiert ist (alle Threads an der Obergrenze pausiert), wird akzeptiert und ignoriert: Es erscheint nicht in der Event-Liste und ändert nichts. Ändere oder entferne das Budget, um fortzufahren.



Eine Session an ihrem Budget fortsetzen

Ändere oder entferne das Budget mit einem Session-Update. Ein akzeptiertes Update setzt die pausierte Arbeit der Session automatisch fort; keine weitere Client-Aktion ist erforderlich.



Das Budget ändern

Aktualisiere die Session mit einem neuen max_list_cost. Der neue Wert kann höher oder niedriger als die aktuelle Obergrenze sein, muss aber strikt größer als die verbrauchten Listenkosten der Session sein; andernfalls wird das Update mit einem 400-Fehler abgelehnt: budget.max_list_cost must be greater than the session's consumed list cost. Da die verbrauchten Kosten normalerweise geringfügig über der alten Obergrenze liegen, wenn die Session pausiert, basiere den neuen Wert auf dem gemeldeten usage.list_cost der Session, nicht auf dem alten max_list_cost. Setze ihn einen Cent oder mehr über diesen Wert: Der gemeldete Wert ist gerundet und kann geringfügig unter den exakten verbrauchten Kosten liegen, die die Prüfung verwendet.

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



Das Budget entfernen

Setze budget auf null, um die Obergrenze vollständig zu entfernen. Die pausierte Arbeit der Session wird fortgesetzt, und das resultierende session.updated-Event enthält budget mit dem Wert null.

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



Ausgaben überwachen

Das Session-Objekt enthält sein budget und ein usage-Objekt mit den erfassten Ausgaben: usage.list_cost sind die verbrauchten Listenkosten der Session, und usage.active_seconds ist die Laufzeit, auf der die Laufzeitkosten basieren. Bei einer Session, die mit budget_reached pausiert ist, erwarte, dass usage.list_cost bei oder geringfügig über max_list_cost liegt: Die Anfrage, die die Obergrenze überschritten hat, wurde vor der Pause abgeschlossen. active_seconds auf Session-Ebene zählt überlappende Aktivität von gleichzeitigen Threads nur einmal. Thread-Abruf-Antworten enthalten dieselben zwei Felder im eigenen usage des Threads, pro Thread bepreist. Pro-Thread-Werte werden unabhängig gerundet und schließen die Laufzeitkosten der Session aus, sodass sie sich nicht exakt zu den list_cost der Session summieren; der Session-Wert ist derjenige, gegen den das Budget durchgesetzt wird.

Das session.usage-Event ist eine Momentaufnahme der kumulativen Nutzung und der erfassten Listenkosten der Session. Es enthält die Token-Summen der Session, list_cost, active_seconds, server_tool_use-Anfragezahlen (web_search_requests, pro Anfrage in die Listenkosten eingepreist, und web_fetch_requests, das 0 anzeigt, weil Web-Fetch-Anfragen keine Gebühr pro Anfrage tragen und nicht gemessen werden) und ein Echo des budget der Session, oder null, wenn die Session keines hat. Es erscheint in der Event-Liste und im Session-Stream. Die Session gibt eines unmittelbar bevor sie idle wird aus, unabhängig vom Stop-Grund, sodass eine Session, die ihr Budget erreicht, immer eines unmittelbar vor dem Budget-erreicht-Idle-Event ausgibt.

Zum Auslesen der Nutzung aus dem Stream und dem Session-Objekt siehe Nutzung verfolgen.



Budgets in Multiagent-Sessions

Eine Multiagent-Session hat ein einziges Budget, das über alle ihre Threads geteilt wird; es gibt keine Pro-Thread-Obergrenzen. Der Verbrauch jedes Threads wird zum jeweils verwendeten Modell bepreist, und Threads pausieren unabhängig voneinander, wenn die gemeinsame Obergrenze erreicht wird. Advisor-Konsultationen zählen gegen dasselbe Budget, bepreist zu den Raten des Advisor-Modells. Ein Thread kann mit budget_reached pausieren, während ein anderer seine laufende Anfrage abschließt.

Eine ausstehende Anfrage hat Vorrang vor der Obergrenze: Eine Session mit einem Thread, der auf requires_action wartet, und einem anderen, der mit budget_reached pausiert ist, meldet requires_action auf Session-Ebene. Die ausstehende Anfrage benötigt weiterhin eine Antwort, und das Beantworten ist ein Abschluss-Event, das das Budget nicht blockiert.



Budgets für Deployments

Ein Deployment akzeptiert dasselbe budget-Objekt, wenn du es erstellst oder aktualisierst:

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

Die Obergrenze wird auf jede Session kopiert, die das Deployment startet, sodass sie jeden Lauf separat begrenzt und nicht die kumulativen Ausgaben des Deployments. Das Ändern des Deployment-Budgets gilt für Sessions, die das Deployment danach startet, nicht für bereits laufende Sessions. Anders als bei einer Session kann das Budget eines Deployments mit null gelöscht und später wieder gesetzt werden. Siehe Ein Budget für jeden Lauf festlegen.



Modelle ohne Listenpreis

Ein Budget kann nur Verbrauch erfassen, den die Plattform bepreisen kann. Das Erstellen einer Session mit Budget, deren Agent oder irgendein Agent oder Advisor auf ihrer Multiagent-Liste ein Modell ohne öffentlichen Listenpreis verwendet, wird mit einem 400-Fehler abgelehnt, der besagt, dass für das Modell kein Listenpreis verfügbar ist.

Wenn die Nutzung einer Session mit Budget ein Modell ohne Listenpreis einschließt, kann das Budget die Ausgaben der Session nicht mehr messen: Die Session kann mit einem stop_reason von budget_reached pausieren, und das Ändern des Budgets wird abgelehnt. Entferne das Budget, um die Session fortzusetzen.



Fehlerreferenz

Budget-bezogene Anfragen werden in den folgenden Fällen abgelehnt: