Async tasks

For bulk or high-throughput workloads, enqueue SERP tasks and collect the results later — by polling or via webhooks.

Enqueue a task

POST /v1/serp/tasks takes the same body as live search and returns HTTP 202:

curl -X POST https://api.serplify.io/v1/serp/tasks \
  -H "Authorization: Bearer live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "electric cars",
    "location": { "code": 2840 },
    "language": { "code": "en" },
    "format": "advanced",
    "priority": "priority",
    "webhook": { "result_url": "https://example.com/hooks/serplify?id=$id" }
  }'

HTTP 202

{
  "request_id": "req_…",
  "status": "accepted",
  "meta": { "api_version": "0.1.0", "time": 0.02, "cost": 0.005, "currency": "USD" },
  "data": {
    "task_id": "0199…",
    "keyword": "electric cars",
    "format": "advanced",
    "status_url": "/v1/serp/tasks/0199…"
  }
}

The charge is applied at enqueue. priority: "priority" makes the task jump the queue ahead of standard tasks.

Fetch a task

GET /v1/serp/tasks/{id} returns the result once ready. An optional ?format= query (standard | advanced | html) overrides the stored format on read.

curl https://api.serplify.io/v1/serp/tasks/0199… \
  -H "Authorization: Bearer live_your_key_here"

• Still processing → HTTP 202:

  {
    "request_id": "req_…",
    "status": "accepted",
    "meta": { "api_version": "0.1.0", "time": 0.01, "cost": 0, "currency": "USD" },
    "data": { "task_id": "0199…", "status": "processing", "status_url": "/v1/serp/tasks/0199…" }
  }

• Ready → HTTP 200 with the SERP result in data.

• Failed → HTTP 502 task_failed.

• Unknown id → HTTP 404 not_found.

List ready tasks

GET /v1/serp/tasks lists your completed tasks from the last 24 hours:

{
  "request_id": "req_…",
  "status": "ok",
  "meta": { "api_version": "0.1.0", "time": 0.03, "cost": 0, "currency": "USD" },
  "data": {
    "tasks": [
      { "task_id": "0199…", "keyword": "electric cars", "tag": null, "created_at": "2026-07-02T12:00:00.000Z", "status_url": "/v1/serp/tasks/0199…" }
    ]
  }
}

Polling vs webhooks

• Polling — fetch status_url on an interval (e.g. every 2–5s). Fetching a task is free.
• Webhooks — set webhook.ready_url and/or webhook.result_url at enqueue to be notified/pushed the result. See webhooks.