Skip to main content

REST API

Last updated

Authentication

Base URL https://rankvitals.io/api/v1, authenticated with Authorization: Bearer rv_live_…. Create a key under Dashboard → API & MCP. A test spends one credit from your plan; uptime checks and reads are free, and on the free plan a single Lighthouse test spends nothing — it is rate-limited rather than metered, and a429 with free_tier_rate_limited tells you when to retry.

A key with read scope can use GET endpoints. Starting a test with POST /tests requires write scope. Keys may also have an expiry; expired keys return 401 with API key expired, while a missing scope returns 403.

Start a test

curl -X POST https://rankvitals.io/api/v1/tests \
  -H "Authorization: Bearer rv_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "type": "lighthouse", "device": "mobile"}'

# → { "id": "…", "status": "queued", "report_url": "…" }
# type: "lighthouse" (speed test) | "seo_crawl" (SEO + AI-readiness audit) | "uptime" (free uptime check)

Poll results

curl https://rankvitals.io/api/v1/tests/TEST_ID \
  -H "Authorization: Bearer rv_live_YOUR_KEY"

# → scores, grade, vitals, audits, seo_issues, report_url
# status: queued → running → completed | failed

Prefer not to poll? Pass a callback_url and let RankVitals notify you instead — see webhooks.

Artifacts and HAR

A completed Lighthouse test also exposes its captured artifacts (screenshots, filmstrip frames, the raw Lighthouse JSON) and the network waterfall as a HAR file.

curl https://rankvitals.io/api/v1/tests/TEST_ID/artifacts -H "Authorization: Bearer rv_live_YOUR_KEY"
curl https://rankvitals.io/api/v1/tests/TEST_ID/har       -H "Authorization: Bearer rv_live_YOUR_KEY"

List tests and credits

curl https://rankvitals.io/api/v1/tests   -H "Authorization: Bearer rv_live_YOUR_KEY"
curl https://rankvitals.io/api/v1/credits -H "Authorization: Bearer rv_live_YOUR_KEY"

Pagination and filtering

GET /tests supports keyset pagination and filters. The response includes next_cursor — pass it back as cursor; null means the end.

curl "https://rankvitals.io/api/v1/tests?limit=25&status=completed&type=lighthouse&cursor=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer rv_live_YOUR_KEY"

Idempotency

Send an Idempotency-Key header (≤128 chars) with POST /tests. Retries within 24 hours return the original test with "replayed": true instead of spending another credit. In CI, the commit SHA makes a good key — see CI integration.

Rate limits

60 requests/min per key for reads, 10/min for POST /tests. A 429 response carries a Retry-After header; honour it rather than backing off blindly.

OpenAPI spec

The full machine-readable spec lives at https://rankvitals.io/api/v1/openapi.json (OpenAPI 3.1, unauthenticated) — import it into Postman, Insomnia or a client generator. A unit test enumerates the route files and fails the build if an endpoint ships without a spec entry, so it cannot fall behind the API.