Riferimento API

URL base: https://www.serpfull.com/api/v1. Invia la tua chiave nell’intestazione Authorization. Le risposte sono in JSON; le liste appaiono come { "object": "list", "data": [...] }. Un progetto è uno dei tuoi siti web.

Progetti

GET /projects
GET /projects/{project_id}

Termini di ricerca

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)

Crea un termine di ricerca

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}'

Crea un termine di ricerca con 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 richiede una chiave di lettura e scrittura (altrimenti 403 insufficient_scope) e restituisce 201 con il termine di ricerca. Accetta gli stessi campi di POST /projects/{project_id}/terms più project_id (obbligatorio). I limiti del piano sono controllati prima: superare il limite di termini di ricerca o clic al giorno del progetto restituisce 422 limit_exceeded con quanto resta; un progetto senza piano restituisce 422 plan_required; un sito web non verificato restituisce 422 project_unverified.

Pianificazione (oggetto schedule opzionale, alla creazione e con PATCH): timezone (nome IANA, default Europe/London); active_hours { start 0–23, end 1–24 } o null per le ore del sito web; start_date e end_date (YYYY-MM-DD, inclusivi, in quel fuso orario); ramp_up { start_clicks, increase_per_day } o null, dove i clic iniziano da start_clicks al primo giorno e aumentano di increase_per_day fino a clicks_per_day. Lo status può essere "active" (default) o "paused" alla creazione. Con PATCH, schedule sostituisce l'intero programma.

Campi: keyword (obbligatorio), target_url (una pagina nel dominio del progetto, o null), country (ISO 3166-1 alpha-2; uno dei paesi offerti nella lista Paesi dell'app; default GB), device (desktop, mobile, tablet o mixed; mixed sceglie casualmente uno dei tre a ogni esecuzione e l'esecuzione registra il dispositivo usato; default desktop). target_url può essere nel dominio o in uno dei suoi sottodomini, clicks_per_day (0–1.000, default 5). PATCH accetta gli stessi campi più status: "active" o "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 restituisce 202 con { "object": "seo_audit", "id": "…", "status": "running" }; esegui polling con GET /seo/audits/{id} finché lo status è completed o failed (di solito meno di un minuto). Applica gli stessi limiti dell'app. Quando uno si applica ricevi 429 con error.code cooldown, concurrency, daily_quota, monthly_quota, competitor_quota o host_busy, error.retry_at e un'intestazione Retry-After; 403 quando il sito necessita di un piano attivo o verifica.

Esecuzioni

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

Le esecuzioni sono ordinate dalla più recente e di default mostrano gli ultimi 30 giorni. limit è 1–200 (default 50). since e until sono timestamp ISO 8601. Quando has_more è true, passa next_cursor come cursor per ottenere la pagina successiva. outcome è uno dei valori spiegati in Run outcomes.

Esempio di esecuzione

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