Getting started with the Tracker API

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 pooled on-demand usage.

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, next scheduled run, and measurement/history state. auto_track_enabled: false is returned as tracking_mode: "benchmark" with effective_frequency: null and next_run_at: null. For recurring projects, effective_frequency comes from each platform’s own cadence: daily, weekly, or monthly when every platform shares one, or mixed with a frequency_breakdown count per cadence (request it with fields). next_run_at is the earliest scheduled run among cadences that have at least one platform, so a weekly-only project shows its next weekly run. Do not interpret the backward-compatible raw frequency field as proof of the schedule; Tracker schedules by platform.

2. Read project detail

curl "https://app.rankability.com/api/agent/v1/reporter/projects/PROJECT_ID?view=summary" \
  -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.

The backward-compatible API default is view=full. Use view=summary for ordinary reads or fields=keyword,spi,platforms_detail,next_run_at for an explicit top-level projection.

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?view=compact" \
  -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.

Compact result rows include position, mention, citation, URL, state, and change data. Request view=full only when complete stored answer_text, answer_excerpt, detected brands, citations, sentiment, or provider provenance is needed. Availability varies by platform and completed work; preserve null and unavailable states. Project-level data_state describes measurement (not_tracked, no_scan, failed, not_ranked, or measured); failed means the latest attempt ended before producing results and needs a rerun. Per-platform rows remain not_tracked, no_scan, not_ranked, or measured. comparison_state describes history (no_history or comparable).

For a client-wide keyword × platform table, call /reporter/matrix?client_id=CLIENT_ID instead of issuing one project-detail request per keyword. Paginate with limit and offset, and use the optional platforms filter when only selected surfaces are needed.

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 usage impact depends on the project’s selected platforms, resolved locations, Local Pack grid size, and tracked keyword count. Read the current estimate first with GET /api/agent/v1/usage/estimate?operation=trigger_scan&project_id=PROJECT_ID or MCP estimate_usage_impact with operation: "trigger_scan". 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 usage, rate limits, and errors before automating scans.
• Use Building a Looker Studio dashboard when you need a server-side, read-only reporting connector.