GET /datasets/app-rankings

앱 랭킹 스냅샷

기간별로 토큰을 많이 쓴 애플리케이션 순위다. HTTP-Referer/X-Title 로 자기를 밝힌 앱들이 집계 대상이다.

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

이 데이터가 무엇인가

인증

Authorization: Bearer <키> 가 필요하다. 추론 키와 관리 키 둘 다 받는다. 키가 없으면 401 invalid_api_key 다. openrouter 도 이 데이터셋에 키를 요구하므로 같은 규칙을 맞췄고, 추론이 아니므로 크레딧은 쓰지 않는다.

기간이 한 번에 하나인 이유

행은 지우지 않는다. 우리 사용 기록이 앱 행을 참조할 수 있어서 오래된 기간의 행도 그대로 남는다. 그래서 여러 기간을 섞어 돌려주면 rank 가 중복되어 순위표가 아니게 된다. 이 경로는 한 기간만 돌려준다 — 기본값은 가장 최근 period_end 이고, end_date 로 과거 기간을 지목할 수 있다.

요청 파라미터

end_datestring

YYYY-MM-DD. 이 날짜 이전(포함)의 기간 중 가장 최근 것 하나를 고른다. 생략하면 전체에서 가장 최근 기간이다. 형식이 다르면 400 이다.

limitnumber

돌려줄 최대 앱 수. 1~100 의 정수이며 기본값은 50 이다.

offsetnumber

건너뛸 앱 수. 0 이상의 정수이며 기본값은 0 이다. rank 는 절대값이므로 offset=50 의 첫 행은 rank: 51 이다.

categorystring

분류로 거른다. 저장된 값과 정확히 일치해야 한다.

subcategorystring

세부 분류로 거른다. category 와 함께 쓰면 두 조건이 모두 적용된다.

요청 예시

curl "https://openrouter.myip.co.kr/api/v1/datasets/app-rankings?limit=20&category=coding" \
  -H "Authorization: Bearer $MYIP_API_KEY"

응답

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

app_idnumber | null

원본 데이터셋의 앱 id. 필드명은 openrouter 를 따른다 — 우리 열 이름(external_app_id)은 응답에 나오지 않는다. id 가 없는 항목은 애초에 저장하지 않으므로(식별자 없는 행은 동기화마다 중복만 쌓인다) 응답의 모든 행에 값이 있다.

app_namestring

앱 이름.

ranknumber | null

해당 기간의 순위.

total_requestsnumber | null

기간 동안의 요청 수.

total_tokensstring | null

기간 동안의 토큰 수. NUMERIC(30,0) 이므로 문자열로 내보낸다. BigInt 로 받으라.

urlstring | null

앱 주소. 원본의 origin_url 을 우선 쓰고 없으면 main_url 을 쓴다.

descriptionstring | null

앱 설명. 원본이 준 문장 그대로다.

categorystring | null

분류. 원본이 배열로 주는 카테고리의 첫 번째 값이다.

subcategorystring | null

같은 배열의 두 번째 값. 없으면 null.

growth_pctnumber | null

직전 기간 대비 증감률(%). 원본이 주지 않으면 null 이다 — 0 이 아니라 null 이라는 점에 주의하라.

period_startstring | null

집계 시작일(YYYY-MM-DD).

period_endstring | null

집계 종료일(YYYY-MM-DD). 한 응답의 모든 행이 같은 값을 갖는다.

sourcestring

openrouter 또는 fixture. fixture 는 샘플 데이터라는 뜻이다.

synced_atstring

마지막 갱신 시각(ISO 8601 UTC).

meta 는 어떤 기간을 실제로 읽었는지를 되돌려준다: as_of, start_date, end_date, limit, offset, version. 데이터가 하나도 없으면 as_of·start_date·end_date 가 모두 null 이다.

응답 예시

json

{
  "data": [
    {
      "app_id": 3067167,
      "app_name": "Hermes Agent",
      "rank": 1,
      "total_requests": 119006782,
      "total_tokens": "11318694593497",
      "url": "https://hermes-agent.nousresearch.com/",
      "description": "An open-source, self-improving AI agent that runs persistently with memory across sessions.",
      "category": "personal-agent",
      "subcategory": "cli-agent",
      "growth_pct": null,
      "period_start": "2026-08-28",
      "period_end": "2026-09-03",
      "source": "fixture",
      "synced_at": "2026-09-04T20:12:57.316Z"
    }
  ],
  "meta": {
    "as_of": "2026-09-04T20:12:57.316Z",
    "start_date": "2026-08-28",
    "end_date": "2026-09-03",
    "limit": 50,
    "offset": 0,
    "version": "v1"
  }
}

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

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

위 예시의 "source": "fixture" 는 실제로 지금 이 서비스가 돌려주는 값이다 — 아직 실데이터 동기화 키가 없다.

내 앱을 이 목록에 올리려면

올릴 수 없다. 이것은 openrouter 쪽 집계이고 우리가 그쪽으로 사용량을 보내지 않는다.

다만 우리 쪽 집계에는 앱 표기가 반영된다. 요청에 HTTP-Referer 와 X-Title(또는 X-MyIP-Title)을 붙이면 그 값이 사용 기록에 남고 대시보드 활동 화면에서 앱별로 갈라 볼 수 있다. 앱 표기를 보라.

오류

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

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