Create a calendar job

Request#

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

Parameters#

• Idempotency-Keystringheaderrequiredmin length 1, max length 200

  Unique per logical submission. Reusing it with the same body returns the original job; a different body is 409.

Body#

JSON object. Unknown fields are rejected with 422.

• itemsarray of objectrequiredmin items 1, max items 50

  One to 50 Google calendar requests. Each item keeps its own market, currency, horizon, occupancy and price basis.

  Show 14 child fieldsHide child fields

  • items[].tokenstringrequiredmin length 8

    Google property token. Get one from POST /v1/search — it is the token on each match. Looks like ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ.

  • items[].marketstring | null

    Market/country, e.g. US, MX, AU, GB. Sets gl and the default tax basis. Omit to derive it from currency.

    18 allowed values

    AG, AT, AU, BE, BZ, CA, CH, DE, ES, FR, GB, IE, IT, MX, NL, NZ, PT, US

  • items[].countrystring | null

    Two-letter gl override. Normally set by market.

    251 allowed values

    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

  • items[].currencystring | null

    ISO currency for the returned prices.

    39 allowed values

    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

  • items[].daysintegerdefault 90min 1, max 330

    Nights to price, starting at start. Max 330.

  • items[].startstring (date) | null

    First stay date. Defaults to tomorrow.

  • items[].adultsintegerdefault 2min 1, max 8

    Occupancy: number of adults, 1-8. Children are not supported by the Google calendar.

  • items[].losintegerdefault 1min 1, max 30

    Length of stay per quote. Nightly price genuinely moves with LOS.

  • items[].rates_include_taxboolean | null

    Overrides the market default; pass the property's own setting

  • items[].is_hostelbooleandefault 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_staybooleandefault 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[].basisstringdefault cheapestpattern ^(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 SearchAPI-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.

    One ofcheapestmainstream

  • items[].verify_sourcesintegerdefault 0min 0, max 5

    Spot-check this many nights against the per-OTA offers page and return a source_check block. The Google 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 ~3 MB offers fetch per sampled night, so it is a sample, not every date.

  • items[].labelstring | nullmax length 200

    Optional customer label returned with this 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. ScraperCompany POSTs a signed job.completed event to it after the batch finishes. If webhook delivery is not enabled for the service, a submission with callback_url is rejected with 503.

Example request#

curl -X POST "https://api.scrapercompany.com/v1/jobs" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
        "label": "Hilton Chicago",
        "days": 90,
        "currency": "USD",
        "market": "US"
      },
      {
        "token": "ChcI7LnnsZLasKYOGgsvZy8xdHJzejFiORAB",
        "label": "Comp set hotel 2",
        "days": 90,
        "currency": "USD",
        "market": "US"
      }
    ]
  }'

Response#

202 — Durably queued; poll the returned URL for progress. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

{
  "id": "refreshjob_0123456789abcdef0123456789abcdef",
  "job_id": "refreshjob_0123456789abcdef0123456789abcdef",
  "poll_url": "/v1/jobs/refreshjob_0123456789abcdef0123456789abcdef",
  "status": "queued",
  "priority": 5,
  "callback_url": "https://example.com/webhooks/scrapercompany",
  "callback_status": "pending",
  "callback_attempts": 0,
  "result_summary": {},
  "items_total": 1,
  "items_succeeded": 0,
  "items_failed": 0,
  "created_at": "2026-08-10T14:05:00Z",
  "updated_at": "2026-08-10T14:05:00Z",
  "items": [
    {
      "id": "refreshitem_0123456789abcdef0123456789abcdef",
      "item_index": 0,
      "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
      "label": "Boston Marriott Copley Place",
      "status": "queued",
      "request": {
        "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
        "label": "Boston Marriott Copley Place",
        "market": "US",
        "currency": "USD",
        "days": 90,
        "adults": 2,
        "los": 1,
        "basis": "cheapest",
        "is_hostel": false,
        "probe_min_stay": true,
        "verify_sources": 0
      },
      "attempts": 0,
      "updated_at": "2026-08-10T14:05:00Z"
    }
  ]
}

Response fields#

Fields marked required are always present; others appear when they apply.

• idstringrequired

  refreshjob_...

• job_idstringrequired

  Same as id.

• poll_urlstringrequired

  /v1/jobs/{job_id}

• statusstringrequired

  One ofqueuedrunningsucceededpartialfailed

• priorityintegerrequired
• callback_urlstring | nullrequired
• callback_statusstringrequired

  One ofnot_configuredpendingdeliveredfailed

• callback_attemptsintegerrequired
• callback_last_errorstring | nullrequired
• artifact_uristring | nullrequired
• artifact_sha256string | nullrequired
• result_summaryobjectrequired

  Empty object until the job finishes.

  Show 3 child fieldsHide child fields

  • result_summary.ratesinteger
  • result_summary.wire_bytesinteger
  • result_summary.databaseobject
    Show 4 child fieldsHide child fields

    • result_summary.database.run_idstringrequired
    • result_summary.database.rows_writtenintegerrequired
    • result_summary.database.rows_changedintegerrequired
    • result_summary.database.rows_removedintegerrequired
