Data APIs
HTTP API

Batch request

The shared async batch, webhook, status poll, and ZIP download.

Batch request

Every product uses this body. The connection does not stay open until the pages are ready.

{
  "batch": [
    { "url": "https://www.google.com/search?q=a%2Bb&hl=de&gl=de", "country": "DE", "device": "desktop" },
    { "search": "pizza near me", "country": "US", "device": "mobile" }
  ],
  "webhookUrl": "https://example.com/hook"
}
FieldTypeRequiredDescription
batcharrayyes1 to 100 items
batch[].urlstringone of url or searchGoogle /search URL. How it is applied depends on the product
batch[].searchstringone of url or searchQuery text, 1–2048 characters. The product builds the Google URL
batch[].countrystringyesTwo-letter country code
batch[].device"desktop" | "mobile"yesDesktop or mobile results. Mobile is iOS
webhookUrlstringnoCalled once, when every index is terminal

An item that sets both url and search, or neither, is rejected with 400.

Accept

curl -sS -X POST "https://lexis-solutions-apis.com/api/serp-nojs/v1/serp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      { "search": "weather today", "country": "US", "device": "desktop" }
    ]
  }'
{ "jobId": "8f1c…", "status": "queued", "size": 1 }

HTTP status is always 202 for a valid batch. There is no timeoutMs and no page in this response.

Status

GET /api/serp-nojs/v1/serp/:jobId and GET /api/serp-js/v1/serp/:jobId use the same shapes.

While the batch is running:

{ "jobId": "8f1c…", "status": "queued", "size": 1, "finished": 0 }

When the ZIP exists, the body matches the webhook below.

Webhook

webhookUrl is called once, after every index is terminal. The body has no HTML and no presigned URL.

{
  "jobId": "8f1c…",
  "status": "done",
  "zipDownload": {
    "url": "https://lexis-solutions-apis.com/api/results/8f1c…",
    "contentType": "application/zip",
    "filename": "8f1c….zip",
    "bytes": 18432
  },
  "items": [{ "index": 0, "code": "ok" }]
}

zipDownload.url stays valid. Call it with your API key when you are ready to download.

Download

GET /api/results/:jobId with the API key returns a 15-minute Scaleway URL. That URL is minted on each call and is not stored in the webhook.

curl -sS "https://lexis-solutions-apis.com/api/results/JOB_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "url": "https://serp-lab-results.s3.fr-par.scw.cloud/serp-nojs/JOB_ID.zip?…",
  "expiresAt": "2026-10-07T12:15:00.000Z"
}

Unknown or unfinished ids return 404.

The ZIP always contains manifest.json:

[
  { "index": 0, "code": "ok", "filename": "0.html" },
  { "index": 1, "code": "blocked", "filename": null }
]

A failed index is omitted as a file and listed in the manifest, so later files keep their batch index. What each product writes is on the no-JS and JavaScript pages.

Errors

StatusBodyCause
400{ "error": "…" }Empty batch, more than 100 items, a bad item, or an invalid webhookUrl
401{ "error": "unauthorized" }Missing or invalid API key
404{ "error": "not found" }Unknown job, or the ZIP is not ready yet on the download route

On this page