# Create a schedule: `POST /v1/async/schedules`

Cost: free (0 (failed requests are free)). Docs: https://scrapercompany.com/docs/reference/async-schedules-create

Store a job template and cadence. Each due slot becomes a normal async
job (same metering, retries, webhook and optional S3/GCS delivery).

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.
- `name` (string; required; min length 1, max length 80): Display name, unique per account.
- `cadence` (string; optional; default daily; one of hourly, every_6h, twice_daily, daily, weekly, manual): How often to run. `hourly` is the fastest; `manual` creates a schedule that only `POST .../run` starts. Missed slots are skipped, not replayed.
- `run_hour` (integer; optional; default 0; min 0, max 23): Hour of the day in `timezone` for `daily`/`weekly`; ignored by interval cadences.
- `weekday` (integer; optional; default 0; min 0, max 6): Day for `weekly`: 0 = Monday, 6 = Sunday.
- `timezone` (string; optional; default UTC; max length 64): IANA timezone for `run_hour`/`weekday` (`America/New_York`). Interval cadences advance from the previous run in UTC.
- `enabled` (boolean; optional; default true): Pause a schedule (false) without deleting it.

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)