Get keyword history
Day-by-day stored ranking history for one keyword on one search engine, in total or per device.
https://api.rankparse.com/v1/rank-tracking/historyFreeAPI keyReturns the stored daily metrics for one keyword on one engine over a date range, plus the sync state of that keyword on the engine's primary property. History is always single-engine: engine is required and all is not accepted. Use Get rankings to compare engines first.
Query parameters
site_idstringrequiredThe website, from List sites.
keyword_idstringrequiredThe keyword, from List keywords. A keyword that does not belong to this website in your workspace (including an unknown site_id) returns 404 rank_tracking_keyword_not_found.
enginestringrequiredgoogle, bing or yandex. Missing, all or any other value returns 400 invalid_rank_tracking_engine. An engine not enabled for your account returns 400 rank_tracking_provider_disabled.
start_datestringrequiredFirst day, YYYY-MM-DD, inclusive.
end_datestringrequiredLast day, YYYY-MM-DD, inclusive. Both dates must be real calendar dates, start_date must not be after end_date, and the inclusive span is capped at 400 days. Anything else returns 400 invalid_rank_tracking_date.
dimensionstringdefault totaltotal returns one row per day. device returns one row per day per device, with a device field on each row. Any other value returns 400 invalid_rank_tracking_dimension.
Response
site_idstringThe website you asked for.
keyword_idstringThe keyword ID.
querystringThe tracked query text.
enginestringThe engine you asked for.
property_idstringThe primary property the rows come from.
property_urlstringThat property's URL.
availabilitystringState of this keyword on this engine. pending_first_sync when no sync state exists yet. See Engines and availability.
data_as_ofstring | nullYYYY-MM-DD the provider's data for this keyword covers.
last_attempt_atinteger | nullUnix time in milliseconds of the last sync attempt.
last_success_atinteger | nullUnix time in milliseconds of the last successful sync.
error_codestring | nullStable error code of the last failed attempt.
start_datestringThe range start used.
end_datestringThe range end used.
dimensionstringtotal or device, echoing the request.
rowsarrayStored days in the range, ascending by date (then by device).
Show propertiesHide properties
datestringYYYY-MM-DD.
clicksnumber | nullClicks that day.
impressionsnumber | nullImpressions that day.
ctrnumber | nullClick-through rate as a 0 to 1 fraction.
positionnumber | nullProvider-reported average position that day.
click_positionnumber | nullAverage position of the clicks that day, when the provider reports it.
devicestringOnly with dimension=device: desktop, mobile or tablet.
Behavior and limits
- Credits: 0.
- Gaps are not zeros. A date missing from
rowshad no synced observation. Never treat a gap as a zero or a dropped rank. - Device rows exist only where the provider synced them: always for Google, and for Yandex only when its per-device breakdown is switched on. Bing has none. An empty
devicehistory next to a populatedtotalhistory means "not synced per device", not "no traffic". - Bing and Yandex sync less often than Google and may report
provider_limited, meaning the provider did not return enough data, not that the keyword ranks nowhere.
Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_rank_tracking_engine | engine is missing, all, or not an engine. |
| 400 | rank_tracking_provider_disabled | The engine is not enabled for your account. |
| 400 | invalid_rank_tracking_date | A date is missing, malformed or not a real date, the dates are out of order, or the span exceeds 400 days. |
| 400 | invalid_rank_tracking_dimension | dimension is not total or device. |
| 400 | rank_tracking_property_not_attached | The keyword exists but the website has no primary property attached for that engine. |
| 401 | invalid_api_key | Missing, invalid or revoked API key. |
| 404 | rank_tracking_keyword_not_found | The keyword is not tracked on this website in your workspace, or the website does not exist or is archived. |
| 429 | rate_limited | More than 60 requests per minute for this key. |
Related
MCP tool: get_keyword_rank_history (accepts site_id, keyword_id, engine, start_date, end_date, dimension).