> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```http theme={null}
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

```bash theme={null}
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

<ParamField body="events" type="array" required>
  Array von Nutzungsereignissen (1-1000 Events)

  <Expandable title="Event-Objekt">
    <ParamField body="transactionId" type="string" required>
      Eindeutige ID für Idempotenz. Doppelte transactionIds werden ignoriert.
    </ParamField>

    <ParamField body="eventName" type="string" required>
      Name des Events. Muss mit dem konfigurierten Event-Namen der Nutzungsmetrik übereinstimmen.
    </ParamField>

    <ParamField body="timestamp" type="string" required>
      Zeitstempel im ISO 8601 Format (z.B. `2026-02-01T10:00:00Z`)
    </ParamField>

    <ParamField body="customerId" type="string" required>
      Kunden-Identifier. Akzeptiert die Fynn-UUID **oder** die externe Kundennummer (`externalId`). Fynn erkennt automatisch, welches Format übergeben wird.
    </ParamField>

    <ParamField body="properties" type="object">
      Beliebige Event-Eigenschaften für Aggregation, Filter und Gruppierung
    </ParamField>
  </Expandable>
</ParamField>

<Tip>
  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](/guide/customers/settings) hinterlegt.
</Tip>

### Response (202 Accepted)

```json theme={null}
{
  "ingested": 1,
  "failed": 0,
  "errors": []
}
```

<ResponseField name="ingested" type="integer">
  Anzahl erfolgreich verarbeiteter Events
</ResponseField>

<ResponseField name="failed" type="integer">
  Anzahl fehlgeschlagener Events
</ResponseField>

<ResponseField name="errors" type="array">
  Details zu fehlgeschlagenen Events

  <Expandable title="Error-Objekt">
    <ResponseField name="index" type="integer">
      Index des fehlgeschlagenen Events im Request-Array
    </ResponseField>

    <ResponseField name="transactionId" type="string">
      TransactionId des fehlgeschlagenen Events
    </ResponseField>

    <ResponseField name="error" type="string">
      Fehlermeldung
    </ResponseField>
  </Expandable>
</ResponseField>

***

## GET /api/usage-events

Rufe Nutzungsereignisse mit Paginierung und Filtern ab.

### Request

```bash theme={null}
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

<ParamField query="customerId" type="string">
  Filtere nach Kunden-UUID
</ParamField>

<ParamField query="eventName" type="string">
  Filtere nach Event-Name
</ParamField>

<ParamField query="timestamp" type="string">
  Filtere nach Zeitraum (ISO 8601)
</ParamField>

<ParamField query="sort" type="string" default="timestamp">
  Sortierfeld: `timestamp` oder `createdAt`
</ParamField>

<ParamField query="order" type="string" default="DESC">
  Sortierreihenfolge: `ASC` oder `DESC`
</ParamField>

<ParamField query="cursor" type="string">
  Paginierungs-Cursor für nächste Seite
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Anzahl Ergebnisse pro Seite (max. 100)
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "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

```bash theme={null}
curl -X GET "https://coreapi.io/api/usage-events/01HQXYZ123456789ABCDEFGH" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameter

<ParamField path="id" type="string" required>
  UUID oder ULID des Nutzungsereignisses
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "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

```bash theme={null}
curl -X GET "https://coreapi.io/api/usage-events/discover?limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Query Parameter

<ParamField query="eventName" type="string">
  Filtere nach spezifischem Event-Namen
</ParamField>

<ParamField query="limit" type="integer" default="1000">
  Anzahl Events zur Analyse (max. 10000)
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "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"
    }
  ]
}
```

<ResponseField name="eventNames" type="array">
  Liste aller gefundenen Event-Namen mit Beispiel-Properties
</ResponseField>

<ResponseField name="allProperties" type="array">
  Liste aller gefundenen Property-Pfade mit Typ-Information
</ResponseField>

<ResponseField name="exampleEvents" type="array">
  Beispiel-Events für jeden Event-Namen
</ResponseField>

***

## 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](/guide/catalogue/measurements/billable-metrics)
* [Nutzungsereignisse senden (Guide)](/guide/catalogue/usage-events-import)
* [Collect Usage Data](/api-reference/guides/collect-usage-data)