Reference

API reference

Every endpoint, parameter and response — generated from the same OpenAPI 3.1 document served at /v1/openapi.json, so it cannot drift from the API.

Base URL https://api.scrapelyserp.com/v1. Authenticate with Authorization: Bearer <key>. Import openapi.json into Postman, Insomnia or an SDK generator.

Products

Product, price and stock data on every live retailer and marketplace (GET /v1/platforms lists them, with what is coming soon), in one response shape; plus every offer on an Amazon listing and offer checks. Send item ids for a `platform`; limits and prices are per platform and tier.

Get products

POST/v1/products

Product data for a list of item ids on one platform and marketplace (defaults amazon and us; GET /v1/platforms lists what is live, each platform's id field, tiers, prices and per-call limits). Send the ids as ids (asins is accepted on Amazon). One result per unique id, in request order, each with a status. Always 200 for a well-formed request, even when every item is unavailable. Billing: per unique item at the tier's rate. The whole call is reserved up front, rounded up once per call (402 if your balance cannot cover it); partial and unavailable items are refunded, so you pay for ok and not_found. X-Scrapely-Credits is the final charge. Allow up to 300 s; smaller calls are proportionally faster. Uses one concurrency slot. Amazon (asins, 1 to 2,000 per call, 10,000 at pulse): per ASIN pulse 0.25, lite 1, full 5; delivery dates are included in lite and full at no extra cost. Typical: pulse 10–20 s for 10,000 ASINs; lite 35–45 s for 2,000 ASINs; full 60–90 s for 2,000 ASINs. Walmart (platform: "walmart", marketplace us): send 1 to 100 numeric item ids (from walmart.com/ip/<slug>/<id>) as ids; 1 credit per ok or not_found item. Results carry the neutral fields plus walmart (list price, offer, seller type, shipping, brand, UPC, rating, category). Typical: 3–10 s for 100 items. Best Buy (platform: "bestbuy", marketplace us): send 1 to 1,000 numeric SKUs as ids; 1 credit per ok or not_found SKU (not_found also covers SKUs Best Buy no longer sells). Results carry the neutral fields plus bestbuy (state, regular price, savings, brand, condition, category). Typical: 10–15 s for 1,000 SKUs. Target (platform: "target", marketplace us): send 1 to 1,000 TCINs (the number after /A- in a product URL) as ids; 1 credit per ok or not_found TCIN. A variation parent answers with its featured variant (target.tcin). Results carry the neutral fields plus target (regular price, shipping, store pickup). Typical: 5–15 s for 1,000 TCINs.

curl -X POST "https://api.scrapelyserp.com/v1/products" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"amazon","marketplace":"us","ids":["0060094664","B0009KNLV6","BZZZZZZZZZ"],"tier":"lite"}'

Responses

200One result per unique id, in request order.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501The platform or marketplace is coming soon. Nothing is charged.

Check whether exact offers can be bought

POST/v1/offers/check

For 1 to 2000 offers ({ asin, offerListingId } from /v1/products or /v1/offers): can each exact offer be bought right now. A yes/no per offer: no price, no stock level (use lite for those). Always 200 for a well-formed request. Cost: 0.5 credit per offer answered, rounded up once per call; reserved up front (402 if your balance cannot cover it), unavailable offers refunded. Duration: 2000 offers usually take 15–20 s; allow up to 120 s. Uses one concurrency slot.

curl -X POST "https://api.scrapelyserp.com/v1/offers/check" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offers":[{"asin":"B0009KNLV6","offerListingId":"pQ4/z9Lr0sT="},{"asin":"0060094664","offerListingId":"Xh7+qT2b/kLm9wQ=="}]}'

Responses

200One result per unique offer, in request order.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501The platform or marketplace is coming soon. Nothing is charged.

Get every offer for a list of items

POST/v1/offers

Every offer for 1 to 100 items on a platform and marketplace (platform default amazon, marketplace default us): price, shipping, condition, seller, FBA and which offer holds the buy box. One result per unique ASIN, in request order. Always 200 for a well-formed request. Cost per unique ASIN: 1 credit for a listing with one offer or none (and for not_found), 3 for one with more (totalOffers says which). 3 per ASIN is reserved up front (402 if your balance cannot cover it) and the difference refunded; unavailable ASINs are refunded. X-Scrapely-Credits is the final charge. Depth: every offer for the ASIN, up to 31 (featured offer first, then cheapest first). Duration: a 100-ASIN call usually takes well under a minute; allow up to 180 s. Uses one concurrency slot.

