Rank tracking
Create trackers, estimate a check before running it, add and remove keywords, and read positions over time.
A tracker pins a domain, a set of keywords, a market, a device choice, and a SERP depth, and records positions each time it is checked. Creating, editing, and reading trackers is free. Running a check costs credits, and the cost is known exactly before you commit: see the cost model.
create_rank_tracker
Create a tracker. Free to create; each check costs credits. Call estimate_rank_tracker_cost afterwards and report the number before committing anyone to a schedule.
| Argument | Type | Required | Default | Meaning |
|---|---|---|---|---|
projectId | string | yes | ||
keywords | string[], 1 to 1,000 items, each up to 200 chars | yes | Keywords to track. | |
domain | string | no | project domain | Domain to track. |
locationCode | integer | no | project market | |
languageCode | string | no | project market | |
devices | both, desktop, or mobile | no | both | both doubles the cost of every check. |
serpDepth | 10, 20, 30, 50, or 100 | no | 100 | How deep to read the SERP. Deeper costs more. The dashboard's default is 20. |
scheduleInterval | daily, weekly, monthly, or manual | no | manual | manual never runs by itself and is the only option on the Free plan; the others require a paid plan. |
locationName | string, up to 255 chars | no | national | A canonical location name such as Austin,Texas,United States switches the tracker to city-level results. Omit for national tracking. |
Subject to the plan's tracker limit (workspace-wide) and, for a schedule other than manual, to the scheduled-tracking plan feature. The project must have a domain or the call must pass one.
get_rank_tracker
List the project's trackers, or inspect one. Free; reads stored snapshots. This is also the tool to poll after run_rank_tracker.
| Argument | Type | Required | Meaning |
|---|---|---|---|
projectId | string | yes | |
configId | string | no | Tracker to inspect. Omit to list every tracker on the project. |
With a configId, returns the settings, the tracked keywords with ids, the latest position per keyword and device, and the last 10 runs. A blank position means the domain was not found within the tracker's depth.
estimate_rank_tracker_cost
What one check of a tracker will cost in credits, and roughly how long it will take. Free. Call it before run_rank_tracker: a large tracker can cost thousands of credits per run.
| Argument | Type | Required | Default | Meaning |
|---|---|---|---|---|
projectId | string | yes | ||
configId | string | yes | ||
trigger | manual or scheduled | no | manual | manual prices a live check (faster, about three times the cost); scheduled prices a queued one. |
Returns: keywordCount, checks (keywords times devices), costCredits, costUsd, estimatedSeconds, and the method priced.
add_rank_tracking_keywords
Add keywords to an existing tracker. Free to add, but every future check costs more; re-run the estimate afterwards.
| Argument | Type | Required |
|---|---|---|
projectId | string | yes |
configId | string | yes |
keywords | string[], 1 to 1,000 items | yes |
remove_rank_tracking_keywords
Stop tracking keywords. Position history is kept, so removing and re-adding a keyword loses nothing.
| Argument | Type | Required | Meaning |
|---|---|---|---|
projectId | string | yes | |
configId | string | yes | |
keywordIds | string[], 1 to 1,000 items | yes | Tracked-keyword ids from get_rank_tracker, not the keyword text. |
run_rank_tracker
Trigger an immediate live position check. Spends credits, often a lot. Returns at once with a runId; poll get_rank_tracker for results.
| Argument | Type | Required | Meaning |
|---|---|---|---|
projectId | string | yes | |
configId | string | yes | |
maxCostCredits | integer | no | Refuse to run, at no cost, if the estimate exceeds this many credits. |
The budget is checked before anything is launched, and again inside the run against a fresh estimate, so a stale estimate cannot overspend. Only one check per tracker can be in flight; a second trigger while one is running fails rather than double-spending.
The cost model
Rank checks are the one operation with a published, pre-computed price. One check is one keyword on one device at the tracker's depth. Depth 10 is one page of results, depth 20 two pages, and so on.
| First page | Each additional page | |
|---|---|---|
| Live (manual checks) | $0.002 | $0.0015 |
| Queued (scheduled checks) | $0.0006 | $0.00045 |
Each metered call is marked up by 1.28, rounded to five decimals, and converted at 1,000 credits per dollar, rounding up per call. Live checks are one call per check; queued checks are batched up to 100 per call, which is why scheduled tracking is about 30% of the price of a manual run.
Worked example, 100 keywords, both devices (200 checks), depth 20:
- Manual run: each check costs ($0.002 + $0.0015) × 1.28 = $0.00448, which rounds up to 5 credits. 200 checks cost 1,000 credits.
- Scheduled run: each check costs ($0.0006 + $0.00045) × 1.28 = $0.001344. A batch of 100 checks is $0.1344, or 135 credits. 200 checks cost 270 credits; daily, that is about 8,100 credits a month; weekly, about 1,080.
The estimate tool does this arithmetic for you and is exact, with one caveat: a queued task that is rejected or times out can incur a live fallback, so a scheduled month can cost slightly more than the nominal figure.