Referência da API

URL base: https://www.serpfull.com/api/v1. Envie sua chave no cabeçalho de autorização. As respostas são JSON; as listas se parecem com { "object": "list", "data": [...] }. Um projeto é um de seus sites.

Projetos

GET /projects
GET /projects/{project_id}

Termos de pesquisa

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)

Crie um termo de pesquisa

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

Crie um termo de pesquisa com 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 precisa de uma chave de leitura e gravação (403 insuficiente_scope caso contrário) e retorna 201 com o termo de pesquisa. São necessários os mesmos campos que POST /projects/{project_id}/terms mais project_id (obrigatório). Os limites do plano são verificados primeiro: ultrapassar o limite de termos de pesquisa ou de cliques por dia do projeto retorna 422 limit_exceeded com o que resta; um projeto sem plano retorna 422 plan_required; um site não verificado retorna 422 project_unverified.

Agendamento (objeto de agendamento opcional, na criação e no PATCH): fuso horário (nome IANA, padrão Europa/Londres); active_hours { start 0–23, end 1–24 } ou null para o horário do site; data_inicial e data_final (AAAA-MM-DD, inclusive, nesse fuso horário); ramp_up { start_clicks, increase_per_day } ou nulo, onde os cliques começam em start_clicks no primeiro dia e aumentam em increment_per_day até clicks_per_day. o status pode ser "ativo" (padrão) ou "pausado" na criação. No PATCH, o agendamento substitui todo o agendamento.

Campos: palavra-chave (obrigatório), target_url (uma página no domínio do projeto, ou nula), país (ISO 3166-1 alfa-2; um dos países oferecidos na lista de países do aplicativo; GB padrão), dispositivo (desktop, celular ou tablet; desktop padrão). target_url pode estar no domínio ou em um de seus subdomínios, clicks_per_day (0–1.000, padrão 5). PATCH aceita os mesmos campos mais o status: “ativo” ou “pausado”.

Auditoria de 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 retorna 202 com { "object": "seo_audit", "id": "…", "status": "running" }; poll GET /seo/audits/{id} até que o status seja concluído ou falhe (geralmente menos de um minuto). Aplica os mesmos limites do aplicativo. Quando alguém se aplica, você obtém 429 com cooldown de error.code, simultaneidade, daily_quota, mensal_quota, concorrente_quota ou host_busy, error.retry_at e um cabeçalho Retry-After; 403 quando o site precisa de um plano ativo ou verificação.

Corre

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

As execuções são as mais recentes primeiro e o padrão são os últimos 30 dias. o limite é 1–200 (padrão 50). desde e até são carimbos de data/hora ISO 8601. Quando has_more for verdadeiro, passe next_cursor como cursor para obter a próxima página. resultado é um dos valores explicados em Resultados da execução.

Exemplo de execução

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