curl -X POST "https://api.scrapelyserp.com/v1/offers" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asins":["B0009KNLV6","BZZZZZZZZZ"],"condition":"all"}'

Responses

200One result per unique ASIN, in request order.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501The platform or marketplace is coming soon. Nothing is charged.

Get every offer for one item

GET/v1/products/{id}/offers

A convenience alias for a single-item POST /v1/offers: same response (results holds one entry), same price (1 or 3 credits, nothing when unavailable). A malformed id is a 400 whose param names the platform's id (asin on Amazon).

curl "https://api.scrapelyserp.com/v1/products/B0009KNLV6/offers" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The item id: on Amazon, the ASIN (10 letters or digits).

conditionenum

all (default), new, or used (every non-new condition: used, renewed/refurbished, collectible). One of: new, used, all.

undefinedany · undefined

Responses

200One result, for the ASIN in the path.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501The platform or marketplace is coming soon. Nothing is charged.

Structured data

Popular page types as typed JSON. **Coming soon:** these endpoints answer 501 for now.

List structured endpoints

GET/v1/structured

Every structured endpoint with its parameters and status (live or coming_soon).

curl "https://api.scrapelyserp.com/v1/structured" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Responses

200Every structured endpoint with its parameters.
401UNAUTHORIZED: missing, unknown or revoked key.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Amazon search (coming soon)

GET/v1/structured/amazon/search

Coming soon. This endpoint answers 501 NOT_IMPLEMENTED with "coming_soon": true and charges nothing until it launches. Search results for a query: position, title, price, rating, sponsored flag. Cost: 5 credits, flat. Also accepts POST with a JSON body.

curl "https://api.scrapelyserp.com/v1/structured/amazon/search?query=…" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

querystringrequired

The search terms.

pageinteger

Results page, 1–100.

countryenum

Marketplace / locale to query.

Responses

200The amazon search as JSON.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501NOT_IMPLEMENTED with "message": "Coming soon" and "coming_soon": true. Nothing is charged.
502TARGET_FAILED: the retailer blocked us, errored, or timed out after retries. Not charged.

Google search (coming soon)

GET/v1/structured/google/search

Coming soon. This endpoint answers 501 NOT_IMPLEMENTED with "coming_soon": true and charges nothing until it launches. A Google results page (SERP): organic results, related searches, People Also Ask. Cost: 5 credits, flat. Also accepts POST with a JSON body.

curl "https://api.scrapelyserp.com/v1/structured/google/search?query=…" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

querystringrequired

The search terms.

pageinteger

Results page, 1–100.

countrystring

Two-letter country to search from (Google gl).

languagestring

Interface language (Google hl), e.g. en, de, pt-BR.

numinteger

Results per page, 10–100.

Responses

200The google search as JSON.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501NOT_IMPLEMENTED with "message": "Coming soon" and "coming_soon": true. Nothing is charged.
502TARGET_FAILED: the retailer blocked us, errored, or timed out after retries. Not charged.

Google Shopping (coming soon)

GET/v1/structured/google/shopping

Coming soon. This endpoint answers 501 NOT_IMPLEMENTED with "coming_soon": true and charges nothing until it launches. Shopping results for a query: product, price, merchant, rating. Cost: 5 credits, flat. Also accepts POST with a JSON body.

curl "https://api.scrapelyserp.com/v1/structured/google/shopping?query=…" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

querystringrequired

The search terms.

countrystring

Two-letter country to shop from.

Responses

200The google shopping as JSON.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501NOT_IMPLEMENTED with "message": "Coming soon" and "coming_soon": true. Nothing is charged.
502TARGET_FAILED: the retailer blocked us, errored, or timed out after retries. Not charged.

Walmart product (coming soon)

GET/v1/structured/walmart/product

Coming soon. This endpoint answers 501 NOT_IMPLEMENTED with "coming_soon": true and charges nothing until it launches. A Walmart product page by item id: title, price, rating, availability, specifications. Cost: 5 credits, flat. Also accepts POST with a JSON body.

curl "https://api.scrapelyserp.com/v1/structured/walmart/product?product_id=…" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

product_idstringrequired

Numeric Walmart item id, from walmart.com/ip/<slug>/<id>.

Responses

200The walmart product as JSON.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501NOT_IMPLEMENTED with "message": "Coming soon" and "coming_soon": true. Nothing is charged.
502TARGET_FAILED: the retailer blocked us, errored, or timed out after retries. Not charged.

