Docs›Budgets

Budgets

Harte Ausgabenlimits fuer Grepture-API-Keys und Labels. E-Mail-Alerts bei 50/80/100% und HTTP-402-Durchsetzung am Proxy, sobald ein Cap erreicht ist.

Ueberblick

Ein Budget ist eine Ausgabenregel mit Scope, Zeitfenster und Limit. Der Proxy verfolgt, wie viel dieser Scope in der aktuellen Periode ausgibt, und lehnt neue passende Requests mit HTTP 402 Payment Required ab, sobald das Limit erreicht ist. E-Mail-Alerts feuern bei 50%, 80% und 100% des Limits.

Budgets finden Sie unter Guardrails → Budgets im Dashboard oder direkt unter /budgets.

Scope

Jedes Budget gehoert zu einem von zwei Scope-Typen:

Pro-Label-Budgets greifen nur bei Traffic, dessen Request den passenden Label-Header enthaelt. Traffic ohne Label oder mit nicht passendem Label wird vom Budget still ignoriert — keine impliziten Budget-Erstellungen.

Ein Label auf einem Request zu setzen ist nur ein Header:

POST /v1/messages
X-Grepture-Target: https://api.anthropic.com/v1/messages
X-Grepture-Label: feature:summarizer

Sie koennen mehrere Budgets gleichzeitig laufen lassen — einen Gesamt-Cap pro Key plus einzelne Caps pro Label. Der Proxy prueft jedes aktive Budget bei jedem Request; das erste, das aufgebraucht ist, gewinnt.

Zeitfenster

Zwei Zeitfenster stehen zur Verfuegung:

• +Monatlich — setzt sich um 00:00 UTC am 1. des Kalendermonats zurueck
• +Taeglich — setzt sich um 00:00 UTC zurueck

Jedes Budget hat genau ein Zeitfenster. Sie brauchen sowohl tageliche als auch monatliche Limits auf demselben Scope? Erstellen Sie zwei Budgets.

Ein Budget erstellen

1. +Gehen Sie zu Guardrails → Budgets im Dashboard
2. +Klicken Sie auf New budget
3. +Waehlen Sie einen Scope (API-Key oder Label)
4. +Waehlen Sie ein Zeitfenster (taeglich oder monatlich)
5. +Setzen Sie das Limit in Dollar
6. +Fuegen Sie Alert-E-Mail-Adressen hinzu (kommagetrennt)

Beim Erstellen eines Budgets zeigt das Formular Ihnen die bisherigen Periodenausgaben fuer den gewaehlten Scope. Das ist nur informativ — es sagt Ihnen, was bereits ausgegeben wurde, damit Sie den Cap passend dimensionieren koennen. Budgets zaehlen Ausgaben ab dem Moment der Erstellung, ein neues Budget startet also immer bei $0.00, unabhaengig davon, was vorher war.

Sie koennen ein Budget jederzeit deaktivieren, bearbeiten oder loeschen. Aenderungen werden innerhalb von 60 Sekunden wirksam (der Proxy cached aktive Budget-Definitionen fuer dieses Zeitfenster).

Die 402-Antwort

Wenn der Cap erreicht ist, gibt der Proxy HTTP 402 mit einem JSON-Body zurueck, der das Budget identifiziert:

{
  "error": "Budget exceeded",
  "budget_id": "1932f5fe-8235-4c45-9588-1371b3f9c27b",
  "scope": { "type": "label", "value": "feature:summarizer" },
  "limit_cents": 1000,
  "period": "monthly",
  "period_key": "2026-05"
}

Die Antwort enthaelt zudem den Header X-Grepture-Budget-Status: exceeded, damit Client-SDKs Budget-Ablehnungen erkennen koennen, ohne den Body zu parsen.

Sobald die Periode umschlaegt, setzt sich das Budget zurueck und der Proxy nimmt Requests automatisch wieder an. Kein Eingriff noetig.

Alerts

Ein App-Layer-Cron laeuft alle fuenf Minuten. Fuer jedes aktive Budget berechnet er die aktuellen Periodenausgaben aus Ihren Traffic-Logs (unter Beruecksichtigung von team-spezifischen Preis-Overrides, die unter Settings → Models gesetzt sind, sowie provider-spezifischer Caching-Discounts wie Anthropic-Cache-Reads zu 10%). Wenn der Prozentsatz zum ersten Mal in der aktuellen Periode 50%, 80% oder 100% ueberschreitet, geht eine E-Mail an die am Budget hinterlegten Adressen.

