API-Referenz

Basis-URL: https://www.serpfull.com/api/v1. Senden Sie Ihren Schlüssel im Authorization-Header. Antworten sind JSON; Listen sehen aus wie { "object": "list", "data": [...] }. Ein Projekt ist eine Ihrer Websites.

Projekte

GET /projects
GET /projects/{project_id}

Suchbegriffe

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)

Einen Suchbegriff erstellen

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

Erstellen Sie einen Suchbegriff mit 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 benötigt einen Lese- & Schreibschlüssel (sonst 403 insufficient_scope) und gibt 201 mit dem Suchbegriff zurück. Es verwendet dieselben Felder wie POST /projects/{project_id}/terms plus project_id (erforderlich). Zuerst werden die Planlimits geprüft: Wird das Limit für Suchbegriffe oder Klicks pro Tag des Projekts überschritten, gibt es 422 limit_exceeded mit dem verbleibenden Kontingent zurück; ein Projekt ohne Plan gibt 422 plan_required zurück; eine nicht verifizierte Website 422 project_unverified.

Planung (optional schedule-Objekt, bei Erstellung und PATCH): Zeitzone (IANA-Name, Standard Europe/London); active_hours { start 0–23, end 1–24 } oder null für die Stunden der Website; start_date und end_date (YYYY-MM-DD, inklusive, in dieser Zeitzone); ramp_up { start_clicks, increase_per_day } oder null, wobei die Klicks am ersten Tag bei start_clicks beginnen und täglich um increase_per_day bis clicks_per_day steigen. status kann bei Erstellung "active" (Standard) oder "paused" sein. Bei PATCH ersetzt schedule den gesamten Zeitplan.

Felder: keyword (erforderlich), target_url (eine Seite auf der Domain des Projekts oder null), country (ISO 3166-1 alpha-2; eines der im App-Länderverzeichnis angebotenen Länder; Standard GB), device (desktop, mobile, tablet oder mixed; mixed wählt bei jedem Lauf zufällig eines der drei und der Lauf zeichnet das verwendete Gerät auf; Standard desktop). target_url kann auf der Domain oder einer ihrer Subdomains liegen, clicks_per_day (0–1.000, Standard 5). PATCH akzeptiert dieselben Felder plus status: "active" oder "paused".

SEO-Audit

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 gibt 202 mit { "object": "seo_audit", "id": "…", "status": "running" } zurück; pollen Sie GET /seo/audits/{id} bis der Status completed oder failed ist (normalerweise unter einer Minute). Es gelten dieselben Limits wie in der App. Wenn eines greift, erhalten Sie 429 mit error.code cooldown, concurrency, daily_quota, monthly_quota, competitor_quota oder host_busy, error.retry_at und einem Retry-After-Header; 403 wenn die Website einen aktiven Plan oder eine Verifizierung benötigt.

Durchläufe

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

Läufe sind standardmäßig die neuesten zuerst und auf die letzten 30 Tage begrenzt. limit ist 1–200 (Standard 50). since und until sind ISO 8601 Zeitstempel. Wenn has_more true ist, übergeben Sie next_cursor als cursor, um die nächste Seite zu erhalten. outcome ist einer der Werte in Run outcomes explained.

Beispiel-Lauf

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