# 非推奨の利用状況レポート

`GET /v1/reports/deprecation-usage` · 権限 `reports:read`

削除が予定されている操作をまだ呼び出しているクライアントを示します。削除日の前に移行できます（[バージョニングポリシー](/docs/policies/versioning)を参照）。呼び出しは UTC の日単位で数えられ、非推奨、クライアント、SDK バージョンごとにグループ化されます。非推奨の操作がない場合、レポートは空です。

環境は常に API キーから決まります。環境のパラメーターはありません。行には IP アドレス、`User-Agent`、エンドユーザーの識別子は含まれません。

## リクエスト

| パラメーター | 位置 | 必須 | 説明 |
|---|---|---|---|
| `from` | query | いいえ | 対象に含める最初の日。完全な日付（`YYYY-MM-DD`、UTC）。既定値は `to` の 30 日前です。プランのレポート履歴（下記）で制限されます。 |
| `to` | query | いいえ | 対象に含める最後の日。完全な日付（`YYYY-MM-DD`、UTC）。既定値は今日です。`from` は `to` より後にできません。 |
| `limit` | query | いいえ | ページサイズ。1～100。既定値 50。 |
| `cursor` | query | いいえ | 前のページの `next_cursor`。発行された環境、`from`、`to` に対してのみ有効です。 |

行は `deprecation_id`、`client_id`、`sdk_package`、`sdk_version` の順に並びます。範囲の両端は含まれます。既定の範囲（`from`/`to` を送らない）で得たカーソルは、UTC の日付が変わると使えなくなります。ページを送る際は `from` と `to` を明示してください。

### プランごとのレポート履歴

| プラン | 履歴 |
|---|---|
| Free | 30 日 |
| Startup、Business | 13 か月 |
| Enterprise | 25 か月（400 日が上限） |

レポートのテーブルは 400 日分を保持するため、どのプランも 400 日より前には遡れません。許可された履歴より古い `from` は `422 report_range_exceeds_plan` で失敗します。許可された最も早い日付はメッセージと `errors[0].detail`（`earliest_allowed_date=YYYY-MM-DD`）に含まれます。

## レスポンス

`200 OK`。`data` にはそのページの行が入ります。`next_cursor` は最後のページで `null` になります。

| フィールド | 説明 |
|---|---|
| `deprecation_id` | 非推奨レジストリの識別子（`dep-YYYY-NN`）。 |
| `client_id` | 管理 API キーは `key_…`、管理 OAuth クライアントは `app_…`、ダッシュボードは `dashboard`。 |
| `sdk_package` | `Idp-Client` ヘッダーの SDK パッケージ。カタログ外のパッケージは `other`、ヘッダーがない場合は `none`。 |
| `sdk_version` | SemVer のバージョン、または空文字列。 |
| `call_count` | 範囲内の呼び出し数。 |
| `last_seen_at` | 範囲内の最後の呼び出し（RFC 3339、UTC）。 |
| `sunset_at` | 非推奨レジストリの削除日（`YYYY-MM-DD`）。不明な場合は `null`。この日以降、操作は `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

`Accept: text/csv` を送ると、同じ列がヘッダー行付きの CSV（RFC 4180）で返ります。`=`、`+`、`-`、`@`、タブ、またはキャリッジリターンで始まるテキストのセルには、表計算ソフトが数式として実行しないよう、先頭に一重引用符が付けられます。次のページのカーソルは `Link` ヘッダー（`rel="next"`）にあり、範囲はそのリンクに明記されます。

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

## 注記

カウントは 1 分ごとに収集され、非同期にレポートへ書き込まれるため、最新の呼び出しが表示されるまで数分かかることがあります。障害が起きた場合、最大 60 秒分のカウントが失われることがあります。このレポートは課金の入力データではありません。

## エラー

すべてのエラーは、安定した `code` を持つ `application/problem+json` 形式のボディです。

| HTTP | `code` | 発生条件 |
|---|---|---|
| 400 | `invalid_filter` | `from` または `to` が `YYYY-MM-DD` 形式の日付ではない、日付が重複している、または `from` が `to` より後。 |
| 400 | `invalid_cursor` | カーソルの形式が不正、またはこの環境と範囲に対して発行されていない。 |
| 422 | `report_range_exceeds_plan` | `from` がプランのレポート履歴より古い。 |
| 422 | `validation_failed` | `limit` が範囲外、またはパラメーターが重複している。 |
| 401 | `unauthenticated` | API キーがない、無効、または失効している。 |
| 403 | `insufficient_permissions` | キーに `reports:read` がない。 |
| 429 | `rate_limited` | レート制限を超えた。`Retry-After` に従ってください。 |
| 503 | `service_unavailable` | レポートサービスが一時的に利用できない。後で再試行してください。 |

## 例

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