> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-reporter-getting-started.md).

# 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

```bash
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`. Do not interpret the backward-compatible raw `frequency` field as proof that a benchmark project is scheduled.

## 2. Read project detail

```bash
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:

```bash
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. `data_state` describes measurement (`not_tracked`, `no_scan`, `not_ranked`, or `measured`), while `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

```bash
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

```bash
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](/api/api-reporter-endpoints.md) for project creation, summaries, and all routes.
* Use [Understanding SPI](/track/understanding-spi.md) before presenting the score outside Rankability.
* Use [Reading traditional and video search results](/track/traditional-search-tab.md), [Reading AI answers](/track/ai-answers-tab.md), and [Reading AI citations](/track/ai-citations-tab.md) to preserve result semantics.
* Review [API usage, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md) before automating scans.
* Use [Building a Looker Studio dashboard](/api/api-reporter-looker-studio.md) when you need a server-side, read-only reporting connector.