> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ausgaben und Nutzung abfragen > - Ausgaben und Aufrufstatistiken für einen Zeitraum abfragen - Nach Modellen filtern und nach Modell oder Kalendertag gruppieren - Nutzung des aktuellen API Key oder des gesamten Kontos abfragen - USD-Beträge, Credits, Aufrufanzahl und Token-Nutzung erhalten Fragen Sie mit einem API Key die Ausgaben für einen Zeitraum ab. Sie können nach Modellen filtern und nach Modell, Kalendertag oder beiden Kriterien gruppieren. Das Ergebnis wird direkt aggregiert zurückgegeben; Aufgaben und Status-Polling sind nicht erforderlich. ```bash cURL theme={null} curl --get 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=2026-09-01T00:00:00+08:00' \ --data-urlencode 'end=2026-09-08T00:00:00+08:00' \ --data-urlencode 'group_by=model' ``` ```python Python theme={null} import requests response = requests.get( "https://api.apimart.ai/v1/usage", headers={"Authorization": "Bearer "}, params={ "start": "2026-09-01T00:00:00+08:00", "end": "2026-09-08T00:00:00+08:00", "group_by": "model", }, timeout=30, ) payload = response.json() if not response.ok or not payload.get("success"): message = payload.get("error", {}).get("message", "Nutzungsabfrage fehlgeschlagen") raise RuntimeError(f"HTTP {response.status_code}: {message}") print(payload["data"]["total"]) print(payload["data"]["items"]) ``` ```javascript JavaScript theme={null} const url = new URL("https://api.apimart.ai/v1/usage"); url.search = new URLSearchParams({ start: "2026-09-01T00:00:00+08:00", end: "2026-09-08T00:00:00+08:00", group_by: "model", }).toString(); const response = await fetch(url, { headers: { Authorization: "Bearer " }, }); const payload = await response.json(); if (!response.ok || !payload.success) { throw new Error( `HTTP ${response.status}: ${payload.error?.message ?? "Nutzungsabfrage fehlgeschlagen"}`, ); } console.log(payload.data.total); console.log(payload.data.items); ``` ```json 200 theme={null} { "success": true, "data": { "scope": "key", "start": 1788192000, "end": 1788796800, "tz": "Asia/Shanghai", "group_by": "model", "total": { "amount_usd": 12.3456, "credits": 123.456, "requests": 1834, "prompt_tokens": 902311, "completion_tokens": 215044 }, "items": [ { "model": "gpt-5.6-luna", "amount_usd": 9.1271, "credits": 91.271, "requests": 1520, "prompt_tokens": 880120, "completion_tokens": 201300 }, { "model": "sora-2", "amount_usd": 3.2185, "credits": 32.185, "requests": 314, "prompt_tokens": 22191, "completion_tokens": 13744 } ] } } ``` ```json 400 theme={null} { "success": false, "error": { "code": "range_too_large", "message": "Time range must not exceed 31 days.", "type": "usage_query_error" } } ``` ## Authentifizierung Verwenden Sie denselben API Key wie für Modellaufrufe mit Bearer-Token-Authentifizierung. Schlüssel erhalten Sie auf der [API-Key-Verwaltungsseite](https://apimart.ai/keys). ``` Authorization: Bearer YOUR_API_KEY ``` Abfragen sind auch bei einem Guthaben von 0 möglich. Das Guthaben wird nicht geprüft, wohl aber Status und Ablaufdatum des API Key, die IP-Freigabeliste und der Kontostatus. ## Endpunkte ```text theme={null} GET /v1/usage GET /usage ``` Beide Endpunkte bieten dieselbe Funktion und unterstützen CORS. Bewahren Sie Ihren API Key sicher auf und veröffentlichen Sie ihn nicht im Frontend-Code. ## Anfrageparameter Alle Parameter werden als URL-Query-Parameter übergeben. Startzeit, einschließlich dieses Zeitpunkts. Unterstützt Unix-Zeitstempel in Sekunden oder RFC3339-Zeichenfolgen mit Zeitzone, z. B. `2026-09-01T00:00:00+08:00`. Ohne Angabe: 24 Stunden vor `end`. Zeitstempel sind in Sekunden, nicht Millisekunden. Endzeit, ausschließlich dieses Zeitpunkts. Gleiches Format wie `start`; ohne Angabe gilt die aktuelle Zeit. Muss nach `start` liegen; `end - start` darf 31 Tage nicht überschreiten. Modellname. Ohne Angabe werden alle Modelle berücksichtigt. Mehrere Modelle mit Kommas trennen; maximal `50`. Exakte Übereinstimmung ohne Beachtung der Groß-/Kleinschreibung. Keine Platzhalter. Beispiel: `gpt-5.6-luna,sora-2` Gruppierung: * `none`: nur Gesamtsumme; `items` ist ein leeres Array * `model`: nach Modell * `date`: nach Kalendertag * `model,date`: nach Modell und Kalendertag IANA-Zeitzonenname. Standard: `Asia/Shanghai`. Beeinflusst nur die Tagesgrenzen, wenn `group_by` den Wert `date` enthält, nicht die Start- und Endzeitpunkte. RFC3339-Zeiten werden anhand ihrer eigenen Zeitzone interpretiert. Statistikbereich: * `key`: nur der aktuelle API Key (Standard) * `account`: alle API Keys des Kontos, zu dem der aktuelle Schlüssel gehört Der Zeitraum ist `[start, end)`: Start inklusive, Ende exklusive. Verwenden Sie für `end` der vorherigen und `start` der nächsten Abfrage denselben Zeitpunkt, um doppelte Zählung an der Grenze zu vermeiden. Beim manuellen Erstellen einer URL muss `+` in RFC3339 als `%2B` kodiert werden. cURL `--data-urlencode`, Python `params` und JavaScript `URLSearchParams` in den Beispielen erledigen dies automatisch. ## Anfragebeispiele ### Ausgaben des aktuellen API Key in den letzten 24 Stunden Ohne Query-Parameter gelten der standardmäßige Zeitraum, Statistikbereich und die Standardgruppierung. ```bash theme={null} curl 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' ``` ### Tägliche Ausgaben des gesamten Kontos für bestimmte Modelle Ausgaben vom 11. bis 18. September 2026 nach Pekinger Zeit, ausschließlich des 18. September. ```bash theme={null} curl --get 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=1789056000' \ --data-urlencode 'end=1789660800' \ --data-urlencode 'model=gpt-5.6-luna' \ --data-urlencode 'group_by=date' \ --data-urlencode 'scope=account' \ --data-urlencode 'tz=Asia/Shanghai' ``` ### Nach Modell und Kalendertag gruppieren ```bash theme={null} curl --get 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=2026-09-01T00:00:00+08:00' \ --data-urlencode 'end=2026-09-08T00:00:00+08:00' \ --data-urlencode 'model=gpt-5.6-luna,sora-2' \ --data-urlencode 'group_by=model,date' \ --data-urlencode 'tz=Asia/Shanghai' ``` Bei dieser Gruppierung enthält jedes Element in `items` sowohl `model` als auch `date`. ## Antwortfelder Erfolg der Abfrage: `true` bei Erfolg, `false` bei einem Nutzungsabfragefehler. Bei Erfolg: Abfragebereich, Gesamtsumme und gruppierte Details. Statistikbereich: `key` oder `account`. Tatsächliche Startzeit als Unix-Zeitstempel in Sekunden, inklusive. Tatsächliche Endzeit als Unix-Zeitstempel in Sekunden, exklusive. Zeitzone für die Gruppierung nach Kalendertag. Gruppierung: `none`, `model`, `date` oder `model,date`. Gesamtsumme im Abfragebereich. Statistikfelder siehe Tabelle unten. Gruppierte Details, absteigend nach `amount_usd`. Bei `group_by=none` ein leeres Array. Jedes Element enthält die Statistikfelder aus der folgenden Tabelle. * Enthält `group_by` den Wert `model`, enthält das Element `model` * Enthält `group_by` den Wert `date`, enthält das Element `date` im Format `YYYY-MM-DD`; Tagesgrenzen gemäß `tz` `data.total` und `data.items[]` verwenden dieselben Statistikfelder: | Feld | Typ | Beschreibung | | ------------------- | ------- | ----------------------------------------------------------------------------------------- | | `amount_usd` | number | USD-Betrag, auf 6 Nachkommastellen gerundet | | `credits` | number | Credits des Dienstes: `amount_usd × 10`, gleiche Einheit wie auf der Website | | `requests` | integer | Anzahl erfolgreich abgerechneter Aufrufe | | `prompt_tokens` | integer | Eingabe-Token; bei Bild- und Videomodellen mit Abrechnung pro Aufruf oder Sekunde meist 0 | | `completion_tokens` | integer | Ausgabe-Token; bei Bild- und Videomodellen mit Abrechnung pro Aufruf oder Sekunde meist 0 | Bei Nutzungsabfragefehlern mit `code`, `message` und `type`; `type` ist `usage_query_error`. Authentifizierungsfehler 401 / 403 kommen aus der Authentifizierungsschicht. ## Ratenlimits und Cache * Maximal `60` Abfragen pro API Key und Minute; globale API-Ratenlimits gelten zusätzlich * Ergebnisse mit gleichen Parametern werden `60` Sekunden gecacht; Antwortheader `X-Usage-Cache`: `hit` oder `miss` * Ausgaben sind meist innerhalb von 1 Sekunde abrufbar; die letzte Minute kann unvollständig sein und Cache-Verzögerungen sind möglich * Mindestens 1 Minute zwischen Abfragen empfohlen; nicht als Echtzeitbenachrichtigung für Abbuchungen verwenden ## Berechnungsgrundlage * Erfolgreich abgerechnete Aufrufdatensätze, identisch mit den Daten im Dashboard der Website * Fehlgeschlagene Aufrufe und Erstattungen nach Aufgabenfehlern sind ausgeschlossen; kein manuelles Gegenrechnen nötig. Bei teilweise erfolgreichen Bildserien werden die tatsächlich gelieferten Bilder abgerechnet * Maßgeblich ist der Buchungszeitpunkt. Asynchrone Bild- und Videoaufgaben werden bei Abschluss gebucht, nicht bei Einreichung; über Mitternacht laufende Aufgaben zählen zum Abschlusstag * Ein nach Löschung neu erstellter API Key ist ein neuer Schlüssel. Seine Abfrage mit `scope=key` enthält keine Historie des alten Schlüssels * Manuelle Guthabenanpassungen sind keine Aufrufausgaben und werden nicht berücksichtigt * Daten nach dem 27. April 2026 sind verfügbar ## Fehlerbehandlung | HTTP-Status | `error.code` | Beschreibung | | ----------- | ------------------------------- | ----------------------------------------------------------------------------- | | 400 | `invalid_start` / `invalid_end` | Ungültiges Start- oder Endzeitformat | | 400 | `invalid_range` | `end` liegt nicht nach `start` | | 400 | `range_too_large` | Mehr als 31 Tage; in mehrere Abfragezeiträume aufteilen | | 400 | `invalid_tz` | Unbekannte IANA-Zeitzone | | 400 | `invalid_group_by` | Ungültige Gruppierung | | 400 | `invalid_scope` | Ungültiger Statistikbereich | | 400 | `too_many_models` | Mehr als 50 Modelle | | 401 / 403 | — | Ungültiger oder abgelaufener API Key, IP nicht erlaubt oder Konto deaktiviert | | 429 | — | Mehr als 60 Abfragen pro Schlüssel und Minute oder globales API-Ratenlimit | | 503 | `usage_unavailable` | Nutzungsdaten vorübergehend nicht verfügbar; später erneut versuchen | `503 usage_unavailable` liefert keine Beträge. Die Abfrage ist nicht verfügbar; die Ausgaben sind nicht notwendigerweise 0. Fehlgeschlagene Antworten nicht als Nullbetrag behandeln oder frühere erfolgreiche Ergebnisse überschreiben. ## Vergleich mit anderen Endpunkten | Endpunkt | Funktion | | --------------------------------- | ----------------------------------------------------------------------------------------------- | | `GET /v1/dashboard/billing/usage` | Nur kumulierte Ausgaben; keine Modell- oder Zeitfilter | | `POST /v1/logs/export` | Asynchroner Export von Aufrufdetails (CSV / XLSX); selbst aggregieren | | `GET /v1/usage` | Abfrage nach Zeitraum und Modell mit direkter Rückgabe von Gesamtsumme und gruppierten Ausgaben | Für das verbleibende Kontingent verwenden Sie [Token-Guthaben abfragen](/de/api-reference/account/token-balance) oder [Benutzerguthaben abfragen](/de/api-reference/account/user-balance).