Get a calendar job

Request#

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

Parameters#

• job_idstringpathrequired
• include_resultsbooleandefault false

  Include each completed calendar payload. Leave false for a small status-only response.

Example request#

curl "https://api.scrapercompany.com/v1/jobs/refreshjob_0123456789abcdef0123456789abcdef?include_results=true" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY"

Response#

200 — Current job and per-property progress.

{
  "id": "refreshjob_0123456789abcdef0123456789abcdef",
  "job_id": "refreshjob_0123456789abcdef0123456789abcdef",
  "poll_url": "/v1/jobs/refreshjob_0123456789abcdef0123456789abcdef",
  "status": "succeeded",
  "priority": 5,
  "callback_url": "https://example.com/webhooks/scrapercompany",
  "callback_status": "delivered",
  "callback_attempts": 1,
  "artifact_uri": "r2://example-bucket/jobs/example.json.gz",
  "artifact_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "result_summary": {
    "rates": 90,
    "wire_bytes": 29804,
    "database": {
      "run_id": "scraperun_0123456789abcdef",
      "rows_written": 90,
      "rows_changed": 82,
      "rows_removed": 1
    }
  },
  "items_total": 1,
  "items_succeeded": 1,
  "items_failed": 0,
  "created_at": "2026-08-10T14:05:00Z",
  "started_at": "2026-08-10T14:05:01Z",
  "finished_at": "2026-08-10T14:05:02Z",
  "updated_at": "2026-08-10T14:05:02Z",
  "items": [
    {
      "id": "refreshitem_0123456789abcdef0123456789abcdef",
      "item_index": 0,
      "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
      "label": "Boston Marriott Copley Place",
      "status": "succeeded",
      "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": 1,
      "started_at": "2026-08-10T14:05:01Z",
      "finished_at": "2026-08-10T14:05:02Z",
      "updated_at": "2026-08-10T14:05:02Z"
    }
  ]
}

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.