# Bericht zur Nutzung abgekündigter Funktionen

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

Zeigt, welche Ihrer Clients noch Operationen aufrufen, die zur Entfernung vorgesehen sind, damit Sie sie vor dem Entfernungsdatum migrieren können (siehe die [Versionierungsrichtlinie](/docs/policies/versioning)). Aufrufe werden pro UTC-Tag gezählt und nach Abkündigung, Client und SDK-Version gruppiert. Wenn keine Operation abgekündigt ist, ist der Bericht leer.

Die Umgebung ergibt sich immer aus dem API-Schlüssel; es gibt keinen Umgebungsparameter. Die Zeilen enthalten keine IP-Adresse, keinen `User-Agent` und keine Kennung von Endbenutzern.

## Anfrage

| Parameter | In | Erforderlich | Beschreibung |
|---|---|---|---|
| `from` | query | nein | Erster einzuschließender Tag, ein vollständiges Datum (`YYYY-MM-DD`, UTC). Standard ist `to` minus 30 Tage. Begrenzt durch den Berichtsverlauf Ihres Tarifs (siehe unten). |
| `to` | query | nein | Letzter einzuschließender Tag, ein vollständiges Datum (`YYYY-MM-DD`, UTC). Standard ist heute. `from` darf nicht nach `to` liegen. |
| `limit` | query | nein | Seitengröße, 1 bis 100. Standard 50. |
| `cursor` | query | nein | `next_cursor` der vorherigen Seite. Nur gültig für die Umgebung, `from` und `to`, für die er ausgestellt wurde. |

Zeilen sind sortiert nach `deprecation_id`, `client_id`, `sdk_package`, `sdk_version`. Beide Grenzen des Bereichs sind einschließend. Ein Cursor aus einem Standardbereich (ohne gesendete `from`/`to`) funktioniert nicht mehr, sobald sich der UTC-Tag ändert; senden Sie beim Paginieren `from` und `to` explizit.

### Berichtsverlauf nach Tarif

| Tarif | Verlauf |
|---|---|
| Free | 30 Tage |
| Startup, Business | 13 Monate |
| Enterprise | 25 Monate, begrenzt auf 400 Tage |

Die Berichtstabelle hält 400 Tage vor, daher reicht kein Tarif weiter als 400 Tage zurück. Ein `from`, das älter als der erlaubte Verlauf ist, schlägt mit `422 report_range_exceeds_plan` fehl; das früheste erlaubte Datum steht in der Meldung und in `errors[0].detail` (`earliest_allowed_date=YYYY-MM-DD`).

## Antwort

`200 OK`. `data` enthält die Zeilen der Seite; `next_cursor` ist auf der letzten Seite `null`.

| Feld | Beschreibung |
|---|---|
| `deprecation_id` | Kennung im Abkündigungsregister (`dep-YYYY-NN`). |
| `client_id` | `key_…` für einen API-Schlüssel für die Verwaltungs-API, `app_…` für einen OAuth-Client der Verwaltungs-API, `dashboard` für das Dashboard. |
| `sdk_package` | SDK-Paket aus dem Header `Idp-Client`; `other` für ein Paket außerhalb des Katalogs, `none`, wenn der Header fehlt. |
| `sdk_version` | SemVer-Version oder ein leerer String. |
| `call_count` | Aufrufe im Bereich. |
| `last_seen_at` | Letzter Aufruf im Bereich (RFC 3339, UTC). |
| `sunset_at` | Entfernungsdatum aus dem Abkündigungsregister (`YYYY-MM-DD`), `null`, wenn unbekannt. Ab diesem Tag antwortet die Operation mit `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

Senden Sie `Accept: text/csv`, um dieselben Spalten als CSV (RFC 4180) mit Kopfzeile zu erhalten. Textzellen, die mit `=`, `+`, `-`, `@`, einem Tabulator oder einem Wagenrücklauf beginnen, erhalten ein vorangestelltes einfaches Anführungszeichen, damit Tabellenkalkulationen sie nicht als Formeln ausführen. Der Cursor der nächsten Seite steht im Header `Link` (`rel="next"`); der Bereich ist in diesem Link ausgeschrieben.

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

## Hinweise

Zähler werden pro Minute erfasst und asynchron in den Bericht geschrieben, daher können die neuesten Aufrufe einige Minuten brauchen, bis sie erscheinen. Ein Absturz kann bis zu 60 Sekunden Zähler verlieren. Der Bericht ist keine Abrechnungsgrundlage.

## Fehler

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

| HTTP | `code` | Wann |
|---|---|---|
| 400 | `invalid_filter` | `from` oder `to` ist kein Datum im Format `YYYY-MM-DD`, ein Datum ist doppelt angegeben, oder `from` liegt nach `to`. |
| 400 | `invalid_cursor` | Der Cursor ist fehlerhaft oder wurde nicht für diese Umgebung und diesen Bereich ausgestellt. |
| 422 | `report_range_exceeds_plan` | `from` ist älter als der Berichtsverlauf Ihres Tarifs. |
| 422 | `validation_failed` | `limit` liegt außerhalb des gültigen Bereichs oder ein Parameter ist doppelt angegeben. |
| 401 | `unauthenticated` | Der API-Schlüssel fehlt, ist ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Der Schlüssel hat nicht `reports:read`. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; beachten Sie `Retry-After`. |
| 503 | `service_unavailable` | Der Berichtsdienst ist vorübergehend nicht verfügbar; versuchen Sie es später erneut. |

## Beispiel

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