Usage Events API

API endpoints for usage-based billing event ingestion and retrieval.

Die Usage Events API ermöglicht das Senden und Abrufen von Nutzungsereignissen für nutzungsbasierte Abrechnung.

​

Base URL

https://coreapi.io

​

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

events · array · erforderlich

Array von Nutzungsereignissen (1-1000 Events)

Anzeigen Event-Objekt

transactionId · string · erforderlich

Eindeutige ID für Idempotenz. Doppelte transactionIds werden ignoriert.

eventName · string · erforderlich

Name des Events. Muss mit dem konfigurierten Event-Namen der Nutzungsmetrik übereinstimmen.

timestamp · string · erforderlich

Zeitstempel im ISO 8601 Format (z.B. 2026-02-01T10:00:00Z)

customerId · string · erforderlich

Kunden-Identifier. Akzeptiert die Fynn-UUID oder die externe Kundennummer (externalId). Fynn erkennt automatisch, welches Format übergeben wird.

properties · object

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": []
}

ingested · integer

Anzahl erfolgreich verarbeiteter Events

failed · integer

Anzahl fehlgeschlagener Events

errors · array

Details zu fehlgeschlagenen Events

Anzeigen Error-Objekt

index · integer

Index des fehlgeschlagenen Events im Request-Array

transactionId · string

TransactionId des fehlgeschlagenen Events

error · string

Fehlermeldung

---

​

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

customerId · string

Filtere nach Kunden-UUID

eventName · string

Filtere nach Event-Name

timestamp · string

Filtere nach Zeitraum (ISO 8601)

sort · string · Standard: "timestamp"

Sortierfeld: timestamp oder createdAt

order · string · Standard: "DESC"

Sortierreihenfolge: ASC oder DESC

cursor · string

Paginierungs-Cursor für nächste Seite

limit · integer · Standard: "20"

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

id · string · erforderlich

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

eventName · string

Filtere nach spezifischem Event-Namen

limit · integer · Standard: "1000"

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"
    }
  ]
}

eventNames · array

Liste aller gefundenen Event-Namen mit Beispiel-Properties

allProperties · array

Liste aller gefundenen Property-Pfade mit Typ-Information

exampleEvents · array

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

• Nutzungsmetriken konfigurieren
• Nutzungsereignisse senden (Guide)
• Collect Usage Data