• errorstring | nullrequired
• items_totalintegerrequired
• items_succeededintegerrequired
• items_failedintegerrequired
• created_atstringrequired

  Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

• started_atstring | nullrequired

  Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

• finished_atstring | nullrequired

  Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

• updated_atstringrequired

  Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

• itemsarray of objectrequired
  Show 12 child fieldsHide child fields

  • items[].idstringrequired

    refreshitem_...

  • items[].item_indexintegerrequired
  • items[].tokenstringrequired
  • items[].labelstring | nullrequired
  • items[].statusstringrequired

    One ofqueuedrunningsucceededfailed

  • items[].requestobjectrequired

    One property in an asynchronous calendar batch.

    Show 14 child fieldsHide child fields

    • items[].request.tokenstringrequiredmin length 8

      Google property token. Get one from POST /v1/search — it is the token on each match. Looks like ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ.

    • items[].request.marketstring | null

      Market/country, e.g. US, MX, AU, GB. Sets gl and the default tax basis. Omit to derive it from currency.

      18 allowed values

      AG, AT, AU, BE, BZ, CA, CH, DE, ES, FR, GB, IE, IT, MX, NL, NZ, PT, US

    • items[].request.countrystring | null

      Two-letter gl override. Normally set by market.

      251 allowed values

      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

    • items[].request.currencystring | null

      ISO currency for the returned prices.

      39 allowed values

      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

    • items[].request.daysintegerdefault 90min 1, max 330

      Nights to price, starting at start. Max 330.

    • items[].request.startstring (date) | null

      First stay date. Defaults to tomorrow.

    • items[].request.adultsintegerdefault 2min 1, max 8

      Occupancy: number of adults, 1-8. Children are not supported by the Google calendar.

    • items[].request.losintegerdefault 1min 1, max 30

      Length of stay per quote. Nightly price genuinely moves with LOS.

    • items[].request.rates_include_taxboolean | null

      Overrides the market default; pass the property's own setting

    • items[].request.is_hostelbooleandefault 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[].request.probe_min_staybooleandefault 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[].request.basisstringdefault cheapestpattern ^(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 SearchAPI-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.

      One ofcheapestmainstream

    • items[].request.verify_sourcesintegerdefault 0min 0, max 5

      Spot-check this many nights against the per-OTA offers page and return a source_check block. The Google 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 ~3 MB offers fetch per sampled night, so it is a sample, not every date.

    • items[].request.labelstring | nullmax length 200

      Optional customer label returned with this item.

  • items[].resultobject | nullrequired

    The item's calendar payload. Only populated with include_results=true once the item succeeded; otherwise null.

    Show 17 child fieldsHide child fields

    • items[].result.tokenstringrequired
    • items[].result.collection_idstringrequired

      Shared by every row of this collection (ratecol_...).

    • items[].result.observed_atstringrequired

      UTC observation time, ISO-8601.

    • items[].result.marketstringrequired
    • items[].result.requested_daysintegerrequired

      Nights requested (capped at 330).

    • items[].result.coveragenumberrequired

      Share of requested nights that returned a priced row, 0-1 rounded to 4 decimals (e.g. 0.9333 = 84 of 90). A number, not an N/M string.

    • items[].result.wire_bytesintegerrequired
    • items[].result.elapsed_snumberrequired

      End-to-end seconds for this request.

    • items[].result.calendar_elapsed_snumberrequired

      Seconds spent on the upstream calendar fetch.

    • items[].result.egress_modestringrequired

      One ofdirectproxy_fallback

    • items[].result.tax_profileobject | nullrequired

      The property's effective tax profile, derived from the returned nights.

    • items[].result.unpriced_datesarray of string (date)required

      Requested nights with no bookable offer.

    • items[].result.validationobjectrequired

      Plausibility checks on the returned rows.

    • items[].result.booking_windowobject

      How far out the property actually sells. Present on successful collections.

    • items[].result.basis_appliedstring

      Present only with basis: mainstream.

      One ofmainstream:annotatedmainstream:calendar-already-matched

    • items[].result.source_checkobject

      Present only when verify_sources > 0 or basis: mainstream sampled nights against the offers page.

    • items[].result.ratesarray of objectrequired

      One row per priced night.

  • items[].errorstring | nullrequired
  • items[].attemptsintegerrequired
  • items[].started_atstring | nullrequired

    Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

  • items[].finished_atstring | nullrequired

    Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

  • items[].updated_atstringrequired

    Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

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#

1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? request access).
2. Copy the cURL example above and run it in a terminal.
3. Or open the interactive playground on api.scrapercompany.com, paste your key and pick this endpoint.