# Submit an async job: `POST /v1/async/jobs`

Cost: free (free to submit; each item is charged its own operation's cost as it runs (listed in `GET /v1/async/operations`). Failed and cancelled items are free). Docs: https://scrapercompany.com/docs/reference/async-jobs-create

Stores the job and answers 202 at once; a stored job survives a restart on our side.

Each item names one metered operation (`GET /v1/async/operations`) and
carries that operation's normal JSON body. Reusing an `Idempotency-Key`
with the same work returns the same job; the same key with different work
is a 409. A callback URL is optional and must be public HTTPS.

Parameters:

- `Idempotency-Key` (string | null; optional; min 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.

Request body (JSON):

- `items` (array of object | null; optional; min 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.
  - `items[].operation` (string | null; optional; max length 200): Operation id (`google_calendar`) or `METHOD /path` (`POST /v1/calendar`). Get the list from `GET /v1/async/operations`.
  - `items[].method` (string | null; optional; max length 10): HTTP method for a `path` item. Defaults to `POST`.
  - `items[].path` (string | null; optional; max length 200): Route path for a `path` item, for example `/v1/calendar`.
  - `items[].url` (string | null; optional; max 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[].body` (object; optional): The operation's JSON request body, exactly as the synchronous endpoint takes it.
  - `items[].query` (object; optional): Query-string parameters, for a GET operation.
  - `items[].label` (string | null; optional; max length 200): Optional customer label returned with this item.
- `operation` (string | null; optional; max length 200): Single-job shorthand: operation id or `METHOD /path`.
- `method` (string | null; optional; max length 10): Single-job shorthand: HTTP method for `path`.
- `path` (string | null; optional; max length 200): Single-job shorthand: route path such as `/v1/calendar`.
- `url` (string | null; optional; max length 2048): Single-job shorthand for the generic scrape endpoint.
- `body` (object; optional): Single-job shorthand: the operation's JSON body.
- `query` (object; optional): Single-job shorthand: query-string parameters.
- `label` (string | null; optional; max length 200): Single-job shorthand: label returned with the item.
- `priority` (integer; optional; default 5; min 0, max 9): Queue priority from 0 (lowest) to 9 (highest). FIFO is preserved among jobs with the same priority.
- `callback_url` (string | null; optional; max 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`.
- `callback` (object | null; optional): ScraperAPI-style webhook callback object. An alternative to `callback_url`.
  - `callback.type` (string; optional; default webhook): Callback transport. `webhook` is the only supported value.
  - `callback.url` (string; required; max length 2048): Public HTTPS endpoint that receives the signed completion event.
- `destination_id` (string | null; optional; max length 80): Saved S3/GCS destination (`POST /v1/async/destinations`) to upload the finished job to. Delivery is independent of the scrape outcome.
- `meta` (object; optional): Caller metadata echoed unchanged in status responses and webhooks. Maximum 8 KB.
- `max_credits` (integer | null; optional; min 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_results` (boolean; optional; default 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.

Base URL: `https://api.scrapercompany.com`. Auth: send your key in the `x-api-key` header. A failed request (4xx or 5xx) or an empty result costs 0 credits.

- [Full API reference as one Markdown file](https://scrapercompany.com/llms-full.txt)
- [OpenAPI spec](https://scrapercompany.com/openapi.json)