Usage Events API

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

array

erforderlich

Array von Nutzungsereignissen (1-1000 Events)

Anzeigen Event-Objekt

string

erforderlich

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

string

erforderlich

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

string

erforderlich

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

string

erforderlich

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

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

integer

Anzahl erfolgreich verarbeiteter Events

integer

Anzahl fehlgeschlagener Events

array

Details zu fehlgeschlagenen Events

Anzeigen Error-Objekt

integer

Index des fehlgeschlagenen Events im Request-Array

string

TransactionId des fehlgeschlagenen Events

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

string

Filtere nach Kunden-UUID

string

Filtere nach Event-Name

string

Filtere nach Zeitraum (ISO 8601)

string

Standard:"timestamp"

Sortierfeld: timestamp oder createdAt

string

Standard:"DESC"

Sortierreihenfolge: ASC oder DESC

string

Paginierungs-Cursor für nächste Seite

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

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

string

Filtere nach spezifischem Event-Namen

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

array

Liste aller gefundenen Event-Namen mit Beispiel-Properties

array

Liste aller gefundenen Property-Pfade mit Typ-Information

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

API documentation

User

Tenant

Customer

Catalogue

Subscription

Invoice

Payment

Dunning

Offer

Checkout

Feature & Entitlement

Analytics

Accounting

Settings

Base URL

Authentifizierung

Endpoints

POST /api/usage-events

Request

Request Body

Response (202 Accepted)

GET /api/usage-events

Request

Query Parameter

Response (200 OK)

GET /api/usage-events/[id]

Request

Path Parameter

Response (200 OK)

GET /api/usage-events/discover

Request

Query Parameter

Response (200 OK)

Fehler-Codes

Verwandte Dokumentation