Update alert settings
Turn a website's weekly rank-change email on or off, change its movement threshold or send it to another address.
https://api.rankparse.com/v1/rank-tracking/alert-settingsFreeAPI key (owner, admin or member)Changes the rank-change alert settings of one website. Only the fields you send change; anything you leave out keeps its current value. Send site_id in the query string and the fields in a JSON body. A client role gets 403 capability_missing.
Turning enabled on starts a real weekly email to the account address (or email_override) whenever meaningful changes exist. Confirm with the account owner before enabling it on someone else's behalf.
Query parameters
site_idstringrequiredThe website, from List sites. A missing or unknown ID returns 404 rank_tracking_site_not_found.
Body parameters
The body must be a JSON object. Anything else (missing, not JSON, an array) returns 400 invalid_rank_tracking_alert_settings. An empty object changes nothing and returns the current settings.
enabledbooleantrue turns on daily detection and the weekly email, false turns them off. Any other type returns 400 invalid_rank_tracking_alert_settings.
move_thresholdnumberAverage-position change that records a moved_up or moved_down event, from 1 to 50. Decimals are accepted. Outside that range, or not a number, returns 400 invalid_rank_tracking_alert_settings.
min_clicksintegerIgnore keywords with fewer clicks than this over the 28 days ending on their latest synced day, from 0 to 100000. 0 turns the filter off. Use it to stop low-traffic keywords, which swing a lot, from filling the weekly email. It applies to alerts detected from now on; events already recorded stay in history. Anything else returns 400 invalid_rank_tracking_alert_settings.
email_overridestring | nullAn email address that receives this website's lines instead of the account email, or null to go back to the account email. Anything else returns 400 invalid_rank_tracking_alert_settings.
Response
The full settings after the change, in the same shape as Get alert settings.
site_idstringThe website you changed.
enabledbooleanWhether alerts are on.
email_overridestring | nullThe override address, or null.
move_thresholdnumberThe movement threshold.
min_clicksintegerThe minimum-clicks filter, 0 when off.
last_detected_datestring | nullThe last UTC date detection ran for this website.
Behavior and limits
- Credits: 0.
- Idempotent: sending the same body twice leaves the same settings.
- Timing: detection runs once per UTC day, and emails go out on Sundays at 18:00 UTC. See Weekly rank-change emails.
Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_rank_tracking_alert_settings | The body is not a JSON object, enabled is not a boolean, move_threshold is outside 1 to 50, min_clicks is not a whole number from 0 to 100000, or email_override is not an email or null. |
| 401 | invalid_api_key | Missing, invalid or revoked API key. |
| 403 | capability_missing | Your role is client. |
| 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: update_rank_alert_settings (accepts site_id, enabled, move_threshold, min_clicks, email_override; safe to repeat).