List alerts
Recorded rank-change alert events for one website, newest first, including ones left out of the weekly email.
https://api.rankparse.com/v1/rank-tracking/alertsFreeAPI keyLists the rank-change events recorded for one website, newest first. Events are recorded once a day while alerts are enabled for the website (see Update alert settings). This is the full history, including events that were left out of the weekly email because their net movement cancelled out. A keyword with no events simply had no significant moves.
Query parameters
site_idstringrequiredThe website, from List sites. A missing or unknown ID returns 404 rank_tracking_site_not_found.
limitintegerdefault 100Events per page, 1 to 100. An invalid or out-of-range value falls back to 100.
offsetintegerdefault 0Number of events to skip. An invalid value falls back to 0.
Response
site_idstringThe website you asked for.
totalintegerRecorded events for the website, for pagination.
limitintegerThe page size used.
offsetintegerThe offset used.
alertsarrayEvents, ordered by metric_date then detected_at, newest first.
Show propertiesHide properties
keyword_idstringThe keyword ID.
querystringThe tracked query text.
enginestringgoogle, bing or yandex.
property_idstringThe primary property the change was seen on.
metric_datestringThe synced day the change was measured on (YYYY-MM-DD).
alert_typestringSee the table below.
old_positionnumber | nullAverage position over the 7-day baseline before metric_date. null for new_ranking.
new_positionnumber | nullPosition on metric_date. null for lost_ranking.
detected_atintegerUnix time in milliseconds when the event was recorded.
digest_datestringThe UTC date of the daily detection run that recorded the event.
delivered_atinteger | nullUnix time in milliseconds when the event was included in a sent weekly email. null while pending, and for events that cancelled out or were never emailed.
Alert types
Detection compares each keyword's position on the property's freshest synced day with its average position over the 7 days before, per engine.
alert_type | Recorded when |
|---|---|
entered_top_3 | Now in positions 1 to 3, baseline outside them |
entered_top_10 | Now in positions 4 to 10, baseline outside the top 10 |
left_top_3 | Now outside the top 3 but still in the top 10, baseline inside the top 3 |
left_top_10 | Now outside the top 10, baseline inside it |
moved_up | Position improved by at least the website's move_threshold |
moved_down | Position worsened by at least move_threshold |
new_ranking | The keyword has a position now and none in the baseline |
lost_ranking | The keyword had a baseline position and has none now, and the provider's data covers the freshest day |
- Only the most specific boundary crossing is recorded per direction: entering the top 3 implies entering the top 10, so only
entered_top_3is recorded. moved_upandmoved_downare recorded independently of boundary events, so one day can produce both kinds.- Only keyword and engine pairs whose
availabilityisavailablegenerate events. A null position is never treated as a move, soprovider_limitedor pending engines produce nothing rather than a falselost_ranking.
Errors
| HTTP | Code | When |
|---|---|---|
| 401 | invalid_api_key | Missing, invalid or revoked API key. |
| 404 | rank_tracking_site_not_found | No website with that site_id in your workspace. |
| 429 | rate_limited | More than 60 requests per minute for this key. |
Related
MCP tool: list_rank_change_alerts (accepts site_id, limit, offset).