Référence API

URL de base : https://www.serpfull.com/api/v1. Envoyez votre clé dans l'en-tête Authorization. Les réponses sont en JSON ; les listes ressemblent à { "object": "list", "data": [...] }. Un projet est un de vos sites web.

Projets

GET /projects
GET /projects/{project_id}

Termes de recherche

GET    /projects/{project_id}/terms
POST   /projects/{project_id}/terms      (read & write key)
POST   /terms                            (read & write key; project_id in the body)
GET    /terms/{term_id}
PATCH  /terms/{term_id}                 (read & write key)
DELETE /terms/{term_id}                 (read & write key)

Créer un terme de recherche

curl -X POST https://www.serpfull.com/api/v1/projects/$PROJECT/terms \
  -H "Authorization: Bearer $SERPFULL_KEY" -H "Content-Type: application/json" \
  -d '{"keyword":"emergency plumber leeds","country":"GB","device":"mobile","clicks_per_day":10}'

Créer un terme de recherche avec POST /terms

curl -X POST https://www.serpfull.com/api/v1/terms \
  -H "Authorization: Bearer $SERPFULL_KEY" -H "Content-Type: application/json" \
  -d '{"project_id":"$PROJECT","keyword":"boiler repair leeds","clicks_per_day":20,
       "schedule":{"timezone":"Europe/London","active_hours":{"start":9,"end":18},
                   "start_date":"2026-11-01","ramp_up":{"start_clicks":2,"increase_per_day":2}}}'

POST /terms nécessite une clé en lecture & écriture (403 insufficient_scope sinon) et retourne 201 avec le terme de recherche. Il prend les mêmes champs que POST /projects/{project_id}/terms plus project_id (requis). Les limites du plan sont vérifiées en premier : dépasser la limite de termes de recherche ou de clics par jour du projet retourne 422 limit_exceeded avec ce qui reste ; un projet sans plan retourne 422 plan_required ; un site web non vérifié retourne 422 project_unverified.

Planification (objet schedule optionnel, à la création et en PATCH) : timezone (nom IANA, Europe/London par défaut) ; active_hours { start 0–23, end 1–24 } ou null pour les heures du site web ; start_date et end_date (AAAA-MM-JJ, inclus, dans ce fuseau) ; ramp_up { start_clicks, increase_per_day } ou null, où les clics commencent à start_clicks le premier jour et augmentent de increase_per_day jusqu'à clicks_per_day. Le statut peut être « active » (par défaut) ou « paused » à la création. En PATCH, schedule remplace tout le planning.

Champs : keyword (requis), target_url (une page sur le domaine du projet, ou null), country (ISO 3166-1 alpha-2 ; un des pays proposés dans la liste Pays de l'application ; GB par défaut), device (desktop, mobile, tablet ou mixed ; mixed choisit aléatoirement l'un des trois à chaque exécution et l'exécution enregistre l'appareil utilisé ; desktop par défaut). target_url peut être sur le domaine ou un de ses sous-domaines, clicks_per_day (0–1 000, 5 par défaut). PATCH accepte les mêmes champs plus status : « active » ou « paused ».

Audit SEO

GET  /projects/{project_id}/seo           pages, limits and usage
GET  /seo/pages/{page_id}                page, latest audit (issues and facts), competitor pages
GET  /seo/pages/{page_id}/audits?limit=50 audit history, newest first
POST /seo/pages/{page_id}/audits         start an audit (read & write key)
GET  /seo/audits/{audit_id}              one audit with category scores, issues and facts

POST /seo/pages/{page_id}/audits retourne 202 avec { "object": "seo_audit", "id": "…", "status": "running" } ; interrogez GET /seo/audits/{id} jusqu'à ce que le statut soit completed ou failed (généralement moins d'une minute). Il applique les mêmes limites que l'application. Lorsqu'une s'applique, vous obtenez 429 avec error.code cooldown, concurrency, daily_quota, monthly_quota, competitor_quota ou host_busy, error.retry_at et un en-tête Retry-After ; 403 lorsque le site web nécessite un plan actif ou une vérification.

Exécutions

GET /runs?project_id=&term_id=&outcome=&since=&until=&limit=50&cursor=

Les exécutions sont les plus récentes en premier et par défaut sur les 30 derniers jours. limit est de 1 à 200 (50 par défaut). since et until sont des horodatages ISO 8601. Quand has_more est vrai, passez next_cursor en cursor pour obtenir la page suivante. outcome est une des valeurs expliquées dans Résultats d'exécution.

Exemple d'exécution

{
  "id": "…", "object": "run", "project_id": "…", "term_id": "…",
  "status": "finished", "outcome": "completed", "position": 4, "page": 1,
  "dwell_seconds": 48, "pages_visited": 2, "device": "mobile", "country": "GB", "error_code": null,
  "started_at": "2026-10-20T13:12:00Z", "finished_at": "2026-10-20T13:13:05Z"
}