Submit an async job

Request#

Authenticate with your API key in the x-api-key header (see Authentication).

Parameters#

• Idempotency-Keystring | nullheadermin length 1, max length 200

  Optional. Reusing it with the same body returns the original job; a different body is 409. Without one, every submission creates a new job.

Body#

JSON object. Unknown fields are rejected with 422.

• itemsarray of object | nullmin items 1, max items 500

  One to 500 operations. Each keeps its own method, path, body, query and label. Omit when submitting a single operation at the top level.

  Show 7 child fieldsHide child fields

  • items[].operationstring | nullmax length 200

    Operation id (google_calendar) or METHOD /path (POST /v1/calendar). Get the list from GET /v1/async/operations.

  • items[].methodstring | nullmax length 10

    HTTP method for a path item. Defaults to POST.

  • items[].pathstring | nullmax length 200

    Route path for a path item, for example /v1/calendar.

  • items[].urlstring | nullmax length 2048

    Shorthand for the generic scrape endpoint: this URL is fetched as a /v1/scrape job. Other item fields in body are passed through.

  • items[].bodyobject

    The operation's JSON request body, exactly as the synchronous endpoint takes it.

  • items[].queryobject

    Query-string parameters, for a GET operation.

  • items[].labelstring | nullmax length 200

    Optional customer label returned with this item.

• operationstring | nullmax length 200

  Single-job shorthand: operation id or METHOD /path.

• methodstring | nullmax length 10

  Single-job shorthand: HTTP method for path.

• pathstring | nullmax length 200

  Single-job shorthand: route path such as /v1/calendar.

• urlstring | nullmax length 2048

  Single-job shorthand for the generic scrape endpoint.

• bodyobject

  Single-job shorthand: the operation's JSON body.

• queryobject

  Single-job shorthand: query-string parameters.

• labelstring | nullmax length 200

  Single-job shorthand: label returned with the item.

• priorityintegerdefault 5min 0, max 9

  Queue priority from 0 (lowest) to 9 (highest). FIFO is preserved among jobs with the same priority.

• callback_urlstring | nullmax length 2048

  Optional public HTTPS endpoint. A signed async_job.completed event is POSTed after the job reaches a terminal state. Verify x-scrapercompany-signature (HMAC-SHA256 of x-scrapercompany-timestamp + . + the raw body) with the enabled HTTPS webhook secret for this URL, or with GET /v1/async/callback-secret when the URL is not an enabled registered webhook. For 24 hours after rotating the account secret the header lists both HMACs, comma-separated. Dedupe on x-scrapercompany-delivery.

• callbackobject | null

  ScraperAPI-style webhook callback object. An alternative to callback_url.

  Show 2 child fieldsHide child fields

  • callback.typestringdefault webhook

    Callback transport. webhook is the only supported value.

  • callback.urlstringrequiredmax length 2048

    Public HTTPS endpoint that receives the signed completion event.

• destination_idstring | nullmax length 80

  Saved S3/GCS destination (POST /v1/async/destinations) to upload the finished job to. Delivery is independent of the scrape outcome.

• metaobject

  Caller metadata echoed unchanged in status responses and webhooks. Maximum 8 KB.

• max_creditsinteger | nullmin 0

  Stop starting items once this many credits are spent or reserved. An item starts only when credits already spent, plus the listed price of items in flight, plus this item's listed price, fit under the limit. The listed price is the synchronous route cost; the charge is never higher. Items that do not fit are cancelled.

• include_resultsbooleandefault false

  When true, the completion webhook includes item response bodies if they fit in 256 KB. Otherwise the webhook is a summary plus results_url. Polling follows its own include_results query parameter.

curl -X POST "https://api.scrapercompany.com/v1/async/jobs" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://example.com/webhooks/scrapercompany",
    "items": [
      {
        "body": {
          "currency": "USD",
          "days": 90,
          "market": "US",
          "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ"
        },
        "label": "Boston Marriott Copley Place",
        "operation": "google_calendar"
      },
      {
        "body": {
          "check_in": "2026-12-20",
          "check_out": "2026-12-22",
          "currency": "USD",
          "market": "US",
          "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ"
        },
        "label": "Same property, seller by seller",
        "operation": "POST /v1/offers"
      }
    ],
    "meta": {
      "batch": "q3-comp-set"
    }
  }'

Response#

202 — Durably queued; poll the returned URL or wait for the webhook.

{
  "id": "asyncjob_0123456789abcdef0123456789abcdef",
  "job_id": "asyncjob_0123456789abcdef0123456789abcdef",
  "status": "queued",
  "priority": 5,
  "status_url": "/v1/async/jobs/asyncjob_0123456789abcdef0123456789abcdef",
  "poll_url": "/v1/async/jobs/asyncjob_0123456789abcdef0123456789abcdef",
  "callback_url": "https://example.com/webhooks/scrapercompany",
  "callback_status": "pending",
  "callback_attempts": 0,
  "meta": {
    "batch": "q3-comp-set"
  },
  "max_credits": 100,
  "credits_used": 0,
  "include_results": false,
  "items_total": 2,
  "items_succeeded": 0,
  "items_failed": 0,
  "created_at": "2026-08-10T14:05:00Z",
  "updated_at": "2026-08-10T14:05:00Z",
  "items": [
    {
      "id": "asyncitem_0123456789abcdef0123456789abcdef",
      "item_id": "asyncitem_0123456789abcdef0123456789abcdef",
      "index": 0,
      "operation": "POST /v1/calendar",
      "method": "POST",
      "path": "/v1/calendar",
      "label": "Boston Marriott Copley Place",
      "status": "queued",
      "attempts": 0,
      "credits": 0
    },
    {
      "id": "asyncitem_0123456789abcdef0123456789abcdea",
      "item_id": "asyncitem_0123456789abcdef0123456789abcdea",
      "index": 1,
      "operation": "POST /v1/offers",
      "method": "POST",
      "path": "/v1/offers",
      "label": "Same property, seller by seller",
      "status": "queued",
      "attempts": 0,
      "credits": 0
    }
  ]
}

Errors#

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

Try it#

Async jobs, destinations, schedules and the callback secret are not changed from the docs; call this with your own key.

1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? start a free trial).
2. Copy the cURL example above and run it in a terminal.