SERP analysis API

Run analyses programmatically with a REST API and your own key.

Authentication

Create a key in your Your account and send it in the X-API-Key header on every request. Each analysis consumes 1 credit from your (or your team) balance.

Start an analysis

POST https://serptune.com/api/v1/analyze
X-API-Key: stk_xxxxxxxx.xxxxxxxx
Content-Type: application/json

{
  "url": "https://example.com/your-page",
  "query": "best running shoes",
  "country": "US",
  "language": "en",
  "report_locale": "en"
}

Response: { "uuid": "…", "status": "queued", "result_url": "https://serptune.com/api/v1/analysis?id=…" }

Fetch the result

GET https://serptune.com/api/v1/analysis?id=<uuid>
X-API-Key: stk_xxxxxxxx.xxxxxxxx

Poll every few seconds until status is completed. The report field then contains the full JSON: executive summary, prioritized actions, and the semantic-gap, UX-gap and AI-readiness sections.

Response:

{
  "uuid": "3f8a1c7e-5b42-4d19-9e6f-0a2b8c4d1e35",
  "status": "completed",
  "url": "https://example.com/your-page",
  "query": "best running shoes",
  "country": "US",
  "language": "en",
  "created_at": "2026-10-12 09:14:02",
  "completed_at": "2026-10-12 09:15:41",
  "error": null,
  "report": { … }
}

Analysis states

status goes through queued and running, then stops at one of three terminal values: completed, failed or canceled. Stop polling on any of the three — on failed and canceled the error field carries the reason and report stays null.

Rate limits

Up to 60 requests per hour per account, and 3 analyses running at the same time. Beyond either limit the endpoint answers 429: wait and retry.

Errors

401 — invalid or revoked API key
402 — insufficient credits
404 — unknown analysis id
405 — wrong HTTP method (analyze accepts POST only)
422 — invalid input (url, query, country, language)
429 — rate limited, try again later

Create API key