Rank check resource
status can be running, completed, or failed. run_id identifies the
rank-check run that produced the row. It is null for legacy rows that predate
runs. A queued request creates its history row when execution begins; workers
or inline execution later update that row to completed, or persist a failed
row with an error message when the provider run fails.
attempts records provider fallback attempts ({ "provider", "message" })
before the final status; it is null when no fallback attempts were recorded.
List rank checks for a keyword
Response:
Get one rank check
404. Use this endpoint after a history row
has provided the rank-check id. A queued request returns a run ID, not a
rank-check ID, so correlate it through the keyword history first.
Export project rank history
JSON uses the standard
data and meta.next_cursor envelope. Every row includes
keyword_id, keyword, checked_at, position, previous_position, and
ranking_url, plus provider, requested_depth, and normalization_version.
Only completed rank checks are included.
Send Accept: text/csv or format=csv for a streamed CSV download. CSV exports
include the same fields and are not cursor-paginated.
Async polling flow
202 with { "id": "rcr_...", "status": "queued" } when the
workflow is queued. Poll GET /keywords/{id}/rank-checks?status=completed and
select the row whose run_id equals that queued run ID. The matching row holds
the final position and rank-check ID. If the queue worker is unavailable, the
request returns 503 and no run is kept.