Skip to main content
Planned. History routes are specified here so you can design against them; they return 404 until launch. Follow the changelog for the release date.
History endpoints return how a value changed over time: a model’s score on a benchmark, its rank in a category, or its price. Each plan sees a rolling window ending today.

​
Endpoints

Both require the history feature, which every plan includes. Each response counts as one data response toward your daily quota.

​
Model history

Points are daily. A single request may span at most 400 days; paginate by date for longer ranges.

​
Rankings history

​
Response shape

/v1/rankings/history has the same shape with category_id in place of model_id and kind fixed to ranking.
  • points are sorted ascending by date, one per day with recorded data. Days without a recorded value are absent, not interpolated.
  • benchmark_id and category_id identify the series a point belongs to when you did not narrow the request.
  • source is capture for values recorded by the nightly snapshot, or backfill for values reconstructed from a source table (pricing only).
  • payload carries kind-specific context (sample size, currency, position count). Its keys may grow; ignore ones you do not know.
  • window tells you what was actually served: plan_limit_from is the oldest date your plan may query (null means unlimited) and available_from is the first day with real data for this kind (null until collection has run).

​
Window clamping

from is clamped to the later of your plan window start and the launch date:
  • If from is inside your window, you get exactly what you asked for.
  • If you omit from, the API uses the later of the default start and window.plan_limit_from.
  • If you set from explicitly to a date before your window, the API returns 403 with error.code: "history_window_exceeded", param: "from", and the earliest date you may request in message. Clamp on your side or upgrade.
Windows are rolling: the earliest date you can request moves forward every day. A Community integration that stores history locally should fetch it while it is in the window.

​
Launch-date limitation

History is available from the launch date of history collection onward. Score and ranking history is not backfilled before that date: we record values from the moment collection started, and an upgrade to Commercial does not reveal earlier scores because none were recorded.
Pricing series may include older source data where we hold it (points marked source: "backfill"), but do not assume universal backfill. window.available_from always tells you the true earliest point for that kind. The launch date is published in the changelog when history ships.

​
Choosing between history and snapshots

Use history endpoints for a few models or a single category chart. Use bulk snapshots plus incremental updates when you need the full dataset over time — one snapshot costs one data response, whereas fetching history for every model costs one per model.