# Rapport d'utilisation des obsolescences

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

Indique quels clients appellent encore des opérations programmées pour suppression, afin que vous puissiez les migrer avant la date de suppression (voir la [politique de versionnement](/docs/policies/versioning)). Les appels sont comptés par jour UTC et regroupés par obsolescence, client et version du SDK. Lorsqu'aucune opération n'est obsolète, le rapport est vide.

L'environnement provient toujours de la clé d'API ; il n'existe aucun paramètre d'environnement. Les lignes ne contiennent aucune adresse IP, aucun `User-Agent` ni aucun identifiant d'utilisateur final.

## Requête

| Paramètre | Dans | Obligatoire | Description |
|---|---|---|---|
| `from` | query | non | Premier jour inclus, date complète (`YYYY-MM-DD`, UTC). Par défaut, `to` moins 30 jours. Limité par l'historique de rapports de votre plan (voir ci-dessous). |
| `to` | query | non | Dernier jour inclus, date complète (`YYYY-MM-DD`, UTC). Par défaut, aujourd'hui. `from` ne doit pas être postérieur à `to`. |
| `limit` | query | non | Taille de page, de 1 à 100. Par défaut 50. |
| `cursor` | query | non | `next_cursor` de la page précédente. Valide uniquement pour l'environnement, `from` et `to` pour lesquels il a été émis. |

Les lignes sont triées par `deprecation_id`, `client_id`, `sdk_package`, `sdk_version`. Les deux bornes de la plage sont incluses. Un curseur issu d'une plage par défaut (sans `from`/`to` envoyés) cesse de fonctionner lorsque le jour UTC change ; envoyez `from` et `to` explicitement lorsque vous paginez.

### Historique de rapports par plan

| Plan | Historique |
|---|---|
| Free | 30 jours |
| Startup, Business | 13 mois |
| Enterprise | 25 mois, plafonné à 400 jours |

La table des rapports conserve 400 jours, donc aucun plan ne remonte au-delà de 400 jours. Un `from` plus ancien que l'historique autorisé échoue avec `422 report_range_exceeds_plan` ; la date la plus ancienne autorisée figure dans le message et dans `errors[0].detail` (`earliest_allowed_date=YYYY-MM-DD`).

## Réponse

`200 OK`. `data` contient les lignes de la page ; `next_cursor` vaut `null` sur la dernière page.

| Champ | Description |
|---|---|
| `deprecation_id` | Identifiant dans le registre des obsolescences (`dep-YYYY-NN`). |
| `client_id` | `key_…` pour une clé d'API de gestion, `app_…` pour un client OAuth de gestion, `dashboard` pour le tableau de bord. |
| `sdk_package` | Paquet SDK issu de l'en-tête `Idp-Client` ; `other` pour un paquet hors catalogue, `none` lorsque l'en-tête est absent. |
| `sdk_version` | Version SemVer, ou une chaîne vide. |
| `call_count` | Appels dans la plage. |
| `last_seen_at` | Dernier appel dans la plage (RFC 3339, UTC). |
| `sunset_at` | Date de suppression issue du registre des obsolescences (`YYYY-MM-DD`), `null` si inconnue. Après ce jour, l'opération répond `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

Envoyez `Accept: text/csv` pour recevoir les mêmes colonnes au format CSV (RFC 4180) avec une ligne d'en-tête. Les cellules de texte commençant par `=`, `+`, `-`, `@`, une tabulation ou un retour chariot sont précédées d'une apostrophe simple afin que les tableurs ne les exécutent pas comme des formules. Le curseur de la page suivante figure dans l'en-tête `Link` (`rel="next"`) ; la plage y est explicitement indiquée.

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

## Remarques

Les compteurs sont collectés par minute et écrits dans le rapport de façon asynchrone ; les appels les plus récents peuvent donc mettre quelques minutes à apparaître. Un incident peut faire perdre jusqu'à 60 secondes de compteurs. Le rapport n'est pas une donnée de facturation.

## Erreurs

Chaque erreur est un corps `application/problem+json` avec un `code` stable.

| HTTP | `code` | Quand |
|---|---|---|
| 400 | `invalid_filter` | `from` ou `to` n'est pas une date `YYYY-MM-DD`, une date est répétée, ou `from` est postérieur à `to`. |
| 400 | `invalid_cursor` | Le curseur est mal formé ou n'a pas été émis pour cet environnement et cette plage. |
| 422 | `report_range_exceeds_plan` | `from` est plus ancien que l'historique de rapports de votre plan. |
| 422 | `validation_failed` | `limit` est hors plage ou un paramètre est répété. |
| 401 | `unauthenticated` | La clé d'API est absente, invalide ou révoquée. |
| 403 | `insufficient_permissions` | La clé ne dispose pas de `reports:read`. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; respectez `Retry-After`. |
| 503 | `service_unavailable` | Le service de rapports est temporairement indisponible ; réessayez plus tard. |

## Exemple

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