GET /datasets/rankings-daily

일별 모델 사용량 스냅샷

모델별 일일 처리 토큰 랭킹이다. 어떤 모델이 실제로 얼마나 쓰이는지를 날짜 단위로 본다.

GET https://openrouter.myip.co.kr/api/v1/datasets/rankings-daily

이 데이터가 무엇인가 — 그리고 무엇이 아닌가

우리 자신의 사용량으로 전환할 자리는 열어 두었다. 각 행의 source 가 openrouter 면 외부 스냅샷, internal 이면 우리 사용 기록에서 집계한 값, fixture 면 샘플 데이터다.

인증

Authorization: Bearer <키> 가 필요하다. 추론 키와 관리 키 둘 다 받는다. 키가 없으면 401 invalid_api_key 다.

요청 파라미터

start_datestring

YYYY-MM-DD. 이 날짜(포함) 이후의 행만 돌려준다. 생략하면 end_date 기준 30일 창이다. 형식이 다르면 400 이다.

end_datestring

YYYY-MM-DD. 이 날짜(포함)까지. 생략하면 그 modality 에 있는 가장 최근 날짜다.

modalitystring

기본값 text. 저장된 modality 값과 정확히 일치하는 행만 남긴다.

limitnumber

돌려줄 최대 행 수. 1~5000 의 정수이며 기본값은 1000 이다. 정렬은 날짜 내림차순 → 순위 오름차순이므로, 작은 limit 은 최신 날짜의 상위권부터 채운다.

요청 예시

curl "https://openrouter.myip.co.kr/api/v1/datasets/rankings-daily?start_date=2026-08-28&end_date=2026-09-03&limit=50" \
  -H "Authorization: Bearer $MYIP_API_KEY"

응답

{"data": [ … ], "meta": { … }} 형태다.

datestring

집계 날짜(YYYY-MM-DD).

model_permaslugstring

원본 데이터셋이 쓰는 모델 식별자. 우리가 서빙하지 않는 모델도 그대로 들어 있다.

model_idstring | null

model_permaslug 를 우리 카탈로그와 맞춰 본 결과. 맞는 모델이 없으면 null 이고, 그때는 model_permaslug 를 그대로 보여 주면 된다. model_id 가 있는 행만 GET /models 로 이어진다.

total_tokensstring

그날 처리된 토큰 수. NUMERIC(30,0) 이라 배정도 실수로 정확히 표현되지 않는 크기가 나올 수 있어 문자열로 내보낸다. BigInt 로 받으라.

ranknumber | null

그날의 순위(1부터). 원본의 순위를 그대로 쓰지 않고 우리가 다시 매긴다 — 같은 모델의 변종 행을 합치기 때문에 원본 순위와 어긋난다.

modalitystring

text 등.

categorystring | null

카테고리별 랭킹의 카테고리. 전역 랭킹에서는 null.

sourcestring

openrouter · internal · fixture 중 하나. fixture 는 샘플 데이터라는 뜻이다.

synced_atstring

이 행이 마지막으로 갱신된 시각(ISO 8601 UTC).

meta 는 어떤 창을 실제로 읽었는지를 되돌려준다.

meta.as_ofstring | null

돌려준 행들의 synced_at 중 가장 최근 값. 데이터가 없으면 null.

meta.start_datestring | null

실제로 적용된 창의 시작일. 생략했을 때 우리가 무엇으로 채웠는지 여기서 확인한다.

meta.end_datestring | null

실제로 적용된 창의 끝. 데이터가 하나도 없으면 null.

meta.modalitystring

적용된 modality.

meta.versionstring

v1 고정. 응답 형상이 바뀌면 이 값이 바뀐다.

응답 예시

json

{
  "data": [
    {
      "date": "2026-09-03",
      "model_permaslug": "google/gemma-4-26b-a4b",
      "model_id": "google/gemma-4-26b-a4b",
      "total_tokens": "11948458704035",
      "rank": 1,
      "modality": "text",
      "category": null,
      "source": "fixture",
      "synced_at": "2026-09-04T20:12:54.274Z"
    },
    {
      "date": "2026-09-03",
      "model_permaslug": "lgai/exaone-4.0-32b",
      "model_id": "lgai/exaone-4.0-32b",
      "total_tokens": "11597347917470",
      "rank": 2,
      "modality": "text",
      "category": null,
      "source": "fixture",
      "synced_at": "2026-09-04T20:12:54.274Z"
    }
  ],
  "meta": {
    "as_of": "2026-09-04T20:12:54.274Z",
    "start_date": "2026-08-05",
    "end_date": "2026-09-03",
    "modality": "text",
    "version": "v1"
  }
}

데이터가 비어 있거나 샘플일 때

동기화는 OPENROUTER_API_KEY 가 있어야 실데이터를 받는다. 키가 없으면 잡은 skipped 로 끝나고, 정책이 픽스처 모드를 가리키면 저장소에 넣어 둔 샘플 스냅샷을 적재한다.

상황	응답	어떻게 알아채나
정상 동기화	실데이터	`source: "openrouter"`
키 없음 + 픽스처 모드	샘플 데이터	`source: "fixture"`. 사이트 화면에는 "샘플 데이터" 배지가 뜬다
키 없음 + 픽스처 꺼짐	`{"data": [], "meta": {"end_date": null, …}}` (200)	빈 배열

오류

상태	`error_type`	언제
400	`invalid_request`	`start_date`·`end_date` 가 `YYYY-MM-DD` 가 아님. `start_date` 가 `end_date` 보다 늦음. `limit` 이 1~5000 정수가 아님
401	`invalid_api_key`	헤더 없음. 우리 접두사가 아닌 토큰. 없거나 꺼졌거나 폐기된 키
401	`expired_api_key`	키가 만료됨
402	`insufficient_credits`	키가 `suspended_no_credit` 상태
403	`key_suspended`	관리자가 정지한 키
500	`server`	그 밖의 서버 오류

데이터가 없는 것은 오류가 아니다. {"data": []} 를 200 으로 돌려준다.