Walmart search (coming soon)

GET/v1/structured/walmart/search

Coming soon. This endpoint answers 501 NOT_IMPLEMENTED with "coming_soon": true and charges nothing until it launches. Walmart search results for a query. Cost: 5 credits, flat. Also accepts POST with a JSON body.

curl "https://api.scrapelyserp.com/v1/structured/walmart/search?query=…" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

querystringrequired

The search terms.

pageinteger

Results page, 1–100.

Responses

200The walmart search as JSON.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501NOT_IMPLEMENTED with "message": "Coming soon" and "coming_soon": true. Nothing is charged.
502TARGET_FAILED: the retailer blocked us, errored, or timed out after retries. Not charged.

eBay listing (coming soon)

GET/v1/structured/ebay/product

Coming soon. This endpoint answers 501 NOT_IMPLEMENTED with "coming_soon": true and charges nothing until it launches. An eBay listing by item id: price, shipping, condition, seller feedback, auction state. Cost: 5 credits, flat. Also accepts POST with a JSON body.

curl "https://api.scrapelyserp.com/v1/structured/ebay/product?item_id=…" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

item_idstringrequired

Numeric eBay item id, from ebay.com/itm/<id>.

countryenum

Marketplace / locale to query. One of: us, gb, de, fr, it, es, ca, au.

Responses

200The ebay listing as JSON.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501NOT_IMPLEMENTED with "message": "Coming soon" and "coming_soon": true. Nothing is charged.
502TARGET_FAILED: the retailer blocked us, errored, or timed out after retries. Not charged.

eBay search (coming soon)

GET/v1/structured/ebay/search

Coming soon. This endpoint answers 501 NOT_IMPLEMENTED with "coming_soon": true and charges nothing until it launches. eBay search results for a query. Cost: 5 credits, flat. Also accepts POST with a JSON body.

curl "https://api.scrapelyserp.com/v1/structured/ebay/search?query=…" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

querystringrequired

The search terms.

pageinteger

Results page, 1–100.

countryenum

Marketplace / locale to query. One of: us, gb, de, fr, it, es, ca, au.

Responses

200The ebay search as JSON.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
402INSUFFICIENT_CREDITS: nothing was charged.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.
501NOT_IMPLEMENTED with "message": "Coming soon" and "coming_soon": true. Nothing is charged.
502TARGET_FAILED: the retailer blocked us, errored, or timed out after retries. Not charged.

Watchlists

Up to 50,000 items of one platform and marketplace (ASINs, Walmart item ids, TCINs, SKUs…) re-checked on a cadence by a pipeline of scrapers and rules you choose (default on Amazon: the pulse → lite → full ladder; on one-tier retailers: a fetch and diff of every item); changes and matches pushed to a signed webhook. Billed as the calls each run makes.

Create a watchlist

POST/v1/watchlists

Track up to 50,000 items of one platform and marketplace on a cadence (every) or a cron schedule in a time zone (cron + timezone) (at most 100 lists per account). Creating is free. Send the item ids in ids (every platform); asins is still accepted on Amazon as a legacy alias. Send a pipeline to choose the scrapers each run uses and how they chain; without one the platform default runs. The first run starts at once and reads every item at the baseline step (default on Amazon: full; no change events). With the default pipeline, on Amazon each later run sweeps at pulse, escalates to lite the ASINs whose offer count or lowest new price moved (plus those whose buy box sat above the lowest offer, and any owed retry), and every refresh_every_runs-th run sweeps everything at lite; one-tier retailers fetch and diff every item each run. Runs are billed exactly like the /v1/products calls they make; a run the balance cannot cover is skipped (insufficient_credits), and the third skip in a row pauses the list.

curl -X POST "https://api.scrapelyserp.com/v1/watchlists" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Repricer","platform":"amazon","marketplace":"us","ids":["B0009KNLV6","0060094664"],"every":"15m","webhook_url":"https://example.com/hooks/scrapely"}'

Parameters

Idempotency-Keystring · header

Retrying with the same key returns the original response (Idempotent-Replayed: true) instead of creating a second list. Remembered 24 hours.

Responses

201Created; the first run is due now.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
403DEMO_READ_ONLY.
409CONFLICT: idempotent request in flight, a run already in progress, or a per-account limit.
422INVALID_PARAM with param: idempotency_key: the key was used for a different request.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

List watchlists

