Getting started with the Tracker API

Connect a reporting integration to Rankability projects, read truthful result snapshots, and start scans only when required.

Use the Tracker API to read tracking projects, SPI, platform results, trends, and organization or brand summaries. The API retains the legacy /reporter path and reporter:* scope names for compatibility; Tracker is the product name. It can also manage projects and start scans, but most dashboard integrations should begin read-only.

Base path and scopes

https://app.rankability.com/api/agent/v1/reporter

Scope	Use it for
reporter:read	List projects and read detail, results, trends, and summaries
reporter:run	Start a scan on an existing project
reporter:write	Create, update, or delete tracking projects

A reporting dashboard normally needs only reporter:read. Grant run or write access only when the integration is intended to change Rankability state or consume scan credits.

1. List available projects

curl "https://app.rankability.com/api/agent/v1/reporter/projects?limit=50" \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

Optional filters are client_id, status=active|archived, limit up to 100, and offset. Use view=compact for portfolio discovery, view=full for every supported field, or fields=id,keyword,data_state to request an explicit field set. Default compact rows return platform_count instead of the full platform-name array and cap each page at 50 rows; paginate with offset. An explicit fields request can still return up to 100 rows and can request platforms when the names are actually needed.

Each compact row identifies its keyword, domain, platform count, status, tracking mode, and measurement/history state. auto_track_enabled: false is returned as tracking_mode: "benchmark" with effective_frequency: null. Do not interpret the backward-compatible raw frequency field as proof that a benchmark project is scheduled.

2. Read project detail

curl https://app.rankability.com/api/agent/v1/reporter/projects/PROJECT_ID \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

Project detail includes:

• Current configuration and tracking mode.

• SPI and its traditional, video, AI mention, AI citation, and local components, plus the canonical standard or local weight set. Unmeasured categories are null, and category_states distinguishes not_tracked, no_scan, and measured rather than zero-filling them.

• Current per-platform result summary, with data_state and comparison_state directly on each entry, including configured platforms with no result.

• The latest run and failed-platform list.

• A latest_per_platform snapshot map showing which run supplied each platform's current result.

The newest project run and the run supplying a platform's current result can differ. A newer partial or failed attempt does not erase an older successful result.

3. Read results with an explicit snapshot method

The default request is:

curl https://app.rankability.com/api/agent/v1/reporter/projects/PROJECT_ID/results \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

It uses snapshot=latest_per_platform, matching Tracker's current-data behavior. The response identifies:

• snapshot.method

• latest_run_id

• every result_run_id

• platform coverage and source runs

• the latest attempt's status and failed platforms

Use ?snapshot=latest_run when you need only the newest run, including its gaps. Use ?run_id=RUN_ID to retrieve one historical run. Never infer the snapshot method from only the top-level run object.

AI result rows can include the complete stored answer_text, shorter answer_excerpt, detected brands, mention and citation data, provider provenance, and capture time. Availability varies by platform and completed work; preserve null and unavailable states. data_state describes measurement (not_tracked, no_scan, not_ranked, or measured), while comparison_state describes history (no_history or comparable).

4. Read trends

curl "https://app.rankability.com/api/agent/v1/reporter/projects/PROJECT_ID/trends?days=30" \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

The allowed period is capped at 90 days. Trend points include completed and partial terminal runs, their coverage, SPI breakdown, and platform values. Do not present a partial point as fully covered.

5. Start a scan only when necessary

curl -X POST https://app.rankability.com/api/agent/v1/reporter/projects/PROJECT_ID/scan \
  -H "Authorization: Bearer rk_live_YOUR_KEY" \
  -H "Idempotency-Key: tracker-scan-PROJECT_ID-2026-08-14"

The key needs reporter:run. The response returns HTTP 201, a run_id, and status: "queued". Continue reading project results until that run reaches a terminal state.

A scan cannot start for an archived project. If the latest run is already pending or running, the endpoint returns 409 conflict with that run ID instead of creating another scan.

Scan cost is not flat. It depends on the project's selected platforms, resolved locations, and Local Pack grid size. Read the current estimate first with GET /reporter/projects/PROJECT_ID/scan-estimate or MCP estimate_cost with operation: "trigger_scan". The same credit rules used by the in-app Tracker apply. Do not schedule repeated manual scans merely because a polling request has not finished.

Next steps

• Use Tracker API endpoint reference for project creation, summaries, and all routes.

• Use Understanding SPI before presenting the score outside Rankability.

• Use Reading traditional and video search results, Reading AI answers, and Reading AI citations to preserve result semantics.

• Review API credits, rate limits, and errors before automating scans.

• Use Building a Looker Studio dashboard when you need a server-side, read-only reporting connector.