Tracker API endpoint reference

Reference the current Rankability Tracker API routes for projects, scans, result snapshots, trends, and summaries.

Tracker API resources are scoped to the authenticated organization. The legacy /reporter route and reporter:* scope names remain for compatibility. An ID from another organization returns 404 not_found rather than revealing that resource.

Prefix every route with:

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

Start with Getting started with the Tracker API if you have not yet validated a read-only integration.

Project routes

Method	Path	Scope	Purpose
GET	/reporter/projects	reporter:read	List projects
POST	/reporter/projects	reporter:write	Create a project
GET	/reporter/projects/:id	reporter:read	Read configuration, SPI, platform summary, and latest run
PATCH	/reporter/projects/:id	reporter:write	Update supported project settings
DELETE	/reporter/projects/:id	reporter:write	Permanently delete a project

Create a project

POST /reporter/projects requires name and a non-empty keywords array. Each keyword item can be a string or { "keyword": "...", "targetDomain": "..." }.

The current route persists the first array item as the project's primary keyword. Send one keyword per create request when each keyword must have its own durable tracking project and route ID; do not assume every array item became a separate project.

Optional fields are:

• client_id — client UUID in the organization.

• target_domain and brand_name.

• gbp_location_name.

• platforms — defaults to Google organic, Bing, ChatGPT, Perplexity, and Gemini.

• location, location_lat, and location_lng.

• grid_size — 3x3, 5x5, or 7x7; defaults to 3x3.

• language — defaults to en.

• frequency — daily, weekly, or monthly; defaults to daily.

• platform_frequencies — platform-specific frequency map.

• auto_track_enabled — defaults to true; false creates benchmark tracking state.

Send Idempotency-Key when retrying project creation. Rankability enforces the organization's tracking-project plan allowance and validates client_id ownership.

Update or delete a project

PATCH /reporter/projects/:id can change name, target_domain, brand_name, gbp_location_name, platforms, location, frequency, platform_frequencies, and auto_track_enabled.

Disabling automatic tracking clears scheduling timestamps. Enabling it or changing platforms or frequencies recalculates the schedule.

DELETE permanently removes the tracking project. Treat it as an intentional destructive action; a read-only reporting connector does not need reporter:write.

Results and scan routes

Method	Path	Scope	Purpose
GET	/reporter/projects/:id/results	reporter:read	Read grouped platform results
GET	/reporter/projects/:id/trends	reporter:read	Read up to 90 days of terminal-run trends
GET	/reporter/projects/:id/scan-estimate	reporter:read	Estimate the current project configuration's scan cost
POST	/reporter/projects/:id/scan	reporter:run	Queue a manual scan

Result snapshots

GET /reporter/projects/:id/results supports:

• No query or snapshot=latest_per_platform — newest available successful result for each tracked platform or keyword.

• snapshot=latest_run — only the newest run.

• run_id=RUN_ID — one explicit historical run; this overrides the snapshot choice.

The response always identifies snapshot.method, latest_run_id, the result-source run IDs, coverage by platform, and the latest run status. The default can intentionally combine results from several runs after a partial or failed attempt.

Traditional rows preserve rank, change, URL, and engine data. AI rows can include answer_text, answer_excerpt, brand sentiment data, detected brands, mention position, citations, provider provenance, and capture time. snippet remains a compatibility alias for answer_excerpt.

Every platform snapshot includes separate measurement and history fields. data_state is not_tracked, no_scan, not_ranked, or measured. comparison_state is no_history or comparable when a current measurement exists, and otherwise null. These states are never interchangeable with numeric zero, and no_history is never a data_state value.

Project detail also places those fields directly on every platforms_detail entry, including configured platforms with no result, so consumers do not need to infer measurement state from omission, null, or false. SPI breakdown categories are null when unmeasured, with a parallel category_states map; a returned numeric zero therefore means a measured zero.

Trend semantics

GET /trends?days=30 defaults to 30 days and caps the request at 90. It includes complete and partial terminal runs. Every point identifies run_status and coverage so consumers can distinguish missing work from a fully completed scan.

Manual scans

GET /scan-estimate returns the credit estimate for the project's current platforms, location, and Local Pack grid without starting work. POST /scan returns a queued run_id; send a stable Idempotency-Key for retryable automation. It rejects archived projects with 400 invalid_operation and returns 409 conflict when a scan is already pending or running.

Summary routes

Method	Path	Scope	Purpose
GET	/reporter/summary	reporter:read	Organization or optional client-level SPI summary
GET	/reporter/brand-summary?client_id=...	reporter:read	Client AI mention and citation summary
GET	/reporter/seo-performance?client_id=...&days=28	reporter:read	Client GSC and GA4 organic-search performance from the client's connected Google integrations

/reporter/summary accepts an optional client_id. It returns project counts, explicit data/comparison states, average SPI, change from prior completed runs when available, platform coverage, and top movers. A summary with current measurements and no prior scan returns data_state: "measured" with comparison_state: "no_history". average_spi is null when no completed measurement exists, and spi_delta is null when no comparable history exists.

/reporter/brand-summary requires client_id. It uses the latest available result per platform and reports projects with and without data, citation and mention rates, counts, and per-platform breakdown. It is an aggregation, not a replacement for the underlying result evidence.

/reporter/seo-performance requires client_id and accepts days=7, 28, or 90. It reuses the Google Search Console and GA4 properties already connected to that Rankability client. The response includes current and previous totals, daily trends, GSC queries and pages, submitted sitemaps, and GA4 organic landing pages. Google refresh tokens remain inside Rankability and are never returned to the caller.

Common failures

• 400 invalid_input — invalid create/update payload or snapshot value.

• 400 invalid_operation — a scan was requested for an archived project.

• 403 forbidden — the key lacks the exact read, run, or write scope.

• 403 plan_limit_exceeded — project creation exceeds the organization's tracking allowance.

• 404 not_found — project, client, or run is absent or outside the organization.

• 409 conflict — a scan is already in progress.

Review API credits, rate limits, and errors before adding automatic retries or scan schedules.