# Rank tracking

> Create trackers, estimate a check before running it, add and remove keywords, and read positions over time.

Source: https://docs.indexzero.site/tools/rank-tracking



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](#the-cost-model).

## `create_rank_tracker` [#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` [#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` [#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_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` [#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` [#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 [#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.