GET/v1/watchlists

curl "https://api.scrapelyserp.com/v1/watchlists" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

limitinteger

Responses

200Newest first.
401UNAUTHORIZED: missing, unknown or revoked key.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Get a watchlist

GET/v1/watchlists/{id}

curl "https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The watchlist id (wl_…).

Responses

200The watchlist, with item counts per state and credit estimates.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Update a watchlist

PATCH/v1/watchlists/{id}

Rename, change the cadence (counted from the last run), the webhook or the refresh interval; pause or resume.

curl -X PATCH "https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"every":"1h","status":"active"}'

Parameters

idstring · pathrequired

The watchlist id (wl_…).

Responses

200Updated.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Delete a watchlist

DELETE/v1/watchlists/{id}

Deletes the list, its items and its run history. A run already in progress finishes but sends no webhooks.

curl -X DELETE "https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The watchlist id (wl_…).

Responses

200Deleted.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Add or remove items (legacy path)

POST/v1/watchlists/{id}/asins

The historical path of POST /api/v1/watchlists/{id}/items: same body and behaviour on every platform; only object differs. Item ids of the list's platform. Removals apply first. Added items get a baseline fetch on the next run (Amazon: full; no change event); a delisted item added again gets another chance. At most 50,000 items per list. Free.

curl -X POST "https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61/asins" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"add":["B074PVTPBW"],"remove":["0060094664"]}'

Parameters

idstring · pathrequired

The watchlist id (wl_…).

Body (JSON)

addstring[]

Item ids to add.

removestring[]

Item ids to remove.

Responses

200What changed.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Run a watchlist now

POST/v1/watchlists/{id}/run

Starts a run at once (202) and restarts the schedule from now. Billed like a scheduled run; works on a paused list. 409 while a run of this list is in progress.

curl -X POST "https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61/run" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The watchlist id (wl_…).

Responses

202Started.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
409CONFLICT: idempotent request in flight, a run already in progress, or a per-account limit.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

List pipeline scrapers

GET/v1/watchlists/scrapers

What a pipeline step can run on a platform: each scraper, what it reads, its credits per item, the fields its routes can test and whether it is available in the marketplace; plus ready-made templates. Free.

curl "https://api.scrapelyserp.com/v1/watchlists/scrapers" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

platformstring

marketplacestring

Responses

200Scrapers and templates.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

List runs

GET/v1/watchlists/{id}/runs

Newest first; the newest 500 are kept.

curl "https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61/runs" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The watchlist id (wl_…).

limitinteger

Responses

200Runs.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

List items

GET/v1/watchlists/{id}/items

The items on the list with their last snapshot, in id order. Each carries id (plus asin on Amazon lists). changed_since returns only items that changed or were delisted since then: the pull counterpart of the webhook.

curl "https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61/items" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The watchlist id (wl_…).

changed_sincestring

ISO 8601 or epoch milliseconds.

stateenum

One of: new, active, delisted.

limitinteger

starting_afterstring

next_starting_after from the previous page.

Responses

200A page of items.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Add or remove items

POST/v1/watchlists/{id}/items

Item ids of the list's platform. Removals apply first. Added items get a baseline fetch on the next run (Amazon: full; no change event); a delisted item added again gets another chance. At most 50,000 items per list. Free.

curl -X POST "https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61/items" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"add":["B074PVTPBW"],"remove":["0060094664"]}'

Parameters

idstring · pathrequired

The watchlist id (wl_…).

Body (JSON)

addstring[]

Item ids to add.

removestring[]

Item ids to remove.

Responses

200What changed.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Webhook endpoints

Where signed webhooks go. Up to 10 endpoints per account, each with its own signing secret, shown once (on create and on rotate) and never returned again.

List webhook endpoints

GET/v1/webhook_endpoints

curl "https://api.scrapelyserp.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Responses

200Oldest first. No secrets.
401UNAUTHORIZED: missing, unknown or revoked key.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Create a webhook endpoint

POST/v1/webhook_endpoints

Registers a URL and generates its own signing secret, returned in secret this once. At most 10 per account (409 beyond). Not idempotent by design: a replayable response would be a stored secret.

curl -X POST "https://api.scrapelyserp.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/scrapely","description":"Production","events":["watchlist.product.changed","watchlist.run.completed"]}'

Responses

201Created. Save secret now.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
409CONFLICT: idempotent request in flight, a run already in progress, or a per-account limit.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Get a webhook endpoint

