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

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

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

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

​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

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