API

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

Authentication

Create a key in your account and send it in the X-API-Key header on every request. Each analysis consumes 1 credit from your (or your team's) 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.

Errors

401 — invalid or revoked API key
402 — insufficient credits
422 — invalid input (url, query, country, language)
429 — rate limited (try again later)

Create API key