# Elenca eventi

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

Restituisce gli eventi dell'ambiente in ordine, dal più vecchio. Ogni evento è lo stesso documento, con lo stesso `id`, che i webhook consegnano. Gli eventi vengono conservati per 30 giorni su ogni piano.

Usa questo endpoint quando il tuo sistema non può ricevere webhook, oppure per colmare una lacuna dopo un'interruzione: conserva l'ultimo `next_cursor` elaborato e continua da lì.

L'ambiente proviene sempre dalla chiave API; non esiste un parametro dell'ambiente.

## Richiesta

| Parametro | In | Obbligatorio | Descrizione |
|---|---|---|---|
| `after` | query | no | `next_cursor` della risposta precedente, oppure `latest` per ricevere solo gli eventi registrati da adesso in poi. Senza questo parametro l'elenco parte dall'evento conservato più vecchio. |
| `types` | query | no | Tipi di evento separati da virgola, al massimo 20, ad esempio `user.created,user.deleted`. Senza questo parametro vengono restituiti tutti i tipi. |
| `org_id` | query | no | Solo eventi di questa organizzazione (`org_…`). |
| `limit` | query | no | Dimensione della pagina, da 1 a 100. Predefinito 20. |
| `payload` | query | no | `thin` (predefinito) o `full`. `full` richiede anche l'autorizzazione `users:read`. Finché il payload completo non è disponibile, `full` restituisce il payload thin. |
| `purpose` | query | no | `tail` (predefinito) o `webhooks_listen`. `webhooks_listen` è accettato solo negli ambienti `development` e `staging`. |

## Risposta

`200 OK`:

| Campo | Descrizione |
|---|---|
| `data` | Eventi in ordine. Ogni evento ha un `seq` che cresce all'interno dell'ambiente. |
| `next_cursor` | Sempre presente. Passalo come `after` nella richiesta successiva, anche quando `data` è vuoto. |
| `has_more` | `true` quando seguono altri eventi; richiedi di nuovo subito. Quando è `false`, attendi prima di interrogare di nuovo (da 5 a 60 secondi). |

Il cursore non dipende da `types` o `org_id`: puoi cambiare il filtro e continuare dalla stessa posizione. Un cursore funziona solo nell'ambiente che lo ha emesso.

```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
}
```

## Esempio: interroga per nuovi eventi

```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
```

La CLI fa lo stesso con `keenauth events tail`.

## Errori

Ogni errore è un body `application/problem+json` con un `code` stabile.

| HTTP | `code` | Quando |
|---|---|---|
| 400 | `invalid_cursor` | Il cursore è malformato o è stato emesso in un altro ambiente. |
| 401 | `unauthenticated` | La chiave API manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La chiave non ha `events:read`, oppure `payload=full` senza `users:read`. |
| 403 | `test_feature_not_in_production` | `purpose=webhooks_listen` in un ambiente di produzione. |
| 422 | `validation_failed` | Un parametro non è valido o è ripetuto; `errors[].pointer` ne indica il nome. |
| 429 | `rate_limited` | È stato superato il limite di frequenza; rispetta `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza è temporaneamente non disponibile; riprova più tardi. |

## Dati personali

Questo endpoint trasporta dati personali: eventi. [Dati personali nelle API di KeenAuth](/docs/policies/personal-data) descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene cancellato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.