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-events | Nutzungsereignisse senden (Batch) |
| GET | /api/usage-events | Nutzungsereignisse abrufen |
| GET | /api/usage-events/[id] | Einzelnes Ereignis abrufen |
| GET | /api/usage-events/discover | Event-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)
Beliebige Event-Eigenschaften für Aggregation, Filter und Gruppierung
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
