# Create a calendar job: `POST /v1/jobs`

Cost: from 8 credits (each succeeded item is priced like POST /v1/calendar, surcharges included (8 for a default item); failed items are free). Docs: https://scrapercompany.com/docs/reference/jobs-create

Persist before returning 202; execution can survive API restarts.

Parameters:

- `Idempotency-Key` (string; required; min length 1, max length 200): Unique per logical submission. Reusing it with the same body returns the original job; a different body is 409.

Request body (JSON):

- `items` (array of object; required; min items 1, max items 50): One to 50 Google calendar requests. Each item keeps its own market, currency, horizon, occupancy and price basis.
  - `items[].token` (string; required; min length 8): Google property token. Get one from `POST /v1/search` — it is the `token` on each match. Looks like `ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ`.
  - `items[].market` (string | null; optional; one of AE, AG, AR, AT, AU, BE, BR, BZ, CA, CH, CL, CN, CO, CZ, DE, DK, EG, ES, FI, FR, GB, GR, HK, HR, HU, ID, IE, IL, IN, IT, JP, KR, MX, MY, NL, NO, NZ, PE, PH, PL, PT, QA, RO, SA, SE, SG, TH, TR, TW, US, VN, ZA): Market/country, e.g. `US`, `MX`, `AU`, `GB`. Sets `gl` and the default tax basis. Omit to derive it from `currency`.
  - `items[].country` (string | null; optional; one of ad, ae, af, ag, ai, al, am, ao, aq, ar, as, at, au, aw, ax, az, ba, bb, bd, be, bf, bg, bh, bi, bj, bl, bm, bn, bo, bq, br, bs, bt, bv, bw, by, bz, ca, cc, cd, cf, cg, ch, ci, ck, cl, cm, cn, co, cr, cu, cv, cw, cx, cy, cz, de, dj, dk, dm, do, dz, ec, ee, eg, eh, er, es, et, fi, fj, fk, fm, fo, fr, ga, gb, gd, ge, gf, gg, gh, gi, gl, gm, gn, gp, gq, gr, gs, gt, gu, gw, gy, hk, hm, hn, hr, ht, hu, id, ie, il, im, in, io, iq, ir, is, it, je, jm, jo, jp, ke, kg, kh, ki, km, kn, kp, kr, kw, ky, kz, la, lb, lc, li, lk, lr, ls, lt, lu, lv, ly, ma, mc, md, me, mf, mg, mh, mk, ml, mm, mn, mo, mp, mq, mr, ms, mt, mu, mv, mw, mx, my, mz, na, nc, ne, nf, ng, ni, nl, no, np, nr, nu, nz, om, pa, pe, pf, pg, ph, pk, pl, pm, pn, pr, ps, pt, pw, py, qa, re, ro, rs, ru, rw, sa, sb, sc, sd, se, sg, sh, si, sj, sk, sl, sm, sn, so, sr, ss, st, sv, sx, sy, sz, tc, td, tf, tg, th, tj, tk, tl, tm, tn, to, tr, tt, tv, tw, tz, ua, ug, uk, um, us, uy, uz, va, vc, ve, vg, vi, vn, vu, wf, ws, xk, ye, yt, za, zm, zw): Two-letter `gl` override. Normally set by `market`.
  - `items[].currency` (string | null; optional; one of AED, ARS, AUD, BRL, CAD, CHF, CLP, CNY, COP, CZK, DKK, EGP, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MXN, MYR, NOK, NZD, PEN, PHP, PLN, QAR, RON, SAR, SEK, SGD, THB, TRY, TWD, USD, VND, ZAR): ISO currency for the returned prices. It is part of the request, so it does not depend on where the request is served from.
  - `items[].days` (integer; optional; default 90; min 1, max 330): Nights to price, starting at `start`. Max 330.
  - `items[].start` (string (date) | null; optional): First stay date. Defaults to tomorrow.
  - `items[].adults` (integer; optional; default 2; min 1, max 8): Occupancy. Any value 1-8 works. Children are not supported by the calendar.
  - `items[].los` (integer; optional; default 1; min 1, max 30): Length of stay per quote. Nightly price genuinely moves with LOS.
  - `items[].rates_include_tax` (boolean | null; optional): Overrides the market default; pass the property's own setting
  - `items[].is_hostel` (boolean; optional; default false): Hostels are priced per bed rather than per room, so occupancy changes the rate differently. Set this and the per-person maths is applied.
  - `items[].probe_min_stay` (boolean; optional; default true): Re-ask for any night that will not price as a single night. Google returns a two-night-minimum night identically to a sold-out one — empty, with no reason and no min-stay field — so without this, weekends silently vanish. On a beach market in August that was every Friday and Saturday on half the comp set. Filled rows carry `min_length_of_stay` and a per-night rate derived from the longer stay. Costs one extra call per probe level, not per date.
  - `items[].basis` (string; optional; default cheapest; one of cheapest, mainstream; pattern ^(cheapest|mainstream)$): What the nightly figure should mean. **`cheapest` (default)** is the fast calendar path: one small request for the whole horizon. It returns Google's lowest bookable rate, including aggregators. The base/fees/taxes/total split and SERP-compatible `rate_before_taxes_with_fees` remain populated. **`mainstream`** also returns `rate_mainstream_total` / `rate_mainstream_base` / `mainstream_source` / `aggregator_discount` — the cheapest rate on Booking, Expedia, Hotels.com, Priceline, Tripadvisor or Agoda, which is what a comp-set audit means by 'the OTA rate'. `rate_total` is left untouched, so both bases are available. This is intentionally expensive: it samples multi-megabyte offers pages and, when an aggregator sets the floor, re-prices each date. Measured on a 14-day request it took about 8s versus 0.4s for `cheapest`; use it selectively. `basis_applied` reports which path ran.
  - `items[].verify_sources` (integer; optional; default 0; min 0, max 5): Spot-check this many nights against the per-OTA offers page and return a `source_check` block. The calendar gives one price per night and never says which source it came from — usually a mainstream OTA, but where a discounter undercuts them it reports the discounter. Measured on four properties: three matched the cheapest mainstream OTA to the cent, the fourth's figure was Super.com's at 15% under. Costs one offers lookup per sampled night, so it is a sample, not every date.
  - `items[].compact` (boolean; optional; default false): Return only essential fields per night (stay_date, rate, rate_total, rate_including_vat, currency, rates_include_tax) for smaller responses over MCP. Omits base/tax/fees breakdown, mainstream rates, and min_length_of_stay details.
  - `items[].label` (string | null; optional; max length 200): Optional customer label returned with this 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 `job.completed` event is POSTed after the batch finishes. Verify `x-scrapercompany-signature` 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`. A submission is rejected with 503 when callback signing is not enabled.

Response fields:

- `id` (string; required): `refreshjob_...`
- `job_id` (string; required): Same as `id`.
- `poll_url` (string; required): `/v1/jobs/{job_id}`
- `status` (string; required; one of queued, running, succeeded, partial, failed)
- `priority` (integer; required)
- `callback_url` (string | null; required)
- `callback_status` (string; required; one of not_configured, pending, delivered, failed)
- `callback_attempts` (integer; required)
- `callback_last_error` (string | null; required)
- `artifact_uri` (string | null; required)
- `artifact_sha256` (string | null; required)
- `result_summary` (object; required): Empty object until the job finishes.
  - `result_summary.rates` (integer; optional)
  - `result_summary.database` (object; optional)
- `error` (string | null; required)
- `items_total` (integer; required)
- `items_succeeded` (integer; required)
- `items_failed` (integer; required)
- `created_at` (string; required): Timestamp string, e.g. `2026-08-10 14:05:00.123456+00`.
- `started_at` (string | null; required): Timestamp string, e.g. `2026-08-10 14:05:00.123456+00`.
- `finished_at` (string | null; required): Timestamp string, e.g. `2026-08-10 14:05:00.123456+00`.
- `updated_at` (string; required): Timestamp string, e.g. `2026-08-10 14:05:00.123456+00`.
- `items` (array of object; required)
  - `items[].id` (string; required): `refreshitem_...`
  - `items[].item_index` (integer; required)
  - `items[].token` (string; required)
  - `items[].label` (string | null; required)
  - `items[].status` (string; required; one of queued, running, succeeded, failed)
  - `items[].request` (object; required): One property in an asynchronous calendar batch.
  - `items[].result` (object | null; required): The item's calendar payload. Only populated with `include_results=true` once the item succeeded; otherwise null.
  - `items[].error` (string | null; required)
  - `items[].attempts` (integer; required)
  - `items[].started_at` (string | null; required): Timestamp string, e.g. `2026-08-10 14:05:00.123456+00`.
  - `items[].finished_at` (string | null; required): Timestamp string, e.g. `2026-08-10 14:05:00.123456+00`.
  - `items[].updated_at` (string; required): Timestamp string, e.g. `2026-08-10 14:05:00.123456+00`.

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)
