Referencia API

URL base: https://www.serpfull.com/api/v1. Envíe su clave en el encabezado de Autorización. Las respuestas son JSON; Las listas se parecen a { "object": "list", "data": [...] }. Un proyecto es uno de sus sitios web.

Proyectos

GET /projects
GET /projects/{project_id}

Términos de búsqueda

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)

Crear un término de búsqueda

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

Crear un término de búsqueda 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 necesita una clave de lectura y escritura (403 alcance_insuficiente en caso contrario) y devuelve 201 con el término de búsqueda. Toma los mismos campos que POST /projects/{project_id}/terms más project_id (obligatorio). Los límites del plan se verifican primero: al superar el término de búsqueda del proyecto o el límite de clics por día se obtiene 422 limit_exceeded con lo que queda; un proyecto sin plan devuelve 422 plan_required; un sitio web no verificado devuelve 422 project_unverified.

Programación (objeto de programación opcional, al crear y PATCH): zona horaria (nombre de IANA, predeterminado Europa/Londres); active_hours { start 0–23, end 1–24 } o null para el horario del sitio web; fecha_inicio y fecha_final (AAAA-MM-DD, inclusive, en esa zona horaria); ramp_up { start_clicks, increase_per_day } o nulo, donde los clics comienzan en start_clicks el día uno y aumentan en incremento_por_día hasta clics_por_día. El estado puede ser "activo" (predeterminado) o "en pausa" al crear. En PATCH, el cronograma reemplaza el cronograma completo.

Campos: palabra clave (obligatoria), target_url (una página en el dominio del proyecto, o nula), país (ISO 3166-1 alfa-2; uno de los países ofrecidos en la lista de países de la aplicación; GB predeterminado), dispositivo (escritorio, móvil o tableta; escritorio predeterminado). target_url puede estar en el dominio o en uno de sus subdominios, clicks_per_day (0–1000, valor predeterminado 5). PATCH acepta los mismos campos más el estado: "activo" o "en pausa".

auditoría 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 devuelve 202 con { "object": "seo_audit", "id": "…", "status": "running" }; sondee GET /seo/audits/{id} hasta que el estado se complete o falle (generalmente menos de un minuto). Aplica los mismos límites que la aplicación. Cuando se aplica uno, obtienes 429 con tiempo de reutilización de error.code, concurrencia, cuota_diaria, cuota_mensual, cuota_competidor o host_busy, error.retry_at y un encabezado Retry-After; 403 cuando el sitio web necesita un plan activo o verificación.

Corre

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

Las ejecuciones son las más recientes primero y de forma predeterminada son los últimos 30 días. El límite es de 1 a 200 (50 predeterminado). desde y hasta son marcas de tiempo ISO 8601. Cuando has_more es verdadero, pasa next_cursor como cursor para pasar a la página siguiente. El resultado es uno de los valores explicados en Ejecutar resultados.

Ejecución de ejemplo

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