GET/v1/webhook_endpoints/{id}

curl "https://api.scrapelyserp.com/v1/webhook_endpoints/we_7b1c2d3e4f5a6b7c" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The endpoint id (we_…).

Responses

200The endpoint. No secret.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Update a webhook endpoint

PATCH/v1/webhook_endpoints/{id}

Change url, description, events or enabled. The secret is unchanged (rotate it separately).

curl -X PATCH "https://api.scrapelyserp.com/v1/webhook_endpoints/we_7b1c2d3e4f5a6b7c" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

Parameters

idstring · pathrequired

The endpoint id (we_…).

Responses

200Updated.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
409CONFLICT: idempotent request in flight, a run already in progress, or a per-account limit.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Delete a webhook endpoint

DELETE/v1/webhook_endpoints/{id}

Pending retries to it, and watchlists that name its URL, are recorded as failed deliveries from now on.

curl -X DELETE "https://api.scrapelyserp.com/v1/webhook_endpoints/we_7b1c2d3e4f5a6b7c" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The endpoint id (we_…).

Responses

200Deleted.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Rotate the signing secret

POST/v1/webhook_endpoints/{id}/rotate

A new secret, effective at once, returned in secret this once. With overlap: true (the default) the old secret keeps signing too — a second v1= in Scrapely-Signature — for 24 hours, so you can deploy the new one without missing a delivery. overlap: false drops it immediately (use it if the secret leaked).

curl -X POST "https://api.scrapelyserp.com/v1/webhook_endpoints/we_7b1c2d3e4f5a6b7c/rotate" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The endpoint id (we_…).

Body (JSON)

overlapboolean

Responses

200Rotated. Save secret now.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Send a test event

POST/v1/webhook_endpoints/{id}/test

One signed webhook.test delivery to this endpoint, now, without retries. Recorded in the delivery log.

curl -X POST "https://api.scrapelyserp.com/v1/webhook_endpoints/we_7b1c2d3e4f5a6b7c/test" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

idstring · pathrequired

The endpoint id (we_…).

Responses

200What the endpoint answered.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

S3 export

Write every watchlist event to your own S3 bucket (or any S3-compatible store: Cloudflare R2, Wasabi, MinIO, Backblaze B2). One destination per account. The secret access key is write-only: it is stored encrypted and never returned.

Get the S3 export destination

GET/v1/exports/s3

curl "https://api.scrapelyserp.com/v1/exports/s3" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Responses

200The destination (keys masked) and its 20 most recent uploads.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Create or update the S3 export destination

PUT/v1/exports/s3

Fields left out keep their current value. Runs a connection test first (unless test: false); enabled: true is refused with a 400 when the test fails, and nothing is saved.

curl -X PUT "https://api.scrapelyserp.com/v1/exports/s3" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bucket":"my-scrapes","region":"us-east-1","access_key_id":"AKIAIOSFODNN7EXAMPLE","secret_access_key":"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY","prefix":"scrapely/"}'

Responses

200Updated.
201Created.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Remove the S3 export destination

DELETE/v1/exports/s3

Deletes the destination and its stored keys. Nothing more is written to the bucket; objects already there stay.

curl -X DELETE "https://api.scrapelyserp.com/v1/exports/s3" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Responses

200Removed.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Test the S3 connection

POST/v1/exports/s3/test

Writes <prefix>scrapely-connection-test.txt now. With no body, tests the saved destination; with destination fields (as PUT), tests those merged over it without saving.

curl -X POST "https://api.scrapelyserp.com/v1/exports/s3/test" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Responses

200What the storage service answered.
400MISSING_PARAM or INVALID_PARAM; param names the culprit.
401UNAUTHORIZED: missing, unknown or revoked key.
404NOT_FOUND.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Account

Balance, concurrency and usage.

Get account

GET/v1/account

Credit balance, lifetime credits, concurrency limit and what is in flight.

curl "https://api.scrapelyserp.com/v1/account" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Responses

200The account the key belongs to.
401UNAUTHORIZED: missing, unknown or revoked key.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.

Get usage

GET/v1/usage

curl "https://api.scrapelyserp.com/v1/usage" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY"

Parameters

daysinteger

Responses

200Daily requests and credits, oldest first.
401UNAUTHORIZED: missing, unknown or revoked key.
429RATE_LIMITED or CONCURRENCY_LIMIT. Honour Retry-After.
500INTERNAL: our fault, not charged. Quote X-Request-Id.