Add keywords
Start tracking up to 50 keywords on a website, on every search engine connected to it.
https://api.rankparse.com/v1/rank-tracking/keywordsFreeAPI key (owner, admin, member or client with edit access)Adds keywords to one website's tracked set. A keyword belongs to the website, not to a search engine: every engine with a property attached to that website (Google, Bing, Yandex) tracks it from the next sync. There is no country or device to choose, because those are breakdowns of the stored data: read them with Get rankings and Get keyword history.
Rankings for a new keyword appear after the next daily sync, usually within a day.
Query parameters
site_idstringrequiredThe website, from List sites. A missing or unknown ID returns 404 rank_tracking_site_not_found.
Body parameters
keywordsarray of stringsrequiredThe keywords to track, one phrase per entry. At most 50 per call, each at most 200 characters. Blank entries are dropped, and entries that differ only by letter case or surrounding spaces count as one. Anything else returns 400 invalid_rank_tracking_keywords.
Response
site_idstringThe website you changed.
addedarrayThe keywords that were new, as { keyword_id, keyword }. Use the keyword_id with Get keyword history and Remove keywords.
already_trackedarray of stringsKeywords you sent that the website already tracks, in any letter case. They are not duplicated.
tracked_totalintegerHow many keywords the website tracks now.
notestringWhen the new keywords start to show rankings.
Behavior and limits
- Credits: 0.
- Idempotent: sending the same keywords again adds nothing and lists them under
already_tracked. - Limits: a website tracks at most 100 keywords (
400 rank_tracking_keyword_limit), and its plan may allow fewer. Past the plan's limit the call returns402 plan_limit_reachedand adds nothing. - All or nothing: a call that fails a limit adds none of its keywords.
Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_rank_tracking_keywords | The body is not a JSON object, keywords is missing, empty, not an array of strings, longer than 50, or has an entry over 200 characters. |
| 400 | rank_tracking_keyword_limit | The website would track more than 100 keywords. |
| 401 | invalid_api_key | Missing, invalid or revoked API key. |
| 402 | plan_limit_reached | The plan's keywords-per-website limit is reached. |
| 403 | capability_missing | Your role may not edit tracked keywords. |
| 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: add_tracked_keywords (accepts site_id and keywords; safe to repeat).