API de análise da SERP

Execute análises via API REST com a sua própria chave.

Autenticação

Crie uma chave na sua A sua conta e envie-a no cabeçalho X-API-Key em cada pedido. Cada análise consome 1 crédito do seu saldo ou do saldo da sua equipa.

Iniciar uma análise

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": "pt"
}

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

Obter o resultado

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

Consulte a cada poucos segundos até status ser completed. O campo report contém então o JSON completo: síntese executiva, ações priorizadas e as secções lacuna semântica, lacuna de UX e preparação para IA.

Resposta:

{
  "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": { … }
}

Estados da análise

status passa por queued e running e para depois num de três valores terminais: completed, failed ou canceled. Interrompa o polling nos três casos — em failed e canceled o campo error indica o motivo e report fica null.

Limites de frequência

Até 60 pedidos por hora e por conta, e 3 análises em curso simultaneamente. Ao exceder um dos dois limites o endpoint responde 429: aguarde e tente novamente.

Erros

401 — chave API inválida ou revogada
402 — créditos insuficientes
404 — id de análise inexistente
405 — método HTTP incorreto (analyze aceita apenas POST)
422 — dados inválidos (url, query, country, language)
429 — demasiados pedidos, tente mais tarde

Criar chave API