Billing-API

Rufen Sie Nutzungs- und Kostendaten Ihres eigenen Workspace in Ihre eigenen Systeme ab, ohne die Konsole zu öffnen. Ein Billing-Schlüssel ist ein nur lesender Anmeldedaten, beschränkt auf einen Workspace - er kann nur Abrechnungsdaten lesen, sonst nichts.

Einen Billing-Schlüssel erstellen

1. Öffnen Sie Konsole → Billing-API-Schlüssel (nur Workspace-Inhaber). Benennen Sie ihn, beschränken Sie ihn optional auf eine IP-Allowlist oder legen Sie ein Ablaufdatum fest, und kopieren Sie dann den Schlüssel - er beginnt mit sk-syn-bill- und wird nur einmal angezeigt.
2. Rufen Sie die untenstehenden Endpoints damit als Bearer-Token auf. Widerrufen Sie ihn jederzeit auf derselben Seite - der Widerruf macht ihn sofort ungültig, ohne sonst etwas im Workspace zu beeinflussen.
3. Ein Schlüssel ist an seinen Ersteller gebunden: Ist dieser nicht mehr Workspace-Inhaber, funktioniert er nicht mehr und liefert 403 key_owner_not_authorized.

Authentifizierung

Jeder Aufruf benötigt Authorization: Bearer sk-syn-bill-... gegen die untenstehende Basis-URL. Ein Billing-Schlüssel funktioniert nur auf diesen Endpoints, und diese Endpoints akzeptieren nur einen Billing-Schlüssel - jede andere Kombination liefert 401 wrong_key_kind.

Authorization: Bearer sk-syn-bill-...

Basis-URL: https://synthorai.io/api/v1/billing

GET /usage - aggregierte Nutzung

GET /usage

Voraggregierte Zeilen pro Stunde oder Tag - für Rechnungen und Dashboards. Sie stammen aus dem stündlichen Rollup, ergänzt um die seit dessen letztem Import geschriebenen Anfragen, sodass jüngste Buckets nicht einen ganzen Importzyklus hinterherhinken.

In jeder Zeile erscheinen api_key_id und api_key_name nur, wenn group_by api_key enthält, und model nur, wenn es model enthält. avg_latency_ms kann null sein, wenn ein Bucket keine Latenz-Stichproben hat.

Beispielanfrage

curl "https://synthorai.io/api/v1/billing/usage?start=2026-09-01&end=2026-09-24&granularity=day" \
  -H "Authorization: Bearer sk-syn-bill-..."

Beispielantwort

{
  "data": [
    {
      "bucket_start": "2026-09-23T00:00:00Z",
      "bucket_end": "2026-09-24T00:00:00Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "requests": 1280,
      "success_requests": 1265,
      "error_requests": 15,
      "errors_4xx": 12,
      "errors_429": 2,
      "errors_5xx": 1,
      "prompt_tokens": 512000,
      "completion_tokens": 98000,
      "cached_tokens": 210000,
      "cache_write_tokens": 8000,
      "reasoning_tokens": 4000,
      "cost_usd": 4.1732,
      "byok_list_price_usd": 0,
      "byok_requests": 0,
      "avg_latency_ms": 812,
      "final": true
    }
  ],
  "meta": {
    "generated_at": "2026-09-24T08:00:00Z",
    "data_complete_until": "2026-09-24T06:00:00Z",
    "timezone": "UTC",
    "currency": "USD",
    "next_cursor": null,
    "has_more": false
  }
}

GET /records - Zeilen pro Anfrage

GET /records

Eine Zeile pro Anfrage, gedacht für die inkrementelle Synchronisierung in Ihre eigene Datenbank. Synchronisieren Sie nach cursor, niemals nach Zeit, und entfernen Sie Duplikate eingehender Zeilen anhand von record_id - siehe unten "Zeitlücken vermeiden" für den Grund.

Beispielanfrage

curl "https://synthorai.io/api/v1/billing/records?start=2026-09-24T00:00:00Z&limit=500" \
  -H "Authorization: Bearer sk-syn-bill-..."

Beispielantwort

{
  "data": [
    {
      "record_id": "rec_8f2a91c4",
      "request_id": "req_9f3c2b1a",
      "recorded_at": "2026-09-24T05:58:31Z",
      "completed_at": "2026-09-24T05:58:29Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "status": "success",
      "status_code": 200,
      "prompt_tokens": 812,
      "completion_tokens": 194,
      "cached_tokens": 512,
      "cache_write_tokens": 64,
      "cache_write_5m_tokens": 64,
      "cache_write_1h_tokens": 0,
      "cost_usd": 0.00412,
      "byok_list_price_usd": 0,
      "is_byok": false,
      "is_stream": true,
      "duration_ms": 1340,
      "ttft_ms": 210
    }
  ],
  "meta": {
    "next_cursor": "eyJvIjoiODgxNDA5MCJ9",
    "has_more": false,
    "window_final": true,
    "safe_until": "2026-09-24T05:58:31Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "data_complete_until": "2026-09-24T05:58:00Z"
  }
}

