# Report di utilizzo delle deprecazioni

`GET /v1/reports/deprecation-usage` · autorizzazione `reports:read`

Mostra quali dei tuoi client chiamano ancora operazioni previste per la rimozione, così da poterli migrare prima della data di rimozione (vedi la [politica di versionamento](/docs/policies/versioning)). Le chiamate sono conteggiate per giorno UTC e raggruppate per deprecazione, client e versione dell'SDK. Quando nessuna operazione è deprecata, il report è vuoto.

L'ambiente proviene sempre dalla chiave API; non esiste un parametro ambiente. Le righe non contengono indirizzi IP, `User-Agent` o identificatori di utenti finali.

## Richiesta

| Parametro | In | Obbligatorio | Descrizione |
|---|---|---|---|
| `from` | query | no | Primo giorno incluso, data completa (`YYYY-MM-DD`, UTC). Predefinito: `to` meno 30 giorni. Limitato dalla cronologia dei report del tuo piano (vedi sotto). |
| `to` | query | no | Ultimo giorno incluso, data completa (`YYYY-MM-DD`, UTC). Predefinito: oggi. `from` non deve essere successivo a `to`. |
| `limit` | query | no | Dimensione della pagina, da 1 a 100. Predefinito 50. |
| `cursor` | query | no | `next_cursor` della pagina precedente. Valido solo per l'ambiente, `from` e `to` per cui è stato emesso. |

Le righe sono ordinate per `deprecation_id`, `client_id`, `sdk_package`, `sdk_version`. Entrambi gli estremi dell'intervallo sono inclusi. Un cursore ottenuto con un intervallo predefinito (senza `from`/`to` inviati) smette di funzionare quando cambia il giorno UTC; invia `from` e `to` in modo esplicito quando paginare.

### Cronologia dei report per piano

| Piano | Cronologia |
|---|---|
| Free | 30 giorni |
| Startup, Business | 13 mesi |
| Enterprise | 25 mesi, con un limite di 400 giorni |

La tabella dei report conserva 400 giorni, quindi nessun piano risale oltre i 400 giorni. Un `from` più vecchio della cronologia consentita fallisce con `422 report_range_exceeds_plan`; la data minima consentita è indicata nel messaggio e in `errors[0].detail` (`earliest_allowed_date=YYYY-MM-DD`).

## Risposta

`200 OK`. `data` contiene le righe della pagina; `next_cursor` è `null` nell'ultima pagina.

| Campo | Descrizione |
|---|---|
| `deprecation_id` | Identificatore nel registro delle deprecazioni (`dep-YYYY-NN`). |
| `client_id` | `key_…` per una chiave API di gestione, `app_…` per un client OAuth di gestione, `dashboard` per la dashboard. |
| `sdk_package` | Pacchetto SDK dall'intestazione `Idp-Client`; `other` per un pacchetto fuori dal catalogo, `none` quando l'intestazione è assente. |
| `sdk_version` | Versione SemVer, oppure una stringa vuota. |
| `call_count` | Chiamate nell'intervallo. |
| `last_seen_at` | Ultima chiamata nell'intervallo (RFC 3339, UTC). |
| `sunset_at` | Data di rimozione dal registro delle deprecazioni (`YYYY-MM-DD`), `null` se sconosciuta. Dopo questo giorno l'operazione risponde `410 endpoint_sunset`. |

```json
{
  "data": [
    {
      "deprecation_id": "dep-2027-01",
      "client_id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d",
      "sdk_package": "keenauth-go",
      "sdk_version": "1.4.0",
      "call_count": 1280,
      "last_seen_at": "2027-03-02T09:30:00Z",
      "sunset_at": "2028-01-17"
    }
  ],
  "next_cursor": null
}
```

### CSV

Invia `Accept: text/csv` per ricevere le stesse colonne in CSV (RFC 4180) con una riga di intestazione. Le celle di testo che iniziano con `=`, `+`, `-`, `@`, una tabulazione o un ritorno a capo ricevono un apice singolo davanti, così che i fogli di calcolo non le eseguano come formule. Il cursore della pagina successiva è nell'intestazione `Link` (`rel="next"`); l'intervallo è esplicitato in quel link.

```text
deprecation_id,client_id,sdk_package,sdk_version,call_count,last_seen_at,sunset_at
dep-2027-01,key_01j9xk3m7q8r2s4t6v8w0y2z4d,keenauth-go,1.4.0,1280,2027-03-02T09:30:00Z,2028-01-17
```

## Note

I conteggi sono raccolti per minuto e scritti nel report in modo asincrono, quindi le chiamate più recenti possono impiegare alcuni minuti a comparire. Un arresto anomalo può far perdere fino a 60 secondi di conteggi. Il report non è un dato di fatturazione.

## Errori

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

| HTTP | `code` | Quando |
|---|---|---|
| 400 | `invalid_filter` | `from` o `to` non è una data `YYYY-MM-DD`, una data è ripetuta, o `from` è successivo a `to`. |
| 400 | `invalid_cursor` | Il cursore è malformato o non è stato emesso per questo ambiente e intervallo. |
| 422 | `report_range_exceeds_plan` | `from` è più vecchio della cronologia dei report del tuo piano. |
| 422 | `validation_failed` | `limit` è fuori intervallo oppure un parametro è ripetuto. |
| 401 | `unauthenticated` | La chiave API è mancante, non valida o revocata. |
| 403 | `insufficient_permissions` | La chiave non ha `reports:read`. |
| 429 | `rate_limited` | È stato superato il limite di frequenza; rispetta `Retry-After`. |
| 503 | `service_unavailable` | Il servizio di report è temporaneamente non disponibile; riprova più tardi. |

## Esempio

```bash
curl "https://api.eu.keenauth.com/v1/reports/deprecation-usage?from=2027-03-01&to=2027-03-31" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

```bash
keenauth reports deprecation-usage --from 2027-03-01 --to 2027-03-31
keenauth reports deprecation-usage --format csv > deprecation-usage.csv
```