Core concepts

Responses & statuses

Every item endpoint returns the same envelope: one result per item with a status you can act on, a stats summary and what the call cost.

The envelope

{
  "platform": "target",
  "marketplace": "us",
  "tier": "standard",
  "results": [
    {
      "id": "83887639",
      "status": "ok",
      "fetchedAt": "2026-10-16T21:27:22.940Z",
      "…": "…"
    }
  ],
  "stats": {
    "requested": 1,
    "ok": 1,
    "partial": 0,
    "notFound": 0,
    "unavailable": 0,
    "elapsedMs": 1345
  },
  "credits": 1
}

Field	Description
`platform`, `marketplace`	Where the data came from.
`tier`	The tier that answered (products). Amazon also echoes `include` when you sent it.
`results`	One entry per unique id, in the order you sent them.
`stats`	`requested` (unique ids), `ok`, `partial`, `notFound`, `unavailable` and `elapsedMs`.
`credits`	What the call cost after refunds. Also the `X-Scrapely-Credits` header.

Always 200

A well-formed item call answers 200, even when every item is unavailable. Branch on each result's status, not on the HTTP status. HTTP errors mean the request itself was refused (Errors).

Item statuses

Status	Meaning	What to do	Charged
`ok`	The item was found and read.	Use it. Out-of-stock items are `ok` too, with `availability.inStock: false`.	Yes
`partial`	Found, but key fields (such as price or stock) could not be read.	Do not trust price or stock. Ask again later.	No
`not_found`	The platform says the item does not exist.	Delist it. Do not retry.	Yes
`unavailable`	We could not get an answer this time.	Retry later. It is never evidence the item is gone.	No

not_found is reported only when the platform itself says so. A failed lookup is always unavailable, so it is safe to delist on not_found.

Common fields

Every product result carries these neutral fields when the platform and tier have the data. A field the platform does not show is left out, never sent empty.

Field	Type	Description
`id`	string	The item id you sent (normalised).
`status`	string	`ok`, `partial`, `not_found` or `unavailable`.
`fetchedAt`	string	When this item was read (ISO 8601).
`title`	string	The product name.
`url`	string	The product page.
`price`	`{ amount, currency }`	The current (featured) price, in the marketplace currency.
`availability`	`{ inStock, message? }`	`inStock` is true only when it can be bought now; `message` is the retailer's own words.
`seller`	`{ id?, name }`	Who sells the featured offer.
`fulfillment`	`{ byPlatform, name? }`	`byPlatform` is true when the retailer itself ships it.
`images`	string[]	Image URLs, primary first.

Platform-specific detail sits in an object named after the platform: walmart, target, bestbuy. Amazon keeps its detail at the top level (buybox, offers, delivery, full). See the platform pages.

Response headers

Header	Meaning
`X-Request-Id`	On every response. Quote it to support.
`X-Scrapely-Credits`	Credits this call cost, after refunds.
`X-Scrapely-Balance`	Your balance after this call.
`X-Scrapely-Duration-Ms`	How long an item call took.
`X-RateLimit-Limit`, `-Remaining`, `-Reset`	Your request-rate window (Rate limits).
`Idempotent-Replayed`	`true` when a create was answered from an earlier request with the same `Idempotency-Key`.

Timeouts

Item calls answer in seconds for a few hundred ids and can take a minute or two at the largest sizes. Allow 300 seconds client-side. If a call runs short of time, the items not yet read come back unavailable and are refunded, rather than the whole call failing.

For the lowest latency, send several smaller calls in parallel within your concurrency.

Idempotency

POST /v1/watchlists accepts an Idempotency-Key header, ideally a UUID. Retry the create with the same key and you get the original response back, with Idempotent-Replayed: true, instead of a second list.

A retry while the first request is still running is a 409 CONFLICT.
The same key with a different body is a 422 INVALID_PARAM.
Keys are remembered for 24 hours.