# Ereignisse auflisten

`GET /v1/events` · Berechtigung `events:read`

Gibt die Ereignisse der Umgebung in chronologischer Reihenfolge zurück, das älteste zuerst. Jedes Ereignis ist dasselbe Dokument mit derselben `id`, das Webhooks ausliefern. Ereignisse werden bei jedem Tarif 30 Tage aufbewahrt.

Verwenden Sie diesen Endpoint, wenn Ihr System keine Webhooks empfangen kann oder um eine Lücke nach einem Ausfall zu schließen: Speichern Sie den zuletzt verarbeiteten `next_cursor` und setzen Sie von dort aus fort.

Die Umgebung ergibt sich immer aus dem API-Schlüssel; es gibt keinen Parameter für die Umgebung.

## Anfrage

| Parameter | In | Pflicht | Beschreibung |
|---|---|---|---|
| `after` | query | nein | `next_cursor` aus der vorherigen Antwort oder `latest`, um nur ab jetzt aufgezeichnete Ereignisse zu erhalten. Ohne diesen Parameter beginnt die Liste mit dem ältesten gespeicherten Ereignis. |
| `types` | query | nein | Durch Kommas getrennte Ereignistypen, höchstens 20, z. B. `user.created,user.deleted`. Ohne diesen Parameter werden alle Typen zurückgegeben. |
| `org_id` | query | nein | Nur Ereignisse dieser Organisation (`org_…`). |
| `limit` | query | nein | Seitengröße, 1 bis 100. Standard: 20. |
| `payload` | query | nein | `thin` (Standard) oder `full`. `full` erfordert zusätzlich die Berechtigung `users:read`. Solange die vollständige Nutzlast nicht verfügbar ist, gibt `full` die reduzierte Nutzlast zurück. |
| `purpose` | query | nein | `tail` (Standard) oder `webhooks_listen`. `webhooks_listen` wird nur in den Umgebungen `development` und `staging` akzeptiert. |

## Antwort

`200 OK`:

| Feld | Beschreibung |
|---|---|
| `data` | Ereignisse in chronologischer Reihenfolge. Jedes Ereignis hat eine `seq`, die innerhalb der Umgebung steigt. |
| `next_cursor` | Immer vorhanden. Übergeben Sie ihn als `after` in der nächsten Anfrage, auch wenn `data` leer ist. |
| `has_more` | `true`, wenn weitere Ereignisse folgen; fragen Sie sofort erneut ab. Bei `false` warten Sie vor der nächsten Abfrage (5 bis 60 Sekunden). |

Der Cursor hängt nicht von `types` oder `org_id` ab: Sie können den Filter ändern und von derselben Position aus fortfahren. Ein Cursor funktioniert nur in der Umgebung, die ihn ausgegeben hat.

```json
{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "type": "connection.deleted",
      "schema_version": 1,
      "environment_id": "env_01j9xk3m7q8r2s4t6v8w0y2z4e",
      "occurred_at": "2026-11-03T08:15:42.120Z",
      "recorded_at": "2026-11-03T08:15:42.140Z",
      "seq": 4182,
      "data": {
        "object": {"id": "conn_01j9xk3m7q8r2s4t6v8w0y2z4f", "status": "deleted"},
        "object_version": 2
      },
      "context": {"actor": {"type": "system"}, "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182"}
    }
  ],
  "next_cursor": "eyJ2IjoxfQ.c2lnbmF0dXJl",
  "has_more": false
}
```

## Beispiel: Auf neue Ereignisse abfragen

```bash
cursor=latest
while true; do
  page=$(curl -sS -G https://api.keenauth.com/v1/events \
    -H "Authorization: Bearer $KEENAUTH_API_KEY" \
    --data-urlencode "after=$cursor" --data-urlencode "limit=100")
  echo "$page" | jq -c '.data[]'
  cursor=$(echo "$page" | jq -r '.next_cursor')
  [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || sleep 10
done
```

Die CLI macht dasselbe mit `keenauth events tail`.

## Fehler

Jeder Fehler ist ein `application/problem+json`-Body mit einem stabilen `code`.

| HTTP | `code` | Wann |
|---|---|---|
| 400 | `invalid_cursor` | Der Cursor ist fehlerhaft oder wurde in einer anderen Umgebung ausgegeben. |
| 401 | `unauthenticated` | Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen. |
| 403 | `insufficient_permissions` | Dem Schlüssel fehlt `events:read` oder `payload=full` ohne `users:read`. |
| 403 | `test_feature_not_in_production` | `purpose=webhooks_listen` in einer Produktionsumgebung. |
| 422 | `validation_failed` | Ein Parameter ist ungültig oder mehrfach angegeben; `errors[].pointer` nennt ihn. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; beachten Sie `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es später erneut. |

## Personenbezogene Daten

Dieser Endpoint enthält personenbezogene Daten: Ereignisse. [Personenbezogene Daten in den KeenAuth-APIs](/docs/policies/personal-data) beschreibt, welche Daten gespeichert werden, wie lange sie aufbewahrt werden und wie sie gelöscht werden. Senden Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).