API d’analyse de SERP

Lancez des analyses par API REST avec votre propre clé.

Authentification

Créez une clé dans votre Votre compte et envoyez-la dans l’en-tête X-API-Key à chaque requête. Chaque analyse consomme 1 crédit sur votre solde ou celui de votre equipe.

Lancer une analyse

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

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

Récupérer le resultat

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

Interrogez toutes les quelques secondes jusqu’à ce que status vaille completed. Le champ report contient alors le JSON complet : synthèse, actions priorisées et les sections écart sémantique, ecart UX et aptitude à l’IA.

Réponse:

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

États de l’analyse

status passe par queued et running, puis s’arrête sur l’une des trois valeurs terminales : completed, failed ou canceled. Arrêtez le polling dans les trois cas — sur failed et canceled, le champ error donne la raison et report reste null.

Limites de débit

Jusqu’à 60 requêtes par heure et par compte, et 3 analyses en cours simultanément. Au-delà de l’une des deux limites, l’endpoint répond 429 : attendez puis réessayez.

Erreurs

401 — clé API invalide ou révoquée
402 — crédits insuffisants
404 — id d’analyse inconnu
405 — méthode HTTP incorrecte (analyze n’accepte que POST)
422 — donnees invalides (url, query, country, language)
429 — trop de requêtes, réessayez plus tard

Créer une clé API