Esta página ainda não foi traduzida para Português. Exibindo o original em inglês.

GET /datasets/app-rankings

App ranking snapshots

A per-period ranking of the applications that consume the most tokens. The apps counted are the ones that identify themselves with HTTP-Referer and X-Title.

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

What this data is

Authentication

Authorization: Bearer <key> is required. Both inference and management keys are accepted; without a key you get 401 invalid_api_key. openrouter requires a key for this dataset too, so we kept the same rule — and since this runs no inference, it spends no credit.

Why one period at a time

Rows are never deleted: our own usage records may reference an app row, so rows from older periods stay. Mixing periods in one response would produce duplicate rank values and stop being a ranking at all. So this endpoint returns exactly one period — the most recent period_end by default, or an earlier one selected with end_date.

Request parameters

end_datestring

YYYY-MM-DD. Selects the most recent single period ending on or before this date. Omitted, it is the most recent period overall. A malformed value returns 400.

limitnumber

Maximum apps to return: an integer from 1 to 100, default 50.

offsetnumber

How many apps to skip: an integer of 0 or more, default 0. rank is absolute, so the first row of offset=50 is rank: 51.

categorystring

Filter by classification. Must match the stored value exactly.

subcategorystring

Filter by sub-classification. Combined with category, both conditions apply.

Request example

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

Response

The body is {"data": [ … ], "meta": { … }}.

app_idnumber | null

The source dataset's app id. The field name follows openrouter — our column name (external_app_id) never appears in the response. Rows without an id are not stored at all (an unidentified row would only accumulate duplicates on every sync), so every row in the response has a value.

app_namestring

The app's name.

ranknumber | null

Rank within the period.

total_requestsnumber | null

Requests during the period.

total_tokensstring | null

Tokens during the period. Stored as NUMERIC(30,0), so it is emitted as a string. Parse it as a BigInt.

urlstring | null

The app's address: the source's origin_url if present, otherwise main_url.

descriptionstring | null

The app's description, exactly as the source wrote it.

categorystring | null

Classification — the first entry of the categories array the source provides.

subcategorystring | null

The second entry of that array, or null.

growth_pctnumber | null

Percentage change against the previous period. null — not zero — when the source does not supply it.

period_startstring | null

First day of the period (YYYY-MM-DD).

period_endstring | null

Last day of the period (YYYY-MM-DD). Every row in one response shares this value.

sourcestring

openrouter or fixture. fixture means sample data.

synced_atstring

When the row was last refreshed (ISO 8601, UTC).

meta reports the period actually read: as_of, start_date, end_date, limit, offset, version. When there is no data at all, as_of, start_date and end_date are all null.

Response example

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"
  }
}

When the data is empty, or a sample

Situation	Response	How you can tell
Normal sync	Real data	`source: "openrouter"`
No key, fixture mode on	Sample data	`source: "fixture"`, and the site shows a "sample data" badge
No key, fixture mode off	`{"data": [], "meta": {"end_date": null, …}}` with status 200	An empty array

The "source": "fixture" in the example above is what this service actually returns today — the real-data sync key is not configured yet.

Getting your app into this list

You cannot. This is openrouter's aggregation, and we do not send usage there.

Attribution does count in our aggregation, though. Send HTTP-Referer and X-Title (or X-MyIP-Title) with a request and those values are recorded against the usage, which lets the dashboard's activity screen break spend down per app. See App attribution.

Errors

Status	`error_type`	When
400	`invalid_request`	`end_date` is not `YYYY-MM-DD`; `limit` is not an integer from 1 to 100; `offset` is not an integer of 0 or more
401	`invalid_api_key`	No header. A token without one of our prefixes. An unknown, switched-off, or revoked key
401	`expired_api_key`	The key has expired
402	`insufficient_credits`	The key is `suspended_no_credit`
403	`key_suspended`	An administrator suspended the key
500	`server`	Any other server-side failure

No data is not an error: it comes back as {"data": []} with status 200.

GET /datasets/rankings-daily — daily model usage
GET /benchmarks — benchmark snapshots
App attribution — HTTP-Referer and X-Title
Errors and debugging — the full error_type table

Última atualização: 5 de set. de 2026