Jede Schwelle feuert einmal pro Periode. Das Dedupe liegt auf Datenbankebene — ein Primaerschluessel (budget_id, period_key, threshold) — also koennen erneute Cron-Laeufe, Wiederholungen oder transiente Fehler keine Duplikat-E-Mails produzieren.

Wenn die Periode umschlaegt, setzen sich die Schwellen-Zaehler zusammen mit dem Budget zurueck.

Vorerst nur E-Mail. Slack und Webhook-Kanaele stehen auf der Roadmap.

Wie die Durchsetzung funktioniert

Zwei Details lohnen sich zu kennen, wie der Proxy entscheidet, ob ein Request durchgelassen wird:

Eventually consistent. Der Proxy haelt die laufenden Periodenausgaben in Redis als Micro-Cent-Zaehler. Bei jedem Request liest er den Zaehler, vergleicht mit dem Limit und laesst entweder durch oder lehnt ab. Nach einem erfolgreichen Forward inkrementiert er den Zaehler um die tatsaechlichen Kosten des Requests.

Das bedeutet: Gleichzeitige Requests, die genau in dem Moment in Flight sind, in dem der Cap erreicht wird, koennen die Periodensumme leicht ueber das Limit treiben. Der Overshoot ist begrenzt durch gleichzeitige_requests × max_einzel_request_kosten. Bei typischen Workloads sind das hoechstens ein paar Dollar — deutlich guenstiger als die Latenz, die strikte Serialisierung bei jedem Request kosten wuerde.

Fail-open bei Redis-Ausfall. Wenn der Proxy Redis nicht erreichen kann, setzen Budgets aus und Traffic fliesst weiter. Das entspricht dem Verhalten der bestehenden Rate-Limit- und Quota-Systeme. Alerts funktionieren beim naechsten Cron-Tick weiter, weil sie aus der Datenbank lesen, nicht aus Redis.

Zaehlt ab Erstellung. Budgets zaehlen Ausgaben ab dem Moment der Erstellung, nicht ab Beginn der Kalenderperiode. Wenn Sie am 15. eines Monats einen $5-Monatscap erstellen, verfolgt das Budget, was ab dem 15. ausgegeben wird — nicht was vorher im Monat passiert ist. Beim Periodenwechsel entfaellt dieses Clipping und das Budget verfolgt die volle neue Periode wie erwartet.

Kostengenauigkeit

Die einem Budget pro Request zugefuegten Kosten werden aus den vom Upstream-Provider gemeldeten Token-Counts berechnet:

• +OpenAI — prompt_tokens und completion_tokens, wobei prompt_tokens_details.cached_tokens zu 50% des Input-Tarifs abgerechnet wird.
• +Anthropic — input_tokens zum regulaeren Input-Tarif, cache_read_input_tokens zu 10% des Input, cache_creation_input_tokens zu 125% des Input, output_tokens zum Output-Tarif.
• +Gemini — promptTokenCount, candidatesTokenCount und cachedContentTokenCount zum verguenstigten Cache-Tarif.

Team-spezifische Preis-Overrides, die unter Settings → Models gesetzt sind, werden vom Alert-Cron beruecksichtigt — wenn Sie also individuelle Tarife mit einem Provider ausgehandelt haben, spiegeln Alerts und Dashboard-Ausgaben diese wider.

Beispiele

Ein typisches Setup fuer ein SaaS-Produkt:

• +Account-weites Sicherheitsnetz — Pro-Key, $2.000/Monat, Alerts an Oncall und Finance. Faengt alles ab, was irgendwo seltsam laeuft.
• +Pro-Feature-Cap — Pro-Label feature:onboarding-chat, $400/Monat, Alerts an die Product-Ownerin. Damit das Team sieht, wenn das Feature heiss laeuft.
• +Pro-Experiment-Cap — Pro-Label feature:experimental, $50/Tag, Alerts an den Ingenieur, der es betreibt. Guenstige Versicherung gegen Endlosschleifen waehrend der Entwicklung.

Die drei Budgets stoeren sich nicht gegenseitig. Ein Request wird gegen jedes passende Budget geprueft; das strengste gewinnt.

Verwandt

• +Konfiguration — Proxy-Setup, X-Grepture-Label und andere Header
• +Dashboard — Traffic-Logs, Analytics und woher die Ausgabenzahlen kommen