# 지원 중단 사용량 보고서

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

## 참고

카운트는 분 단위로 수집되어 비동기로 보고서에 기록되므로, 가장 최근 호출은 나타나는 데 몇 분이 걸릴 수 있습니다. 장애가 나면 최대 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
```