API de análisis de SERP

Ejecuta análisis mediante una API REST con tu clave.

Autenticación

Crea una clave en tu Tu cuenta y envíala en la cabecera X-API-Key en cada petición. Cada análisis consume 1 crédito del saldo tuyo o de tu equipo.

Iniciar un análisis

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

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

Obtener el resultado

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

Consulta cada pocos segundos hasta que status sea completed. El campo report contiene entonces el JSON completo: resumen ejecutivo, acciones priorizadas y las secciones de brecha semántica, brecha de UX y preparación para IA.

Respuesta:

{
  "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 del análisis

status pasa por queued y running, y luego se detiene en uno de tres valores terminales: completed, failed o canceled. Detén el sondeo en los tres — en failed y canceled el campo error indica el motivo y report queda null.

Límites de frecuencia

Hasta 60 peticiones por hora y cuenta, y 3 análisis en curso a la vez. Al superar cualquiera de los dos límites el endpoint responde 429: espera y reinténtalo.

Errores

401 — clave API no válida o revocada
402 — créditos insuficientes
404 — id de análisis inexistente
405 — método HTTP incorrecto (analyze solo acepta POST)
422 — datos no válidos (url, query, country, language)
429 — demasiadas peticiónes, intentalo mas tarde

Crear clave API