GET /records/export - gestreamter Export

GET /records/export

Dieselben Filter wie /records, gestreamt als zeilenweise getrenntes JSON (application/x-ndjson) - für einen großen Rückstands-Abgleich statt einer paginierten Liste gedacht. Pro Workspace kann jeweils nur ein Export gestreamt werden; ein zweiter erhält 429 too_many_concurrent_requests.

Beispielanfrage

curl -N "https://synthorai.io/api/v1/billing/records/export?cursor=eyJvIjoiODgxNDAzMiJ9" \
  -H "Authorization: Bearer sk-syn-bill-..."

Beispielantwort

{"record_id":"rec_8f2a91c4","request_id":"req_9f3c2b1a","model":"claude-sonnet-5","status":"success","cost_usd":0.00412}
{"record_id":"rec_8f2a91c5","request_id":"req_9f3c2b1b","model":"claude-sonnet-5","status":"success","cost_usd":0.00398}
{"_meta":{"next_cursor":"eyJvIjoiODgxNDA5MSJ9","rows":2,"complete":true,"window_final":true,"generated_at":"2026-09-24T06:00:02Z"}}

Die letzte Zeile des Streams ist ein _meta Objekt:

GET /summary - vorläufige Statistiken und Anomalien

GET /summary

Summen, Top-Modelle und Top-Schlüssel nach Kosten sowie eine Fehlerrate für den Zeitraum, plus eine anomalies Liste (high_error_rate, rate_limited, data_not_final, rollup_delayed), jede mit einem Schweregrad info oder warning und einer für Menschen lesbaren Nachricht. Zahlen in einem noch nicht abgeschlossenen Zeitraum können sich noch ändern - siehe unten.

models_count und keys_count liefern die Summen hinter top_models und top_keys, die höchstens die Top 20 nach Kosten aufführen. Der Zeitraum ist standardmäßig die 30 Tage vor end , wenn start ausgelassen wird.

Beispielanfrage

curl "https://synthorai.io/api/v1/billing/summary?start=2026-09-17&end=2026-09-24" \
  -H "Authorization: Bearer sk-syn-bill-..."

Beispielantwort

{
  "data": {
    "totals": { "requests": 48210, "cost_usd": 132.55, "error_rate": 0.021 },
    "models_count": 6,
    "keys_count": 3,
    "top_models": [ { "model": "claude-sonnet-5", "cost_usd": 88.10, "byok_list_price_usd": 0 } ],
    "top_keys": [ { "api_key_id": 42, "api_key_name": "prod-backend", "cost_usd": 61.30, "byok_list_price_usd": 0 } ],
    "anomalies": [
      { "type": "data_not_final", "severity": "info", "message": "The last 2 hours of this range are not yet final." }
    ]
  },
  "meta": {
    "generated_at": "2026-09-24T06:00:02Z",
    "data_complete_until": "2026-09-24T04:00:00Z"
  }
}

GET /freshness - wie vollständig die Daten sind

GET /freshness

Liefert data_complete_until, latest_recorded_at, safe_until und pipeline_lag_seconds - fragen Sie es ab, bevor Sie einen gerade abgerufenen Zeitraum als endgültig behandeln. safe_until ist der neueste recorded_at, den ein Aufrufer als vollständig ansehen kann; jüngere Zeilen können noch eintreffen.

Beispielanfrage

curl "https://synthorai.io/api/v1/billing/freshness" \
  -H "Authorization: Bearer sk-syn-bill-..."

Beispielantwort

