Die Usage Events API ermöglicht das Senden und Abrufen von Nutzungsereignissen für nutzungsbasierte Abrechnung.
Base URL Authentifizierung Alle Endpoints erfordern einen API-Token im Header:
Authorization : Bearer YOUR_API_KEY
Endpoints Method Endpoint Beschreibung POST /api/usage-eventsNutzungsereignisse senden (Batch) GET /api/usage-eventsNutzungsereignisse abrufen GET /api/usage-events/[id]Einzelnes Ereignis abrufen GET /api/usage-events/discoverEvent-Namen und Properties entdecken
POST /api/usage-events Sende bis zu 1000 Nutzungsereignisse in einem Request.
Request curl -X POST https://coreapi.io/api/usage-events \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "events": [ { "transactionId": "tx-001", "eventName": "ai_request", "timestamp": "2026-02-01T10:00:00Z", "customerId": "550e8400-e29b-41d4-a716-446655440000", "properties": { "tokens_used": 350, "model": "gpt-4" } } ] }'
Request Body Array von Nutzungsereignissen (1-1000 Events) Eindeutige ID für Idempotenz. Doppelte transactionIds werden ignoriert.
Name des Events. Muss mit dem konfigurierten Event-Namen der Nutzungsmetrik übereinstimmen.
Zeitstempel im ISO 8601 Format (z.B. 2026-02-01T10:00:00Z)
Kunden-Identifier. Akzeptiert die Fynn-UUID oder die externe Kundennummer (externalId). Fynn erkennt automatisch, welches Format übergeben wird.
Beliebige Event-Eigenschaften für Aggregation, Filter und Gruppierung
Du kannst im Feld customerId auch die externe Kundennummer (externalId) übergeben. Fynn erkennt automatisch, ob es sich um eine UUID oder eine externe ID handelt. Die externalId wird am Kunden unter Kundeneinstellungen hinterlegt. Response (202 Accepted) { "ingested" : 1 , "failed" : 0 , "errors" : [] }
Anzahl erfolgreich verarbeiteter Events
Anzahl fehlgeschlagener Events
Details zu fehlgeschlagenen Events Index des fehlgeschlagenen Events im Request-Array
TransactionId des fehlgeschlagenen Events
GET /api/usage-events Rufe Nutzungsereignisse mit Paginierung und Filtern ab.
Request curl -X GET "https://coreapi.io/api/usage-events?customerId=550e8400-e29b-41d4-a716-446655440000&eventName=ai_request&limit=20" \ -H "Authorization: Bearer YOUR_API_KEY"
Query Parameter Filtere nach Zeitraum (ISO 8601)
sort
string
Standard: "timestamp"
Sortierfeld: timestamp oder createdAt
Sortierreihenfolge: ASC oder DESC
Paginierungs-Cursor für nächste Seite
Anzahl Ergebnisse pro Seite (max. 100)
Response (200 OK) { "data" : [ { "id" : "01HQXYZ123456789ABCDEFGH" , "transactionId" : "tx-001" , "eventName" : "ai_request" , "timestamp" : "2026-02-01T10:00:00Z" , "customerId" : "550e8400-e29b-41d4-a716-446655440000" , "properties" : { "tokens_used" : 350 , "model" : "gpt-4" }, "createdAt" : "2026-02-01T10:00:05Z" } ], "meta" : {}, "pagination" : { "cursor" : "eyJpZCI6IjAxSFFYWVoxMjM0NTY3ODlBQkNERUZHSCJ9" } }
GET /api/usage-events/[id] Rufe ein einzelnes Nutzungsereignis ab.
Request curl -X GET "https://coreapi.io/api/usage-events/01HQXYZ123456789ABCDEFGH" \ -H "Authorization: Bearer YOUR_API_KEY"
Path Parameter UUID oder ULID des Nutzungsereignisses
Response (200 OK) { "id" : "01HQXYZ123456789ABCDEFGH" , "transactionId" : "tx-001" , "eventName" : "ai_request" , "timestamp" : "2026-02-01T10:00:00Z" , "customerId" : "550e8400-e29b-41d4-a716-446655440000" , "properties" : { "tokens_used" : 350 , "model" : "gpt-4" }, "createdAt" : "2026-02-01T10:00:05Z" }
GET /api/usage-events/discover Entdecke automatisch Event-Namen und Properties aus bereits gesendeten Events. Nützlich für die Konfiguration von Nutzungsmetriken.
Request curl -X GET "https://coreapi.io/api/usage-events/discover?limit=1000" \ -H "Authorization: Bearer YOUR_API_KEY"
Query Parameter Filtere nach spezifischem Event-Namen
Anzahl Events zur Analyse (max. 10000)
Response (200 OK) { "eventNames" : [ { "name" : "ai_request" , "sampleProperties" : { "tokens_used" : 350 , "model" : "gpt-4" } }, { "name" : "api_call" , "sampleProperties" : { "endpoint" : "/api/users" , "status_code" : 200 } } ], "allProperties" : [ { "path" : "tokens_used" , "type" : "number" , "eventName" : "ai_request" , "sampleValues" : [ 150 , 350 , 500 ] }, { "path" : "model" , "type" : "string" , "eventName" : "ai_request" , "sampleValues" : [ "gpt-4" , "gpt-4-turbo" , "gpt-3.5-turbo" ] } ], "exampleEvents" : [ { "eventName" : "ai_request" , "properties" : { "tokens_used" : 350 , "model" : "gpt-4" }, "timestamp" : "2026-02-01T10:00:00Z" } ] }
Liste aller gefundenen Event-Namen mit Beispiel-Properties
Liste aller gefundenen Property-Pfade mit Typ-Information
Beispiel-Events für jeden Event-Namen
Fehler-Codes HTTP Status Beschreibung 202 Events akzeptiert (kann teilweise Fehler enthalten) 400 Ungültige Anfrage - Validierungsfehler 401 Nicht autorisiert - Ungültiger API-Token 404 Event nicht gefunden 429 Rate Limit überschritten
Verwandte Dokumentation 