{
  "data": {
    "data_complete_until": "2026-09-24T04:00:00Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "safe_until": "2026-09-24T05:58:31Z",
    "pipeline_lag_seconds": 47
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z" }
}

GET /balance - was der Workspace jetzt ausgeben kann

GET /balance

Liefert das aktuell verfügbare Guthaben des Workspace - denselben Betrag wie in der Konsole. Für regelmäßige Abfragen gebaut: alle 30 bis 60 Sekunden genügt. Es hat ein eigenes Rate-Limit, sodass das Abfragen das Budget der Daten-Endpunkte nicht aufbraucht, und es antwortet auch bei einem Guthaben von null.

Beispielanfrage

curl "https://synthorai.io/api/v1/billing/balance" \
  -H "Authorization: Bearer sk-syn-bill-..."

Beispielantwort

{
  "data": {
    "available_usd": 1284.37,
    "debt_usd": 0,
    "source": "live",
    "voucher": null,
    "scheduled_credits": [
      { "amount_usd": 250, "release_at": "2026-10-01T00:00:00Z" }
    ],
    "scheduled_credit_total_usd": 250
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z", "currency": "USD" }
}

Fehler

Jeder Fehler ist {"error": {"type", "message", "hint"}}:

{
  "error": {
    "type": "range_too_large",
    "message": "the requested range exceeds this endpoint's cap",
    "hint": "narrow start/end to at most 31 days, or sync /records with a cursor instead"
  }
}

Rate-Limits und Obergrenzen

Wird nie zurückgegeben: channel_id, upstream_request_id, usage_raw, other, content, ip_address, user_agent, cost_detail.

Zeitlücken vermeiden

Anfragen werden nach ihrem Abschluss asynchron in das Log geschrieben (normalerweise Sekunden, bei Rückstand länger), und das stündliche Rollup, aus dem /usage und /summary lesen, wird in Batches eingespielt. Die jüngsten Stunden sind immer etwas unvollständig. /usage und /summary ergänzen außerdem die seit dem letzten Import geschriebenen Anfragen (meta.live_tail ist true); liegt der Rollup dafür zu weit zurück, ist meta.live_tail false und die jüngsten Buckets sind unvollständig.

data_complete_until ist der frühere der beiden folgenden Zeitpunkte: der Wasserstand des stündlichen Rollups minus der aktuellen Pipeline-Verzögerung, oder die älteste noch nicht eingerollte Anfrage - minus einer Sicherheitsmarge von 30 Minuten, abgerundet auf die volle Stunde.

Jede Zeile von /usage trägt ein final -Flag: true , das gilt, sobald sein Bucket vor oder bei data_complete_until (Wert von /freshness) endet. Ein finaler Bucket ändert sich nie wieder.

• Aggregate: upserten Sie jede Zeile anhand von (bucket_start, api_key_id, model) in Ihren eigenen Speicher, und holen Sie jeden Bucket erneut ab, solange er noch final: false ist. Leiten Sie niemals ein Delta ab, indem Sie eine alte Summe von einer neuen abziehen.
• Rohdaten-Zeilen: synchronisieren Sie nach cursor, niemals nach Zeit. Bewahren Sie next_cursor auf und setzen Sie beim nächsten Aufruf dort fort, und entfernen Sie Duplikate eingehender Zeilen anhand von record_id (eine stabile, undurchsichtige id pro Zeile), falls eine wiederholte Seite dieselbe Zeile erneut liefert. Zeilen, die jünger als etwa 5 Minuten sind, werden zurückgehalten - safe_until ist die Zeit der neuesten protokollierten Zeile minus 5 Minuten - sodass eine noch in Arbeit befindliche Zeile niemals an einer bereits ausgegebenen Cursor-Position vorbeirutschen kann und nichts in eine Lücke fällt. Zum Zählen von Anfragen zählen Sie eindeutige request_id.
• Begrenztes Fenster: wenn Sie einen start/end-Zeitraum abfragen, statt nach cursor zu synchronisieren, behandeln Sie ihn erst als vollständig, wenn window_final true ist (das ist nur der Fall, wenn Sie ein end angegeben haben und dieses bei oder vor safe_until liegt). Ist window_final false, rufen Sie später mit demselben Zeitraum erneut auf, oder wechseln Sie zur Synchronisierung per cursor. Ein Fenster muss spätestens bei safe_until beginnen; ein späterer Beginn liefert 400 start_too_recent mit Retry-After-Header.

Empfohlene Integration

• Nächtliche Abrechnung: rufen Sie /usage einmal täglich mit granularity=day auf, und holen Sie jeden Bucket erneut ab, der bei Ihrem letzten Lauf noch final: false war.
• Details pro Anfrage: rufen Sie /records stündlich mit cursor auf den zuletzt gespeicherten next_cursor gesetzt auf, paginieren Sie weiter, solange has_more true ist, und entfernen Sie Duplikate eingehender Zeilen anhand von record_id.
• Dashboards: rufen Sie für den sichtbaren Zeitraum /summary auf, statt /records selbst zu aggregieren - er enthält bereits die Anomalienliste.

Müssen Sie reguläre API-Schlüssel programmatisch erstellen oder verwalten, statt Abrechnungsdaten zu lesen? Siehe Provisioning-Schlüssel.