{"openapi":"3.1.0","info":{"title":"Scrapely API","version":"1.0.0","summary":"Retail product data, as one API","description":"Product, price and stock data from the retailers you sell on, in one response shape, plus watchlists that tell you what changed. Proxies, retries and bot walls are handled for you.\n\n**Authentication:** send your key as `Authorization: Bearer <key>`, `X-API-Key: <key>`, or `?api_key=<key>`.\n\n**Billing:** pay-as-you-go credits, per item; failed lookups are free. Per item, by platform and tier: see GET /v1/platforms (Amazon per ASIN: pulse 0.25, lite 1, full 5).\n\n**Errors:** every error is `{ \"error\": { \"code\", \"message\", \"param?\", \"docs\" } }`.\n\n| Code | Status | Meaning |\n|---|---|---|\n| `MISSING_PARAM` | 400 | Missing parameter |\n| `INVALID_PARAM` | 400 | Invalid parameter |\n| `UNAUTHORIZED` | 401 | Unauthorized |\n| `DEMO_READ_ONLY` | 403 | Demo workspace |\n| `INSUFFICIENT_CREDITS` | 402 | Insufficient credits |\n| `NOT_FOUND` | 404 | Not found |\n| `GONE` | 410 | Gone |\n| `CONFLICT` | 409 | Conflict |\n| `CONCURRENCY_LIMIT` | 429 | Concurrency limit reached |\n| `RATE_LIMITED` | 429 | Rate limited |\n| `TARGET_FAILED` | 502 | Target failed |\n| `UNAVAILABLE` | 503 | Temporarily unavailable |\n| `NOT_IMPLEMENTED` | 501 | Not implemented |\n| `INTERNAL` | 500 | Internal error |","contact":{"email":""}},"servers":[{"url":"https://scrapelyserp.com","description":"This deployment"}],"security":[{"bearer":[]},{"apiKeyHeader":[]},{"apiKeyQuery":[]}],"tags":[{"name":"Products","description":"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. Send item ids for a `platform`; limits and prices are per platform and tier."},{"name":"Offers","description":"Every offer on a listing (price, shipping, condition, seller, fulfilment, which one holds the buy box), and whether exact offers can still be bought."},{"name":"Platforms","description":"Which retailers and marketplaces are live, their id fields, endpoints, tiers and prices. Public: no key needed."},{"name":"Structured data","description":"Popular page types as typed JSON. **Coming soon:** these endpoints answer 501 for now."},{"name":"Watchlists","description":"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."},{"name":"Webhook endpoints","description":"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."},{"name":"S3 export","description":"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."},{"name":"Account & usage","description":"Balance, concurrency and daily usage for the key's account."},{"name":"Meta","description":"Health and this document."}],"paths":{"/api/v1/products":{"post":{"tags":["Products"],"operationId":"fetchProducts","summary":"Get products","description":"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`.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsRequest"},"example":{"platform":"walmart","marketplace":"us","ids":["931920073","5129928603","1000000404"]}}}},"responses":{"200":{"description":"One result per unique id, in request order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsResponse"},"example":{"platform":"walmart","marketplace":"us","tier":"standard","results":[{"id":"931920073","status":"ok","fetchedAt":"2026-10-16T14:02:37.118Z","title":"Mainstays 20\" 3-Speed Box Fan, White","url":"https://www.walmart.com/ip/931920073","price":{"amount":30,"currency":"USD"},"availability":{"inStock":true,"message":"Available"},"seller":{"name":"Walmart.com"},"fulfillment":{"byPlatform":true,"name":"Walmart"},"images":["https://i5.walmartimages.com/asr/box-fan-1.jpeg","https://i5.walmartimages.com/asr/box-fan-2.jpeg"],"walmart":{"brand":"Mainstays","upc":"810004819238","modelNumber":"FB50-16HW","parentId":"931920073","listPrice":{"amount":24.99,"currency":"USD"},"offerId":"F8CF2B7A1E2D4C6A9B0E3D5F7A1C2B4D","offerType":"ONLINE_AND_STORE","thirdPartySeller":false,"onlineAvailable":true,"shipping":{"standard":{"amount":0,"currency":"USD"},"twoDayEligible":true,"freeOverThreshold":true},"maxPerOrder":12,"clearance":false,"preOrder":false,"condition":"New","category":"Home Improvement/Heating, Cooling, & Air Quality/Fans/Box Fans","rating":4.4,"reviewsCount":1250,"color":"White"}},{"id":"5129928603","status":"ok","fetchedAt":"2026-10-16T14:02:37.118Z","title":"Stainless Steel Electric Kettle, 1.7 L","url":"https://www.walmart.com/ip/5129928603","availability":{"inStock":false,"message":"Not available"},"seller":{"name":"Kitchen Outlet LLC"},"fulfillment":{"byPlatform":false},"images":["https://i5.walmartimages.com/asr/kettle-1.jpeg"],"walmart":{"brand":"Generic","listPrice":{"amount":39.99,"currency":"USD"},"offerType":"ONLINE_ONLY","thirdPartySeller":true,"onlineAvailable":false,"condition":"New","category":"Home/Kitchen & Dining/Small Appliances/Kettles"}},{"id":"1000000404","status":"not_found","fetchedAt":"2026-10-16T14:02:37.118Z"}],"stats":{"requested":3,"ok":2,"partial":0,"notFound":1,"unavailable":0,"elapsedMs":1840},"credits":3}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_PARAM","message":"ids[0] (\"ip/931920073\") is not an item id: expected the numeric Walmart item id, e.g. 5129928603.","param":"ids[0]","docs":"/docs/errors#invalid_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"description":"The platform or marketplace is coming soon. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceComingSoon"}}}}}}},"/api/v1/offers":{"post":{"tags":["Offers"],"operationId":"getOffers","summary":"Get every offer for a list of items","description":"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.\n\n**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.\n\n**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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffersRequest"},"example":{"platform":"amazon","marketplace":"us","ids":["B0009KNLV6","BZZZZZZZZZ"],"condition":"all"}}}},"responses":{"200":{"description":"One result per unique ASIN, in request order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffersResponse"},"example":{"platform":"amazon","marketplace":"us","results":[{"id":"B0009KNLV6","asin":"B0009KNLV6","status":"ok","fetchedAt":"2026-10-16T14:02:11.402Z","buyboxOfferListingId":"Rk9vX3dqYlR4Q0pZcWt3dmlmZnpPOFZZJTJCUmN3dE92cmlMQ0o0R2ZtS1hYSjdNSmhqWWVEdkQ=","totalOffers":14,"offers":[{"offerListingId":"Rk9vX3dqYlR4Q0pZcWt3dmlmZnpPOFZZJTJCUmN3dE92cmlMQ0o0R2ZtS1hYSjdNSmhqWWVEdkQ=","price":77.43,"currency":"USD","priceDisplay":"$77.43","shipping":0,"condition":"new","seller":{"id":"ATVPDKIKX0DER","name":"Amazon.com"},"fulfillment":{"isFba":true,"fulfillerName":"Amazon.com"},"isBuybox":true,"delivery":"FREE delivery Tuesday, October 21"},{"offerListingId":"cW1aMWx0dDNPcEdnbUo2UnBQOGJzcFJIVWZPRWlqUiUyRkR1NUwlMkZPRzZTJTJCQ3J6cFk=","price":71.5,"currency":"USD","priceDisplay":"$71.50","shipping":5.99,"condition":"new","seller":{"id":"A2R2RITDJNW1Q6","name":"Retro Lunch Co","rating":4.5,"ratingCount":1287},"fulfillment":{"isFba":false,"fulfillerName":"Retro Lunch Co"},"isBuybox":false,"availability":"Only 3 left in stock - order soon.","delivery":"$5.99 delivery October 24 - 28"}]},{"id":"BZZZZZZZZZ","asin":"BZZZZZZZZZ","status":"not_found","fetchedAt":"2026-10-16T14:02:10.977Z","offers":[]}],"stats":{"requested":2,"ok":1,"partial":0,"notFound":1,"unavailable":0,"elapsedMs":2210},"credits":4}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_PARAM","message":"At most 100 ASINs per call; split larger lists across calls.","param":"ids","docs":"/docs/errors#invalid_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"description":"The platform or marketplace is coming soon. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceComingSoon"}}}}}}},"/api/v1/offers/check":{"post":{"tags":["Offers"],"operationId":"checkOffers","summary":"Check whether exact offers can be bought","description":"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.\n\n**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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferCheckRequest"},"example":{"platform":"amazon","marketplace":"us","offers":[{"asin":"B0009KNLV6","offerListingId":"Rk9vX3dqYlR4Q0pZcWt3dmlmZnpPOFZZJTJCUmN3dE92cmlMQ0o0R2ZtS1hYSjdNSmhqWWVEdkQ="},{"asin":"0060094664","offerListingId":"cW1aMWx0dDNPcEdnbUo2UnBQOGJzcFJIVWZPRWlqUiUyRkR1NUwlMkZPRzZTJTJCQ3J6cFk="}]}}}},"responses":{"200":{"description":"One result per unique offer, in request order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferCheckResponse"},"example":{"platform":"amazon","marketplace":"us","results":[{"id":"Rk9vX3dqYlR4Q0pZcWt3dmlmZnpPOFZZJTJCUmN3dE92cmlMQ0o0R2ZtS1hYSjdNSmhqWWVEdkQ=","asin":"B0009KNLV6","offerListingId":"Rk9vX3dqYlR4Q0pZcWt3dmlmZnpPOFZZJTJCUmN3dE92cmlMQ0o0R2ZtS1hYSjdNSmhqWWVEdkQ=","status":"ok","fetchedAt":"2026-10-16T19:02:11.402Z","buyable":true},{"id":"cW1aMWx0dDNPcEdnbUo2UnBQOGJzcFJIVWZPRWlqUiUyRkR1NUwlMkZPRzZTJTJCQ3J6cFk=","asin":"0060094664","offerListingId":"cW1aMWx0dDNPcEdnbUo2UnBQOGJzcFJIVWZPRWlqUiUyRkR1NUwlMkZPRzZTJTJCQ3J6cFk=","status":"ok","fetchedAt":"2026-10-16T19:02:11.402Z","buyable":false}],"stats":{"requested":2,"ok":2,"partial":0,"notFound":0,"unavailable":0,"elapsedMs":1210},"credits":1}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_PARAM","message":"Missing required parameter `offers` (an array of offers).","param":"offers","docs":"/docs/errors#missing_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"description":"The platform or marketplace is coming soon. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceComingSoon"}}}}}}},"/api/v1/products/{id}/offers":{"get":{"tags":["Offers"],"operationId":"getProductOffers","summary":"Get every offer for one item","description":"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).","parameters":[{"name":"id","in":"path","required":true,"description":"The item id: on Amazon, the ASIN (10 letters or digits).","schema":{"type":"string"},"example":"B0009KNLV6"},{"name":"condition","in":"query","required":false,"description":"`all` (default), `new`, or `used` (every non-new condition: used, renewed/refurbished, collectible).","schema":{"type":"string","enum":["new","used","all"],"default":"all"},"example":"new"},{"name":"platform","in":"query","required":false,"schema":{"type":"string","default":"amazon"},"description":"Which platform to read. Platforms: `amazon` (live: us; coming soon: uk, de, fr, it, es, ca, mx, jp, au, in, br, nl, se, pl), `walmart` (live: us), `ebay` (coming soon), `target` (live: us), `bestbuy` (live: us; coming soon: ca), `aliexpress` (coming soon). A coming-soon platform or marketplace answers 501 `NOT_IMPLEMENTED` with `\"coming_soon\": true` (nothing charged); an unknown one is a 400 listing the valid values. GET /v1/platforms has the full list.","example":"amazon"},{"name":"marketplace","in":"query","required":false,"schema":{"type":"string","default":"us"},"description":"The platform's regional storefront (`us`, `uk`, `de`…); default the platform's main one. Prices come back in its currency.","example":"us"}],"responses":{"200":{"description":"One result, for the ASIN in the path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffersResponse"},"example":{"platform":"amazon","marketplace":"us","results":[{"id":"B0009KNLV6","asin":"B0009KNLV6","status":"ok","fetchedAt":"2026-10-16T14:02:11.402Z","buyboxOfferListingId":"Rk9vX3dqYlR4Q0pZcWt3dmlmZnpPOFZZJTJCUmN3dE92cmlMQ0o0R2ZtS1hYSjdNSmhqWWVEdkQ=","totalOffers":14,"offers":[{"offerListingId":"Rk9vX3dqYlR4Q0pZcWt3dmlmZnpPOFZZJTJCUmN3dE92cmlMQ0o0R2ZtS1hYSjdNSmhqWWVEdkQ=","price":77.43,"currency":"USD","priceDisplay":"$77.43","shipping":0,"condition":"new","seller":{"id":"ATVPDKIKX0DER","name":"Amazon.com"},"fulfillment":{"isFba":true,"fulfillerName":"Amazon.com"},"isBuybox":true,"delivery":"FREE delivery Tuesday, October 21"},{"offerListingId":"cW1aMWx0dDNPcEdnbUo2UnBQOGJzcFJIVWZPRWlqUiUyRkR1NUwlMkZPRzZTJTJCQ3J6cFk=","price":71.5,"currency":"USD","priceDisplay":"$71.50","shipping":5.99,"condition":"new","seller":{"id":"A2R2RITDJNW1Q6","name":"Retro Lunch Co","rating":4.5,"ratingCount":1287},"fulfillment":{"isFba":false,"fulfillerName":"Retro Lunch Co"},"isBuybox":false,"availability":"Only 3 left in stock - order soon.","delivery":"$5.99 delivery October 24 - 28"}]}],"stats":{"requested":1,"ok":1,"partial":0,"notFound":0,"unavailable":0,"elapsedMs":1630},"credits":3}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_PARAM","message":"asin (\"B0009\") is not an ASIN: expected 10 letters or digits, e.g. B0009KNLV6.","param":"asin","docs":"/docs/errors#invalid_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"description":"The platform or marketplace is coming soon. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceComingSoon"}}}}}}},"/api/v1/platforms":{"get":{"tags":["Platforms"],"operationId":"listPlatforms","summary":"List platforms and marketplaces","description":"Every platform this API reads, its marketplaces (each with its currency), and the endpoints each marketplace offers, `live` or `coming_soon`, with tiers and prices. Public: no key needed. Use it to discover coverage instead of hard-coding it.","security":[],"responses":{"200":{"description":"The platforms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformList"},"example":{"object":"list","data":[{"id":"bestbuy","object":"platform","name":"Best Buy","status":"live","id_field":"ids","id_name":"SKU","default_marketplace":"us","endpoints":[{"id":"products","name":"Product data","route":"POST /v1/products","status":"live","tiers":[{"id":"standard","name":"Standard","credits_per_item":1,"max_items_per_call":1000}]}],"marketplaces":[{"code":"us","name":"Best Buy US","country":"US","currency":"USD","status":"live","endpoints":{"products":"live"}},{"code":"ca","name":"Best Buy Canada","country":"CA","currency":"CAD","status":"coming_soon","endpoints":{"products":"coming_soon"}}]}]}}}}}}},"/api/v1/structured":{"get":{"tags":["Structured data"],"operationId":"listStructured","summary":"List structured endpoints","description":"Every structured endpoint with its parameters and `status` (`live` or `coming_soon`).","responses":{"200":{"description":"Every structured endpoint with its parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/structured/amazon/search":{"get":{"tags":["Structured data"],"operationId":"structured_amazon_search","summary":"Amazon search (coming soon)","description":"**Coming soon.** This endpoint answers `501 NOT_IMPLEMENTED` with `\"coming_soon\": true` and charges nothing until it launches.\n\nSearch results for a query: position, title, price, rating, sponsored flag.\n\n**Cost:** 5 credits, flat. Also accepts POST with a JSON body.","x-status":"coming_soon","parameters":[{"name":"query","in":"query","required":true,"description":"The search terms.","schema":{"type":"string"},"example":"wireless earbuds"},{"name":"page","in":"query","required":false,"description":"Results page, 1–100.","schema":{"type":"integer","default":1}},{"name":"country","in":"query","required":false,"description":"Marketplace / locale to query.","schema":{"type":"string","enum":["us","gb","de","fr","it","es","ca","jp","in","au","mx","br","nl","se","pl","sg","ae","tr"],"default":"us"},"example":"us"}],"responses":{"200":{"description":"The amazon search as JSON.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StructuredResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SearchResults"}}}]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"$ref":"#/components/responses/ComingSoon"},"502":{"$ref":"#/components/responses/TargetFailed"}}}},"/api/v1/structured/google/search":{"get":{"tags":["Structured data"],"operationId":"structured_google_search","summary":"Google search (coming soon)","description":"**Coming soon.** This endpoint answers `501 NOT_IMPLEMENTED` with `\"coming_soon\": true` and charges nothing until it launches.\n\nA Google results page (SERP): organic results, related searches, People Also Ask.\n\n**Cost:** 5 credits, flat. Also accepts POST with a JSON body.","x-status":"coming_soon","parameters":[{"name":"query","in":"query","required":true,"description":"The search terms.","schema":{"type":"string"},"example":"web scraping api"},{"name":"page","in":"query","required":false,"description":"Results page, 1–100.","schema":{"type":"integer","default":1}},{"name":"country","in":"query","required":false,"description":"Two-letter country to search from (Google `gl`).","schema":{"type":"string","default":"us"},"example":"us"},{"name":"language","in":"query","required":false,"description":"Interface language (Google `hl`), e.g. `en`, `de`, `pt-BR`.","schema":{"type":"string","default":"en"}},{"name":"num","in":"query","required":false,"description":"Results per page, 10–100.","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"The google search as JSON.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StructuredResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GoogleSearch"}}}]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"$ref":"#/components/responses/ComingSoon"},"502":{"$ref":"#/components/responses/TargetFailed"}}}},"/api/v1/structured/google/shopping":{"get":{"tags":["Structured data"],"operationId":"structured_google_shopping","summary":"Google Shopping (coming soon)","description":"**Coming soon.** This endpoint answers `501 NOT_IMPLEMENTED` with `\"coming_soon\": true` and charges nothing until it launches.\n\nShopping results for a query: product, price, merchant, rating.\n\n**Cost:** 5 credits, flat. Also accepts POST with a JSON body.","x-status":"coming_soon","parameters":[{"name":"query","in":"query","required":true,"description":"The search terms.","schema":{"type":"string"},"example":"espresso machine"},{"name":"country","in":"query","required":false,"description":"Two-letter country to shop from.","schema":{"type":"string","default":"us"}}],"responses":{"200":{"description":"The google shopping as JSON.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StructuredResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GoogleShopping"}}}]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"$ref":"#/components/responses/ComingSoon"},"502":{"$ref":"#/components/responses/TargetFailed"}}}},"/api/v1/structured/walmart/product":{"get":{"tags":["Structured data"],"operationId":"structured_walmart_product","summary":"Walmart product (coming soon)","description":"**Coming soon.** This endpoint answers `501 NOT_IMPLEMENTED` with `\"coming_soon\": true` and charges nothing until it launches.\n\nA Walmart product page by item id: title, price, rating, availability, specifications.\n\n**Cost:** 5 credits, flat. Also accepts POST with a JSON body.","x-status":"coming_soon","parameters":[{"name":"product_id","in":"query","required":true,"description":"Numeric Walmart item id, from `walmart.com/ip/<slug>/<id>`.","schema":{"type":"string"},"example":"5129928603"}],"responses":{"200":{"description":"The walmart product as JSON.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StructuredResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WalmartProduct"}}}]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"$ref":"#/components/responses/ComingSoon"},"502":{"$ref":"#/components/responses/TargetFailed"}}}},"/api/v1/structured/walmart/search":{"get":{"tags":["Structured data"],"operationId":"structured_walmart_search","summary":"Walmart search (coming soon)","description":"**Coming soon.** This endpoint answers `501 NOT_IMPLEMENTED` with `\"coming_soon\": true` and charges nothing until it launches.\n\nWalmart search results for a query.\n\n**Cost:** 5 credits, flat. Also accepts POST with a JSON body.","x-status":"coming_soon","parameters":[{"name":"query","in":"query","required":true,"description":"The search terms.","schema":{"type":"string"},"example":"air fryer"},{"name":"page","in":"query","required":false,"description":"Results page, 1–100.","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"The walmart search as JSON.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StructuredResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SearchResults"}}}]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"$ref":"#/components/responses/ComingSoon"},"502":{"$ref":"#/components/responses/TargetFailed"}}}},"/api/v1/structured/ebay/product":{"get":{"tags":["Structured data"],"operationId":"structured_ebay_product","summary":"eBay listing (coming soon)","description":"**Coming soon.** This endpoint answers `501 NOT_IMPLEMENTED` with `\"coming_soon\": true` and charges nothing until it launches.\n\nAn eBay listing by item id: price, shipping, condition, seller feedback, auction state.\n\n**Cost:** 5 credits, flat. Also accepts POST with a JSON body.","x-status":"coming_soon","parameters":[{"name":"item_id","in":"query","required":true,"description":"Numeric eBay item id, from `ebay.com/itm/<id>`.","schema":{"type":"string"},"example":"305512345678"},{"name":"country","in":"query","required":false,"description":"Marketplace / locale to query.","schema":{"type":"string","enum":["us","gb","de","fr","it","es","ca","au"],"default":"us"},"example":"us"}],"responses":{"200":{"description":"The ebay listing as JSON.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StructuredResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EbayProduct"}}}]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"$ref":"#/components/responses/ComingSoon"},"502":{"$ref":"#/components/responses/TargetFailed"}}}},"/api/v1/structured/ebay/search":{"get":{"tags":["Structured data"],"operationId":"structured_ebay_search","summary":"eBay search (coming soon)","description":"**Coming soon.** This endpoint answers `501 NOT_IMPLEMENTED` with `\"coming_soon\": true` and charges nothing until it launches.\n\neBay search results for a query.\n\n**Cost:** 5 credits, flat. Also accepts POST with a JSON body.","x-status":"coming_soon","parameters":[{"name":"query","in":"query","required":true,"description":"The search terms.","schema":{"type":"string"},"example":"mechanical keyboard"},{"name":"page","in":"query","required":false,"description":"Results page, 1–100.","schema":{"type":"integer","default":1}},{"name":"country","in":"query","required":false,"description":"Marketplace / locale to query.","schema":{"type":"string","enum":["us","gb","de","fr","it","es","ca","au"],"default":"us"}}],"responses":{"200":{"description":"The ebay search as JSON.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StructuredResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SearchResults"}}}]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Scrapely-Credits":{"$ref":"#/components/headers/Credits"},"X-Scrapely-Balance":{"$ref":"#/components/headers/Balance"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"501":{"$ref":"#/components/responses/ComingSoon"},"502":{"$ref":"#/components/responses/TargetFailed"}}}},"/api/v1/account":{"get":{"tags":["Account & usage"],"operationId":"getAccount","summary":"Get account","description":"Credit balance, lifetime credits, concurrency limit (with the calls in flight now and the next tier), auto top-up, and which key made the call. Free.","responses":{"200":{"description":"The account the key belongs to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"},"example":{"object":"account","id":"acct_4d5e6f7a8b9c0d1e","name":"Acme Retail","email":"dev@example.com","credit_balance":412640,"lifetime_credits":605000,"credits_spent":192360,"concurrency":{"limit":50,"in_flight":3,"next_tier":{"concurrency":100,"at_lifetime_credits":2000000}},"auto_topup":{"enabled":true,"threshold_credits":50000,"pack_id":"growth"},"webhook_endpoints":1,"api_key":{"id":"key_9a8b7c6d5e4f","name":"Production","prefix":"sk_live_3f9a"},"created_at":"2026-09-01T12:00:00.000Z"}}}},"401":{"description":"`UNAUTHORIZED`: missing, unknown or revoked key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"UNAUTHORIZED","message":"Invalid or revoked API key.","param":"api_key","docs":"/docs/errors#unauthorized"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/usage":{"get":{"tags":["Account & usage"],"operationId":"getUsage","summary":"Get usage","description":"Requests, successes, failures and credits per day for the last `days` days, oldest first, with totals for the window. Free.","parameters":[{"name":"days","in":"query","description":"How many days to report.","schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"example":3}],"responses":{"200":{"description":"Daily requests and credits, oldest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"},"example":{"object":"usage","days":3,"totals":{"requests":1294,"successful":1288,"failed":6,"credits":58210,"success_rate":0.9954},"daily":[{"date":"2026-10-14","requests":431,"successful":430,"failed":1,"credits":19402},{"date":"2026-10-15","requests":442,"successful":439,"failed":3,"credits":19918},{"date":"2026-10-16","requests":421,"successful":419,"failed":2,"credits":18890}]}}}},"401":{"description":"`UNAUTHORIZED`: missing, unknown or revoked key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"UNAUTHORIZED","message":"Invalid or revoked API key.","param":"api_key","docs":"/docs/errors#unauthorized"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/watchlists":{"post":{"tags":["Watchlists"],"operationId":"createWatchlist","summary":"Create a watchlist","description":"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.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response (`Idempotent-Replayed: true`) instead of creating a second list. Remembered 24 hours.","schema":{"type":"string","maxLength":255},"example":"5f0c8a1b-2d3e-4f56-9a8b-7c6d5e4f3a21"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistCreate"},"example":{"name":"Consoles","platform":"target","marketplace":"us","ids":["83887639","1011697103"],"every":"15m","webhook_url":"https://example.com/hooks/scrapely"}}}},"responses":{"201":{"description":"Created; the first run is due now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Watchlist"},"example":{"id":"wl_3f1c2a9e8d4b4c61","object":"watchlist","name":"Consoles","platform":"target","marketplace":"us","currency":"USD","status":"active","paused_reason":null,"schedule":{"type":"every","every":"15m","every_seconds":900},"every":"15m","every_seconds":900,"refresh_every_runs":8,"webhook_url":"https://example.com/hooks/scrapely","item_count":2,"items_by_state":{"new":2,"active":0,"delisted":0},"asin_count":2,"asins_by_state":{"new":2,"active":0,"delisted":0},"pipeline":{"entry":"check","baseline":null,"refresh":null,"steps":[{"id":"check","scraper":"target.standard","routes":[{"when":"changed","notify":true}]}]},"default_pipeline":true,"estimated_credits":{"pulseRun":0,"refreshRun":0,"newAsins":2},"run_count":0,"consecutive_skips":0,"last_run_at":null,"last_run_status":null,"next_run_at":"2026-10-16T09:15:04.120Z","created_at":"2026-10-16T09:15:04.120Z","updated_at":"2026-10-16T09:15:04.120Z","url":"https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61"}}},"headers":{"Location":{"schema":{"type":"string"},"description":"The watchlist URL."}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_PARAM","message":"`every` must be a number of minutes, hours or days, e.g. \"5m\", \"15m\", \"1h\", \"6h\", \"24h\". Or send `cron` (e.g. \"0 9 * * 1-5\") with a `timezone`.","param":"every","docs":"/docs/errors#invalid_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`DEMO_READ_ONLY`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/IdempotencyMismatch"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}},"get":{"tags":["Watchlists"],"operationId":"listWatchlists","summary":"List watchlists","description":"Your watchlists, newest first, with their schedule, pipeline and last run. Free.","parameters":[{"name":"limit","in":"query","description":"How many lists to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"example":20}],"responses":{"200":{"description":"Newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistList"},"example":{"object":"list","data":[{"id":"wl_3f1c2a9e8d4b4c61","object":"watchlist","name":"Consoles","platform":"target","marketplace":"us","currency":"USD","status":"active","paused_reason":null,"schedule":{"type":"every","every":"15m","every_seconds":900},"every":"15m","every_seconds":900,"refresh_every_runs":8,"webhook_url":"https://example.com/hooks/scrapely","item_count":2,"items_by_state":{"new":0,"active":2,"delisted":0},"asin_count":2,"asins_by_state":{"new":0,"active":2,"delisted":0},"pipeline":{"entry":"check","baseline":null,"refresh":null,"steps":[{"id":"check","scraper":"target.standard","routes":[{"when":"changed","notify":true}]}]},"default_pipeline":true,"estimated_credits":{"pulseRun":2,"refreshRun":2,"newAsins":0},"run_count":42,"consecutive_skips":0,"last_run_at":"2026-10-16T09:15:00.004Z","last_run_status":"completed","next_run_at":"2026-10-16T09:30:00.004Z","created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-16T09:15:21.101Z","url":"https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61"}],"has_more":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/watchlists/{id}":{"get":{"tags":["Watchlists"],"operationId":"getWatchlist","summary":"Get a watchlist","description":"One list, with its item counts per state (`items_by_state`) and the credits its next runs should cost (`estimated_credits`). Free.","parameters":[{"name":"id","in":"path","required":true,"description":"The watchlist id (`wl_…`).","schema":{"type":"string"},"example":"wl_3f1c2a9e8d4b4c61"}],"responses":{"200":{"description":"The watchlist, with item counts per state and credit estimates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Watchlist"},"example":{"id":"wl_3f1c2a9e8d4b4c61","object":"watchlist","name":"Consoles","platform":"target","marketplace":"us","currency":"USD","status":"active","paused_reason":null,"schedule":{"type":"every","every":"15m","every_seconds":900},"every":"15m","every_seconds":900,"refresh_every_runs":8,"webhook_url":"https://example.com/hooks/scrapely","item_count":2,"items_by_state":{"new":0,"active":2,"delisted":0},"asin_count":2,"asins_by_state":{"new":0,"active":2,"delisted":0},"pipeline":{"entry":"check","baseline":null,"refresh":null,"steps":[{"id":"check","scraper":"target.standard","routes":[{"when":"changed","notify":true}]}]},"default_pipeline":true,"estimated_credits":{"pulseRun":2,"refreshRun":2,"newAsins":0},"run_count":42,"consecutive_skips":0,"last_run_at":"2026-10-16T09:15:00.004Z","last_run_status":"completed","next_run_at":"2026-10-16T09:30:00.004Z","created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-16T09:15:21.101Z","url":"https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No watchlist wl_3f1c2a9e8d4b4c61 on this account.","param":"id","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}},"patch":{"tags":["Watchlists"],"operationId":"updateWatchlist","summary":"Update a watchlist","description":"Rename; switch between a cadence (`every`, counted from the last run) and a cron schedule (`cron` + `timezone`); change the webhook, the pipeline or the refresh interval; pause or resume. Send only the fields to change. Free.","parameters":[{"name":"id","in":"path","required":true,"description":"The watchlist id (`wl_…`).","schema":{"type":"string"},"example":"wl_3f1c2a9e8d4b4c61"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistPatch"},"example":{"cron":"0 8 * * 1-5","timezone":"America/New_York"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Watchlist"},"example":{"id":"wl_3f1c2a9e8d4b4c61","object":"watchlist","name":"Consoles","platform":"target","marketplace":"us","currency":"USD","status":"active","paused_reason":null,"schedule":{"type":"cron","cron":"0 8 * * 1-5","timezone":"America/New_York"},"every":null,"every_seconds":null,"refresh_every_runs":8,"webhook_url":"https://example.com/hooks/scrapely","item_count":2,"items_by_state":{"new":0,"active":2,"delisted":0},"asin_count":2,"asins_by_state":{"new":0,"active":2,"delisted":0},"pipeline":{"entry":"check","baseline":null,"refresh":null,"steps":[{"id":"check","scraper":"target.standard","routes":[{"when":"changed","notify":true}]}]},"default_pipeline":true,"estimated_credits":{"pulseRun":2,"refreshRun":2,"newAsins":0},"run_count":42,"consecutive_skips":0,"last_run_at":"2026-10-16T09:15:00.004Z","last_run_status":"completed","next_run_at":"2026-10-19T12:00:00.000Z","created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-16T09:15:04.120Z","url":"https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61"}}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_PARAM","message":"Send either `every` (a cadence) or `cron` (a schedule), not both.","param":"cron","docs":"/docs/errors#invalid_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}},"delete":{"tags":["Watchlists"],"operationId":"deleteWatchlist","summary":"Delete a watchlist","description":"Deletes the list, its items and its run history. A run already in progress finishes but sends no webhooks.","parameters":[{"name":"id","in":"path","required":true,"description":"The watchlist id (`wl_…`).","schema":{"type":"string"},"example":"wl_3f1c2a9e8d4b4c61"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"watchlist"},"deleted":{"const":true}}},"example":{"id":"wl_3f1c2a9e8d4b4c61","object":"watchlist","deleted":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No watchlist wl_3f1c2a9e8d4b4c61 on this account.","param":"id","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/watchlists/{id}/asins":{"post":{"tags":["Watchlists"],"operationId":"editWatchlistAsins","summary":"Add or remove items (legacy path)","deprecated":true,"description":"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.","parameters":[{"name":"id","in":"path","required":true,"description":"The watchlist id (`wl_…`).","schema":{"type":"string"},"example":"wl_2b3c4d5e6f7a8b9c"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50000,"description":"Item ids to add."},"remove":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50000,"description":"Item ids to remove."}}},"example":{"add":["B074PVTPBW"],"remove":["0060094664"]}}}},"responses":{"200":{"description":"What changed.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"watchlist_asins"},"platform":{"type":"string","example":"amazon"},"marketplace":{"type":"string","example":"us"},"added":{"type":"integer"},"reactivated":{"type":"integer","description":"Delisted items added again."},"removed":{"type":"integer"},"unchanged":{"type":"integer","description":"Already present (add) or not present (remove)."},"item_count":{"type":"integer"},"asin_count":{"type":"integer","deprecated":true,"description":"Deprecated alias, same value as `item_count`."}}},"example":{"id":"wl_2b3c4d5e6f7a8b9c","object":"watchlist_asins","platform":"amazon","marketplace":"us","added":1,"reactivated":0,"removed":1,"unchanged":0,"item_count":2400,"asin_count":2400}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No watchlist wl_2b3c4d5e6f7a8b9c on this account.","param":"id","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/watchlists/{id}/run":{"post":{"tags":["Watchlists"],"operationId":"runWatchlist","summary":"Run a watchlist now","description":"Starts a run at once (202). A cadence list (`every`) counts its next run from now; a cron list keeps its wall-clock times, skipping a fire time less than 5 minutes after the manual run. Billed like a scheduled run; works on a paused list. 409 while a run of this list is in progress.","parameters":[{"name":"id","in":"path","required":true,"description":"The watchlist id (`wl_…`).","schema":{"type":"string"},"example":"wl_3f1c2a9e8d4b4c61"}],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WatchlistRun"},{"type":"object","properties":{"runs_url":{"type":"string"}}}]},"example":{"id":"wlrun_5f0c8a1b2d3e4f56","object":"watchlist_run","watchlist_id":"wl_3f1c2a9e8d4b4c61","run_number":42,"trigger":"manual","kind":"sweep","status":"running","credits":0,"stats":null,"error":null,"started_at":"2026-10-16T09:15:04.120Z","finished_at":null,"runs_url":"https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61/runs"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`CONFLICT`: idempotent request in flight, a run already in progress, or a per-account limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CONFLICT","message":"A run of this watchlist is already in progress. It will finish on its own; see GET …/runs.","param":"id","docs":"/docs/errors#conflict"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/watchlists/scrapers":{"get":{"tags":["Watchlists"],"operationId":"listWatchlistScrapers","summary":"List pipeline scrapers","description":"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.","parameters":[{"name":"platform","in":"query","description":"The platform whose scrapers to list.","schema":{"type":"string","default":"amazon"},"example":"walmart"},{"name":"marketplace","in":"query","description":"Marks each scraper `available` or not in this marketplace.","schema":{"type":"string","default":"us"},"example":"us"}],"responses":{"200":{"description":"Scrapers and templates.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"platform":{"type":"string"},"marketplace":{"type":"string"},"branches":{"type":"array","items":{"type":"string"}},"ops":{"type":"array","items":{"type":"string"}},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The `scraper` value of a pipeline step."},"name":{"type":"string"},"description":{"type":"string"},"credits_per_item":{"type":"string","description":"A number, or a range such as `1–3` when it depends on the answer."},"reads":{"type":"string","enum":["pulse","product","offers","offer_check"],"description":"The kind of data it reads; steps of one kind compare with each other."},"input":{"type":"string","enum":["item","offer"],"description":"`offer`: needs the buy-box offer an earlier product or offers step found."},"fields":{"type":"array","description":"What rules can test (`field`).","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["number","money","boolean","text"]}}}},"options":{"type":"object","description":"Step options, when it has any: `condition` for `amazon.offers`.","properties":{"condition":{"type":"array","items":{"type":"string"}}}},"available":{"type":"boolean","description":"Can run in `marketplace`."}}}},"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"pipeline":{"$ref":"#/components/schemas/WatchlistPipeline"}}}}}},"example":{"object":"list","platform":"walmart","marketplace":"us","branches":["new","changed","unchanged","ok","failed","not_found","always"],"ops":["increased","decreased","below","above","is","is_not"],"data":[{"id":"walmart.standard","name":"Product lookup","description":"Price, stock and the rest of what the retailer shows.","credits_per_item":"1","reads":"product","input":"item","fields":[{"key":"price","label":"Price","type":"money"},{"key":"listPrice","label":"List price","type":"money"},{"key":"inStock","label":"In stock","type":"boolean"},{"key":"seller","label":"Seller","type":"text"},{"key":"byPlatform","label":"Sold by Walmart","type":"boolean"},{"key":"clearance","label":"Clearance","type":"boolean"}],"available":true}],"templates":[{"id":"default","name":"Price & stock monitor","description":"Notify when price, stock or seller changes.","pipeline":{"entry":"check","baseline":null,"refresh":null,"steps":[{"id":"check","scraper":"walmart.standard","routes":[{"when":"changed","notify":true}]}]}},{"id":"restock","name":"Back in stock","description":"Notify only when an item comes back in stock.","pipeline":{"entry":"check","baseline":null,"refresh":null,"steps":[{"id":"check","scraper":"walmart.standard","routes":[{"when":"changed","field":"inStock","op":"is","value":true,"notify":true}]}]}},{"id":"price-drop","name":"Price drops","description":"Notify when the price goes down.","pipeline":{"entry":"check","baseline":null,"refresh":null,"steps":[{"id":"check","scraper":"walmart.standard","routes":[{"when":"changed","field":"price","op":"decreased","notify":true}]}]}}]}}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_PARAM","message":"Unknown platform \"wallmart\". Available: amazon, google, walmart, ebay, target, bestbuy, aliexpress.","param":"platform","docs":"/docs/errors#invalid_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/watchlists/{id}/runs":{"get":{"tags":["Watchlists"],"operationId":"listWatchlistRuns","summary":"List runs","description":"The list's runs, newest first, with per-step counts and the credits each run cost. The newest 500 are kept. Free.","parameters":[{"name":"id","in":"path","required":true,"description":"The watchlist id (`wl_…`).","schema":{"type":"string"},"example":"wl_3f1c2a9e8d4b4c61"},{"name":"limit","in":"query","description":"How many runs to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20}],"responses":{"200":{"description":"Runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistRunList"},"example":{"object":"list","data":[{"id":"wlrun_5f0c8a1b2d3e4f56","object":"watchlist_run","watchlist_id":"wl_3f1c2a9e8d4b4c61","run_number":42,"trigger":"schedule","kind":"sweep","status":"completed","credits":2,"stats":{"tracked":2,"entry":"check","new_items":0,"steps":{"check":{"scraper":"target.standard","requested":2,"ok":2,"partial":0,"not_found":0,"unavailable":0,"credits":2,"skipped":0}},"matched":0,"deferred":0,"changed":1,"delisted":0,"retry_next_run":0},"error":null,"started_at":"2026-10-16T09:15:00.004Z","finished_at":"2026-10-16T09:15:02.310Z"}],"has_more":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No watchlist wl_3f1c2a9e8d4b4c61 on this account.","param":"id","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/watchlists/{id}/items":{"get":{"tags":["Watchlists"],"operationId":"listWatchlistItems","summary":"List items","description":"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.","parameters":[{"name":"id","in":"path","required":true,"description":"The watchlist id (`wl_…`).","schema":{"type":"string"},"example":"wl_3f1c2a9e8d4b4c61"},{"name":"changed_since","in":"query","description":"ISO 8601 or epoch milliseconds.","schema":{"type":"string"},"example":"2026-10-15T09:00:00Z"},{"name":"state","in":"query","description":"Only items in this state.","schema":{"type":"string","enum":["new","active","delisted"]}},{"name":"limit","in":"query","description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"example":100},{"name":"starting_after","in":"query","description":"`next_starting_after` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistItemList"},"example":{"object":"list","platform":"target","marketplace":"us","data":[{"id":"83887639","state":"active","added_at":"2026-10-06T08:00:00.000Z","last_status":"ok","pulse":null,"snapshot":{"price":349.99,"regularPrice":399.99,"inStock":true,"shipping":"IN_STOCK","pickup":"IN_STOCK","title":"Nintendo Switch - OLED Model with White Joy-Con","parentTcin":null},"snapshot_at":"2026-10-16T09:15:01.870Z","snapshot_tier":"standard","buybox_above_lowest":false,"pending_standard":false,"changed_at":"2026-10-16T09:15:01.870Z","last_change":{"price":{"before":399.99,"after":349.99}},"delisted_at":null}],"has_more":false,"next_starting_after":"83887639"}}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_PARAM","message":"`changed_since` must be an ISO 8601 timestamp (e.g. 2026-10-16T09:00:00Z) or epoch milliseconds.","param":"changed_since","docs":"/docs/errors#invalid_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}},"post":{"tags":["Watchlists"],"operationId":"editWatchlistItems","summary":"Add or remove items","description":"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.","parameters":[{"name":"id","in":"path","required":true,"description":"The watchlist id (`wl_…`).","schema":{"type":"string"},"example":"wl_9a8b7c6d5e4f3a21"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50000,"description":"Item ids to add."},"remove":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50000,"description":"Item ids to remove."}}},"example":{"add":["6505727"],"remove":["6418599"]}}}},"responses":{"200":{"description":"What changed.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"watchlist_items"},"platform":{"type":"string","example":"amazon"},"marketplace":{"type":"string","example":"us"},"added":{"type":"integer"},"reactivated":{"type":"integer","description":"Delisted items added again."},"removed":{"type":"integer"},"unchanged":{"type":"integer","description":"Already present (add) or not present (remove)."},"item_count":{"type":"integer"},"asin_count":{"type":"integer","deprecated":true,"description":"Deprecated alias, same value as `item_count`."}}},"example":{"id":"wl_9a8b7c6d5e4f3a21","object":"watchlist_items","platform":"bestbuy","marketplace":"us","added":1,"reactivated":0,"removed":1,"unchanged":0,"item_count":120,"asin_count":120}}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_PARAM","message":"add[0] (\"SKU-6505727\") is not a SKU: expected the numeric Best Buy SKU, e.g. 6505727.","param":"add[0]","docs":"/docs/errors#invalid_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/webhook_endpoints":{"get":{"tags":["Webhook endpoints"],"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","description":"Every endpoint on the account, oldest first. Secrets are never returned: `secret_hint` shows the last four characters.","responses":{"200":{"description":"Oldest first. No secrets.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"id":"we_7b1c2d3e4f5a6b7c8d9e","object":"webhook_endpoint","url":"https://example.com/hooks/scrapely","description":"Production","events":["watchlist.product.changed","watchlist.run.completed"],"enabled":true,"secret_hint":"whsec_…9c41","previous_secret_expires_at":null,"created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-06T08:00:00.000Z"}],"has_more":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}},"post":{"tags":["Webhook endpoints"],"operationId":"createWebhookEndpoint","summary":"Create a webhook endpoint","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpointInput"},{"required":["url"]}]},"example":{"url":"https://example.com/hooks/scrapely","description":"Production","events":["watchlist.product.changed","watchlist.run.completed"]}}}},"responses":{"201":{"description":"Created. Save `secret` now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"},"example":{"id":"we_7b1c2d3e4f5a6b7c8d9e","object":"webhook_endpoint","url":"https://example.com/hooks/scrapely","description":"Production","events":["watchlist.product.changed","watchlist.run.completed"],"enabled":true,"secret_hint":"whsec_…9c41","previous_secret_expires_at":null,"created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-06T08:00:00.000Z","secret":"whsec_example_shown_once_store_it_now"}}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_PARAM","message":"`url` must be an absolute https:// URL.","param":"url","docs":"/docs/errors#invalid_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/webhook_endpoints/{id}":{"get":{"tags":["Webhook endpoints"],"operationId":"getWebhookEndpoint","summary":"Get a webhook endpoint","description":"One endpoint, without its secret.","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint id (`we_…`).","schema":{"type":"string"},"example":"we_7b1c2d3e4f5a6b7c8d9e"}],"responses":{"200":{"description":"The endpoint. No secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"},"example":{"id":"we_7b1c2d3e4f5a6b7c8d9e","object":"webhook_endpoint","url":"https://example.com/hooks/scrapely","description":"Production","events":["watchlist.product.changed","watchlist.run.completed"],"enabled":true,"secret_hint":"whsec_…9c41","previous_secret_expires_at":null,"created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-06T08:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No webhook endpoint we_7b1c2d3e4f5a6b7c8d9e on this account.","param":"id","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}},"patch":{"tags":["Webhook endpoints"],"operationId":"updateWebhookEndpoint","summary":"Update a webhook endpoint","description":"Change `url`, `description`, `events` or `enabled`. The secret is unchanged (rotate it separately).","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint id (`we_…`).","schema":{"type":"string"},"example":"we_7b1c2d3e4f5a6b7c8d9e"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointInput"},"example":{"enabled":false}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"},"example":{"id":"we_7b1c2d3e4f5a6b7c8d9e","object":"webhook_endpoint","url":"https://example.com/hooks/scrapely","description":"Production","events":["watchlist.product.changed","watchlist.run.completed"],"enabled":false,"secret_hint":"whsec_…9c41","previous_secret_expires_at":null,"created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-16T09:15:04.120Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No webhook endpoint we_7b1c2d3e4f5a6b7c8d9e on this account.","param":"id","docs":"/docs/errors#not_found"}}}}},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}},"delete":{"tags":["Webhook endpoints"],"operationId":"deleteWebhookEndpoint","summary":"Delete a webhook endpoint","description":"Pending retries to it, and watchlists that name its URL, are recorded as failed deliveries from now on.","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint id (`we_…`).","schema":{"type":"string"},"example":"we_7b1c2d3e4f5a6b7c8d9e"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"webhook_endpoint"},"deleted":{"const":true}}},"example":{"id":"we_7b1c2d3e4f5a6b7c8d9e","object":"webhook_endpoint","deleted":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No webhook endpoint we_7b1c2d3e4f5a6b7c8d9e on this account.","param":"id","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/webhook_endpoints/{id}/rotate":{"post":{"tags":["Webhook endpoints"],"operationId":"rotateWebhookEndpointSecret","summary":"Rotate the signing secret","description":"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).","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint id (`we_…`).","schema":{"type":"string"},"example":"we_7b1c2d3e4f5a6b7c8d9e"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"overlap":{"type":"boolean","default":true}}},"example":{"overlap":true}}}},"responses":{"200":{"description":"Rotated. Save `secret` now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"},"example":{"id":"we_7b1c2d3e4f5a6b7c8d9e","object":"webhook_endpoint","url":"https://example.com/hooks/scrapely","description":"Production","events":["watchlist.product.changed","watchlist.run.completed"],"enabled":true,"secret_hint":"whsec_…77ab","previous_secret_expires_at":"2026-10-17T09:15:04.120Z","created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-16T09:15:04.120Z","secret":"whsec_example_shown_once_store_it_now"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No webhook endpoint we_7b1c2d3e4f5a6b7c8d9e on this account.","param":"id","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/webhook_endpoints/{id}/test":{"post":{"tags":["Webhook endpoints"],"operationId":"testWebhookEndpoint","summary":"Send a test event","description":"One signed `webhook.test` delivery to this endpoint, now, without retries. Recorded in the delivery log.","parameters":[{"name":"id","in":"path","required":true,"description":"The endpoint id (`we_…`).","schema":{"type":"string"},"example":"we_7b1c2d3e4f5a6b7c8d9e"}],"responses":{"200":{"description":"What the endpoint answered.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"webhook_test"},"endpoint_id":{"type":"string"},"delivered":{"type":"boolean"},"status_code":{"oneOf":[{"type":"integer"},{"type":"null"}]},"duration_ms":{"type":"integer"},"error":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"example":{"object":"webhook_test","endpoint_id":"we_7b1c2d3e4f5a6b7c8d9e","delivered":true,"status_code":200,"duration_ms":182,"error":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"No webhook endpoint we_7b1c2d3e4f5a6b7c8d9e on this account.","param":"id","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/exports/s3":{"get":{"tags":["S3 export"],"operationId":"getS3Export","summary":"Get the S3 export destination","description":"The destination with its access key id masked (the secret is never returned), the last connection test, and the 20 most recent uploads. 404 when the account has none.","responses":{"200":{"description":"The destination (keys masked) and its 20 most recent uploads.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/S3Destination"},{"type":"object","properties":{"recent_exports":{"type":"array","items":{"$ref":"#/components/schemas/S3ExportEntry"}}}}]},"example":{"object":"s3_destination","bucket":"my-scrapes","region":"us-east-1","endpoint":null,"path_style":false,"prefix":"scrapely/","enabled":true,"access_key_id":"••••EYID","last_test":{"at":"2026-10-16T08:59:58.000Z","ok":true,"error":null},"created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-16T09:00:00.000Z","recent_exports":[{"id":"s3x_8f7e6d5c4b3a2910","kind":"watchlist","key":"scrapely/watchlists/wl_3f1c2a9e8d4b4c61/wlrun_5f0c8a1b2d3e4f56/watchlist.product.changed-1.json","status":"ok","status_code":200,"error":null,"bytes":2381,"attempt":1,"at":"2026-10-16T09:15:03.002Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"This account has no S3 export destination. Create one with PUT /v1/exports/s3.","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}},"put":{"tags":["S3 export"],"operationId":"putS3Export","summary":"Create or update the S3 export destination","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/S3DestinationInput"},"example":{"bucket":"my-scrapes","region":"us-east-1","access_key_id":"EXAMPLEKEYID","secret_access_key":"example-secret-access-key","prefix":"scrapely/"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/S3Destination"},{"type":"object","properties":{"test":{"oneOf":[{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"string","example":"scrapely/scrapely-connection-test.txt"},"status_code":{"oneOf":[{"type":"integer"},{"type":"null"}]},"code":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"The storage service's error code: `AccessDenied`, `NoSuchBucket`, `InvalidAccessKeyId`, `SignatureDoesNotMatch`, `PermanentRedirect`, …"},"error":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"What went wrong, in plain words."}}},{"type":"null"}]}}}]},"example":{"object":"s3_destination","bucket":"my-scrapes","region":"us-east-1","endpoint":null,"path_style":false,"prefix":"scrapely/","enabled":true,"access_key_id":"••••EYID","last_test":{"at":"2026-10-16T09:15:04.120Z","ok":true,"error":null},"created_at":"2026-10-06T08:00:00.000Z","updated_at":"2026-10-16T09:15:04.120Z","test":{"ok":true,"key":"scrapely/scrapely-connection-test.txt","status_code":200,"code":null,"error":null}}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/S3Destination"},{"type":"object","properties":{"test":{"oneOf":[{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"string","example":"scrapely/scrapely-connection-test.txt"},"status_code":{"oneOf":[{"type":"integer"},{"type":"null"}]},"code":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"The storage service's error code: `AccessDenied`, `NoSuchBucket`, `InvalidAccessKeyId`, `SignatureDoesNotMatch`, `PermanentRedirect`, …"},"error":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"What went wrong, in plain words."}}},{"type":"null"}]}}}]},"example":{"object":"s3_destination","bucket":"my-scrapes","region":"us-east-1","endpoint":null,"path_style":false,"prefix":"scrapely/","enabled":true,"access_key_id":"••••EYID","last_test":{"at":"2026-10-16T09:15:04.120Z","ok":true,"error":null},"created_at":"2026-10-16T09:15:04.120Z","updated_at":"2026-10-16T09:15:04.120Z","test":{"ok":true,"key":"scrapely/scrapely-connection-test.txt","status_code":200,"code":null,"error":null}}}}},"400":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_PARAM","message":"Missing required parameters `access_key_id` and `secret_access_key`.","param":"access_key_id","docs":"/docs/errors#missing_param"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}},"delete":{"tags":["S3 export"],"operationId":"deleteS3Export","summary":"Remove the S3 export destination","description":"Deletes the destination and its stored keys. Nothing more is written to the bucket; objects already there stay.","responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"s3_destination"},"deleted":{"const":true}}},"example":{"object":"s3_destination","deleted":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"This account has no S3 export destination. Create one with PUT /v1/exports/s3.","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/exports/s3/test":{"post":{"tags":["S3 export"],"operationId":"testS3Export","summary":"Test the S3 connection","description":"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.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/S3DestinationInput"}}}},"responses":{"200":{"description":"What the storage service answered.","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"object":{"const":"s3_test"},"duration_ms":{"type":"integer"}}},{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"string","example":"scrapely/scrapely-connection-test.txt"},"status_code":{"oneOf":[{"type":"integer"},{"type":"null"}]},"code":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"The storage service's error code: `AccessDenied`, `NoSuchBucket`, `InvalidAccessKeyId`, `SignatureDoesNotMatch`, `PermanentRedirect`, …"},"error":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"What went wrong, in plain words."}}}]},"example":{"object":"s3_test","ok":true,"key":"scrapely/scrapely-connection-test.txt","status_code":200,"code":null,"error":null,"duration_ms":412}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"This account has no S3 export destination. Create one with PUT /v1/exports/s3.","docs":"/docs/errors#not_found"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}}}},"/api/v1/openapi.json":{"get":{"tags":["Meta"],"operationId":"openapi","summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI 3.1.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/health":{"get":{"tags":["Meta"],"operationId":"health","summary":"Health check","security":[],"responses":{"200":{"description":"Up.","content":{"application/json":{"schema":{"type":"object","required":["status","time"],"properties":{"status":{"const":"ok"},"time":{"type":"string","format":"date-time"}}}}}}}}}},"webhooks":{"watchlistProductChanged":{"post":{"summary":"Watchlist products changed","description":"A notify rule fired on a change: tracked fields moved on one or more items in a run. Each change names the `step` and `scraper` that saw it. Each entry carries `id` (plus `asin` on Amazon lists). At most 500 products per delivery; `part`/`parts` number them. Same envelope (`{ id, type, created_at, data }`), signature and retries as every other webhook. Sent to the list's `webhook_url` endpoint, else to every endpoint subscribed to the event.","parameters":[{"name":"Scrapely-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">`, keyed with the endpoint's secret. Two `v1=` while a rotation overlaps.","schema":{"type":"string"}},{"name":"Scrapely-Event","in":"header","required":true,"description":"The event type, as in the body's `type`.","schema":{"type":"string","enum":["watchlist.product.changed"]}},{"name":"Scrapely-Delivery","in":"header","required":true,"description":"The event id (`evt_…`), the same on every retry: deduplicate on it.","schema":{"type":"string"}},{"name":"Scrapely-Attempt","in":"header","required":true,"description":"1 on the first try, then 2, 3, …","schema":{"type":"integer"}},{"name":"Scrapely-Endpoint","in":"header","required":true,"schema":{"type":"string"},"description":"The id of the receiving endpoint (`we_…`): which secret to verify with."}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"watchlist.product.changed"},"data":{"$ref":"#/components/schemas/WatchlistChangedEvent"}}}]},"example":{"id":"evt_1a2b3c4d5e6f7a8b9c0d","type":"watchlist.product.changed","created_at":"2026-10-16T09:15:04.120Z","data":{"watchlist_id":"wl_3f1c2a9e8d4b4c61","watchlist_name":"Consoles","platform":"target","marketplace":"us","currency":"USD","run_id":"wlrun_5f0c8a1b2d3e4f56","run_number":42,"part":1,"parts":1,"changes":[{"id":"83887639","changed_at":"2026-10-16T09:15:01.870Z","tier":"standard","step":"check","scraper":"target.standard","changes":{"price":{"before":399.99,"after":349.99}},"snapshot":{"price":349.99,"regularPrice":399.99,"inStock":true,"shipping":"IN_STOCK","pickup":"IN_STOCK","title":"Nintendo Switch - OLED Model with White Joy-Con","parentTcin":null}}]}}}}},"responses":{"200":{"description":"Acknowledged. Any 2xx works."}}}},"watchlistProductMatched":{"post":{"summary":"Watchlist products matched","description":"A notify rule fired on a branch other than `changed` (a value test, a failure, `always`…): the step, scraper, branch and the values it saw. At most 500 products per delivery. Same envelope (`{ id, type, created_at, data }`), signature and retries as every other webhook. Sent to the list's `webhook_url` endpoint, else to every endpoint subscribed to the event.","parameters":[{"name":"Scrapely-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">`, keyed with the endpoint's secret. Two `v1=` while a rotation overlaps.","schema":{"type":"string"}},{"name":"Scrapely-Event","in":"header","required":true,"description":"The event type, as in the body's `type`.","schema":{"type":"string","enum":["watchlist.product.matched"]}},{"name":"Scrapely-Delivery","in":"header","required":true,"description":"The event id (`evt_…`), the same on every retry: deduplicate on it.","schema":{"type":"string"}},{"name":"Scrapely-Attempt","in":"header","required":true,"description":"1 on the first try, then 2, 3, …","schema":{"type":"integer"}},{"name":"Scrapely-Endpoint","in":"header","required":true,"schema":{"type":"string"},"description":"The id of the receiving endpoint (`we_…`): which secret to verify with."}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"watchlist.product.matched"},"data":{"$ref":"#/components/schemas/WatchlistMatchedEvent"}}}]},"example":{"id":"evt_2b3c4d5e6f7a8b9c0d1e","type":"watchlist.product.matched","created_at":"2026-10-16T09:15:04.120Z","data":{"watchlist_id":"wl_7c2e9a1b3d4f5e60","watchlist_name":"Under $40","platform":"walmart","marketplace":"us","currency":"USD","run_id":"wlrun_2a3b4c5d6e7f8091","run_number":12,"part":1,"parts":1,"products":[{"id":"5129928603","matched_at":"2026-10-16T09:15:03.512Z","step":"check","scraper":"walmart.standard","branch":"ok","status":"ok","values":{"price":34.97,"listPrice":39.99,"inStock":true,"seller":"Kitchen Outlet LLC","byPlatform":false}}]}}}}},"responses":{"200":{"description":"Acknowledged. Any 2xx works."}}}},"watchlistProductDelisted":{"post":{"summary":"Watchlist products delisted","description":"The retailer answered `not_found` for these items. They stay on the list as `delisted` and are not fetched again. `partial`/`unavailable` never delist. Each entry carries `id` (plus `asin` on Amazon lists). Same envelope (`{ id, type, created_at, data }`), signature and retries as every other webhook. Sent to the list's `webhook_url` endpoint, else to every endpoint subscribed to the event.","parameters":[{"name":"Scrapely-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">`, keyed with the endpoint's secret. Two `v1=` while a rotation overlaps.","schema":{"type":"string"}},{"name":"Scrapely-Event","in":"header","required":true,"description":"The event type, as in the body's `type`.","schema":{"type":"string","enum":["watchlist.product.delisted"]}},{"name":"Scrapely-Delivery","in":"header","required":true,"description":"The event id (`evt_…`), the same on every retry: deduplicate on it.","schema":{"type":"string"}},{"name":"Scrapely-Attempt","in":"header","required":true,"description":"1 on the first try, then 2, 3, …","schema":{"type":"integer"}},{"name":"Scrapely-Endpoint","in":"header","required":true,"schema":{"type":"string"},"description":"The id of the receiving endpoint (`we_…`): which secret to verify with."}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"watchlist.product.delisted"},"data":{"$ref":"#/components/schemas/WatchlistDelistedEvent"}}}]},"example":{"id":"evt_3c4d5e6f7a8b9c0d1e2f","type":"watchlist.product.delisted","created_at":"2026-10-16T09:15:04.120Z","data":{"watchlist_id":"wl_5e6f7a8b9c0d1e2f","watchlist_name":"Headphones","platform":"bestbuy","marketplace":"us","currency":"USD","run_id":"wlrun_9f8e7d6c5b4a3921","run_number":31,"part":1,"parts":1,"products":[{"id":"6418599","delisted_at":"2026-10-16T09:15:01.002Z","detected_by":"standard","step":"check","scraper":"bestbuy.standard","last_snapshot":{"price":129.99,"regularPrice":149.99,"inStock":false,"state":"sold_out","purchasable":false}}]}}}}},"responses":{"200":{"description":"Acknowledged. Any 2xx works."}}}},"watchlistRunCompleted":{"post":{"summary":"Watchlist run completed","description":"Every run that ends: `completed`, `insufficient_credits` (nothing fetched or charged; `watchlist.status` shows an auto-pause) or `failed`. Same envelope (`{ id, type, created_at, data }`), signature and retries as every other webhook. Sent to the list's `webhook_url` endpoint, else to every endpoint subscribed to the event.","parameters":[{"name":"Scrapely-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">`, keyed with the endpoint's secret. Two `v1=` while a rotation overlaps.","schema":{"type":"string"}},{"name":"Scrapely-Event","in":"header","required":true,"description":"The event type, as in the body's `type`.","schema":{"type":"string","enum":["watchlist.run.completed"]}},{"name":"Scrapely-Delivery","in":"header","required":true,"description":"The event id (`evt_…`), the same on every retry: deduplicate on it.","schema":{"type":"string"}},{"name":"Scrapely-Attempt","in":"header","required":true,"description":"1 on the first try, then 2, 3, …","schema":{"type":"integer"}},{"name":"Scrapely-Endpoint","in":"header","required":true,"schema":{"type":"string"},"description":"The id of the receiving endpoint (`we_…`): which secret to verify with."}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"watchlist.run.completed"},"data":{"$ref":"#/components/schemas/WatchlistRunCompletedEvent"}}}]},"example":{"id":"evt_4d5e6f7a8b9c0d1e2f3a","type":"watchlist.run.completed","created_at":"2026-10-16T09:15:04.120Z","data":{"id":"wlrun_5f0c8a1b2d3e4f56","object":"watchlist_run","watchlist_id":"wl_3f1c2a9e8d4b4c61","run_number":42,"trigger":"schedule","kind":"sweep","status":"completed","credits":2,"stats":{"tracked":2,"entry":"check","new_items":0,"steps":{"check":{"scraper":"target.standard","requested":2,"ok":2,"partial":0,"not_found":0,"unavailable":0,"credits":2,"skipped":0}},"matched":0,"deferred":0,"changed":1,"delisted":0,"retry_next_run":0},"error":null,"started_at":"2026-10-16T09:15:00.004Z","finished_at":"2026-10-16T09:15:02.310Z","watchlist":{"id":"wl_3f1c2a9e8d4b4c61","name":"Consoles","platform":"target","marketplace":"us","status":"active","paused_reason":null,"next_run_at":"2026-10-16T09:30:00.004Z"}}}}}},"responses":{"200":{"description":"Acknowledged. Any 2xx works."}}}},"webhookTest":{"post":{"summary":"Test delivery","description":"Sent only by `POST /v1/webhook_endpoints/{id}/test` (or **Send test** in the dashboard), to that endpoint, once and without retries. Signed exactly like every other event, so it proves your verification code end to end.","parameters":[{"name":"Scrapely-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">`, keyed with the endpoint's secret. Two `v1=` while a rotation overlaps.","schema":{"type":"string"}},{"name":"Scrapely-Event","in":"header","required":true,"description":"The event type, as in the body's `type`.","schema":{"type":"string","enum":["webhook.test"]}},{"name":"Scrapely-Delivery","in":"header","required":true,"description":"The event id (`evt_…`), the same on every retry: deduplicate on it.","schema":{"type":"string"}},{"name":"Scrapely-Attempt","in":"header","required":true,"description":"1 on the first try, then 2, 3, …","schema":{"type":"integer"}},{"name":"Scrapely-Endpoint","in":"header","required":true,"schema":{"type":"string"},"description":"The id of the receiving endpoint (`we_…`): which secret to verify with."}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"const":"webhook.test"},"data":{"$ref":"#/components/schemas/WebhookTestEvent"}}}]},"example":{"id":"evt_5e6f7a8b9c0d1e2f3a4b","type":"webhook.test","created_at":"2026-10-16T09:15:04.120Z","data":{"message":"Test delivery from Scrapely.","endpoint_id":"we_7b1c2d3e4f5a6b7c8d9e"}}}}},"responses":{"200":{"description":"Acknowledged. Any 2xx works."}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer sk_live_…`"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"Accepted for clients that cannot set headers. Prefer a header: URLs end up in logs."}},"headers":{"RequestId":{"description":"Unique per request. Quote it to support.","schema":{"type":"string"}},"Credits":{"description":"Credits this request cost (0 when refunded).","schema":{"type":"integer"}},"Balance":{"description":"Your credit balance after this request.","schema":{"type":"integer"}},"RateLimitLimit":{"description":"Calls allowed per window for this key.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Calls left in the current window.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Unix time (seconds) when the window frees a call.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"`MISSING_PARAM` or `INVALID_PARAM`; `param` names the culprit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"`UNAUTHORIZED`: missing, unknown or revoked key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"`INSUFFICIENT_CREDITS`: nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"`NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"`CONFLICT`: idempotent request in flight, a run already in progress, or a per-account limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"IdempotencyMismatch":{"description":"`INVALID_PARAM` with `param: idempotency_key`: the key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"`RATE_LIMITED` or `CONCURRENCY_LIMIT`. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"ComingSoon":{"description":"`NOT_IMPLEMENTED` with `\"message\": \"Coming soon\"` and `\"coming_soon\": true`. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComingSoon"}}}},"TargetFailed":{"description":"`TARGET_FAILED`: the retailer blocked us, errored, or timed out after retries. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Internal":{"description":"`INTERNAL`: our fault, not charged. Quote `X-Request-Id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["MISSING_PARAM","INVALID_PARAM","UNAUTHORIZED","DEMO_READ_ONLY","INSUFFICIENT_CREDITS","NOT_FOUND","GONE","CONFLICT","CONCURRENCY_LIMIT","RATE_LIMITED","TARGET_FAILED","UNAVAILABLE","NOT_IMPLEMENTED","INTERNAL"],"description":"Stable, machine-readable. Branch on this, never on `message`."},"message":{"type":"string","description":"Human-readable; may change."},"param":{"type":"string","description":"The parameter at fault, when there is one."},"docs":{"type":"string","description":"Link to this code on /docs/errors.","example":"/docs/errors#insufficient_credits"}}}}},"Price":{"type":"object","properties":{"amount":{"type":"number","example":79.99},"currency":{"type":"string","example":"USD"}},"required":["amount","currency"]},"Account":{"type":"object","properties":{"object":{"const":"account"},"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"credit_balance":{"type":"integer","description":"Prepaid credits remaining. They never expire."},"lifetime_credits":{"type":"integer","description":"Credits ever purchased, plus the signup grant. Sets your concurrency tier."},"credits_spent":{"type":"integer"},"concurrency":{"type":"object","properties":{"limit":{"type":"integer"},"in_flight":{"type":"integer"},"next_tier":{"oneOf":[{"type":"object","properties":{"concurrency":{"type":"integer"},"at_lifetime_credits":{"type":"integer"}}},{"type":"null"}]}}},"auto_topup":{"oneOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"threshold_credits":{"type":"integer"},"pack_id":{"type":"string"}}},{"type":"null"}]},"webhook_endpoints":{"type":"integer","description":"Registered webhook endpoints (`GET /v1/webhook_endpoints` lists them)."},"api_key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"}}},"Usage":{"type":"object","properties":{"object":{"const":"usage"},"days":{"type":"integer"},"totals":{"type":"object","properties":{"requests":{"type":"integer"},"successful":{"type":"integer"},"failed":{"type":"integer"},"credits":{"type":"integer"},"success_rate":{"oneOf":[{"type":"number"},{"type":"null"}]}}},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"requests":{"type":"integer"},"successful":{"type":"integer"},"failed":{"type":"integer"},"credits":{"type":"integer"}}}}}},"StructuredResponse":{"type":"object","properties":{"endpoint":{"type":"string","example":"amazon/product"},"url":{"type":"string","description":"The page we fetched."},"credits":{"type":"integer","example":5},"duration_ms":{"type":"integer"},"data":{"type":"object","description":"The endpoint's typed result; see its response schema."}}},"SearchResults":{"type":"object","properties":{"query":{"type":"string"},"page":{"type":"integer"},"total_results":{"oneOf":[{"type":"integer"},{"type":"null"}]},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"},"price":{"oneOf":[{"$ref":"#/components/schemas/Price"},{"type":"null"}]},"rating":{"oneOf":[{"type":"number"},{"type":"null"}]},"reviews_count":{"type":"integer"},"snippet":{"type":"string"},"sponsored":{"type":"boolean"}}}}}},"GoogleSearch":{"allOf":[{"$ref":"#/components/schemas/SearchResults"},{"type":"object","properties":{"organic_results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"},"displayed_url":{"type":"string"},"snippet":{"type":"string"}}}},"related_searches":{"type":"array","items":{"type":"string"}},"people_also_ask":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"snippet":{"type":"string"}}}}}}]},"GoogleShopping":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"},"price":{"$ref":"#/components/schemas/Price"},"merchant":{"type":"string"},"rating":{"oneOf":[{"type":"number"},{"type":"null"}]},"reviews_count":{"type":"integer"}}}}}},"WalmartProduct":{"type":"object","properties":{"product_id":{"type":"string"},"url":{"type":"string"},"title":{"type":"string"},"brand":{"type":"string"},"price":{"oneOf":[{"$ref":"#/components/schemas/Price"},{"type":"null"}]},"rating":{"oneOf":[{"type":"number"},{"type":"null"}]},"reviews_count":{"type":"integer"},"availability":{"type":"string","enum":["in_stock","out_of_stock"]},"images":{"type":"array","items":{"type":"string"}},"specifications":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"EbayProduct":{"type":"object","properties":{"item_id":{"type":"string"},"url":{"type":"string"},"title":{"type":"string"},"condition":{"type":"string","enum":["new","used","refurbished"]},"price":{"oneOf":[{"$ref":"#/components/schemas/Price"},{"type":"null"}]},"shipping":{"oneOf":[{"$ref":"#/components/schemas/Price"},{"type":"null"}]},"seller":{"type":"object","properties":{"name":{"type":"string"},"feedback_score":{"type":"integer"},"positive_percent":{"type":"number"}}},"bids":{"oneOf":[{"type":"integer"},{"type":"null"}]},"ends_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"images":{"type":"array","items":{"type":"string"}}}},"WalmartDetails":{"type":"object","description":"Walmart only (`platform: \"walmart\"`): what Walmart says beyond the neutral fields. Every field is optional: absent when Walmart does not say.","properties":{"brand":{"type":"string","example":"Mainstays"},"upc":{"type":"string","example":"810004819238"},"modelNumber":{"type":"string"},"parentId":{"type":"string","description":"The variant group: items that are variants of one product share it."},"listPrice":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"Walmart's list (\"was\") price. Can be below `price`."},"offerId":{"type":"string","description":"The current offer's id; changes when another offer takes over."},"offerType":{"type":"string","example":"ONLINE_AND_STORE"},"thirdPartySeller":{"type":"boolean","description":"Sold by a marketplace seller rather than Walmart itself."},"onlineAvailable":{"type":"boolean","description":"Offered online. Use `availability.inStock` for whether it can be bought now."},"shipping":{"type":"object","properties":{"standard":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"Standard shipping cost."},"twoDay":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"Two-day shipping cost."},"twoDayEligible":{"type":"boolean"},"freeOverThreshold":{"type":"boolean","description":"Ships free on orders over Walmart's free-shipping minimum."}}},"maxPerOrder":{"type":"integer","description":"Most units one order may contain."},"clearance":{"type":"boolean"},"preOrder":{"type":"boolean"},"condition":{"type":"string","example":"New"},"category":{"type":"string","example":"Home/Appliances/Fans"},"rating":{"type":"number","example":4.4},"reviewsCount":{"type":"integer","example":1250},"size":{"type":"string"},"color":{"type":"string"}}},"ProductsRequest":{"type":"object","description":"Send the items as the generic `ids` (or `asins` on Amazon): one of the two is required. `tier` is required on Amazon. How many per call, and which tiers, depend on the platform: GET /v1/platforms.","properties":{"platform":{"type":"string","default":"amazon","description":"Which platform to read. Platforms: `amazon` (live: us; coming soon: uk, de, fr, it, es, ca, mx, jp, au, in, br, nl, se, pl), `walmart` (live: us), `ebay` (coming soon), `target` (live: us), `bestbuy` (live: us; coming soon: ca), `aliexpress` (coming soon). A coming-soon platform or marketplace answers 501 `NOT_IMPLEMENTED` with `\"coming_soon\": true` (nothing charged); an unknown one is a 400 listing the valid values. GET /v1/platforms has the full list.","example":"amazon"},"marketplace":{"type":"string","default":"us","description":"The platform's regional storefront (`us`, `uk`, `de`…); default the platform's main one. Prices come back in its currency.","example":"us"},"ids":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Required (on Amazon, this or `asins`). The item ids of `platform` (Amazon ASINs, Walmart item ids, Target TCINs, Best Buy SKUs…). De-duplicated; duplicates are fetched and charged once. On Amazon `asins` is accepted instead: send one or the other."},"asins":{"type":"array","minItems":1,"maxItems":10000,"items":{"type":"string","pattern":"^[A-Za-z0-9]{10}$"},"description":"1 to 2,000 ASINs; up to 10,000 at tier `pulse`. Upper-cased and de-duplicated; empty strings are ignored. Duplicates are fetched and charged once.","example":["0060094664","B0009KNLV6","BZZZZZZZZZ"]},"tier":{"type":"string","enum":["pulse","lite","full","standard"],"description":"Required on Amazon; elsewhere optional (default `standard`). `pulse` (0.25 credits per ASIN): New-offer count and lowest new price. The cheapest way to sweep a whole catalogue for change. `lite` (1 credit per ASIN): Everything about the offer: buy-box price and list price, stock, seller, FBA, offer listing id, offer counts, rating and delivery dates. `full` (5 credits per ASIN): Lite plus the listing: description, images, attributes, binding, other editions and offer summaries for every condition. Pulse returns no buy box: its lowest new price equals the buy-box price for ~92% of ASINs, so use it to detect change, not as a price. `standard` was merged into `lite`: it is still accepted and answered as `lite`. Walmart has one tier, `standard` (1 credit per item, the default there): Title, price and list price, stock, seller, fulfilment, shipping, images, brand, UPC, rating and category. Best Buy has one tier, `standard` (1 credit per SKU, the default there): Title, current and regular price, stock, brand, condition and category. Target has one tier, `standard` (1 credit per TCIN, the default there): Title, current and regular price, stock, shipping and store pickup.","example":"lite"},"include":{"type":"array","items":{"type":"string","enum":["delivery"]},"uniqueItems":true,"description":"Accepted and ignored: lite and full always include delivery dates and pulse never does, so `[\"delivery\"]` changes nothing and costs nothing. Echoed back as `include` in the response. Any other entry is a 400.","example":["delivery"]}}},"DeliveryPromise":{"type":"object","required":["earliest","latest"],"properties":{"earliest":{"type":"string","format":"date-time","description":"Earliest promised arrival (ISO 8601, as Amazon sends it)."},"latest":{"type":"string","format":"date-time","description":"Latest promised arrival; equals `earliest` for a single-day promise."},"free":{"type":"boolean","description":"Free delivery. Absent when Amazon does not say."},"cost":{"type":"number","description":"What this delivery option costs, in the Delivery `currency` (0 when free). Absent when Amazon does not say.","example":5.99},"orderBy":{"type":"string","format":"date-time","description":"Order before this time (ISO 8601) to get this promise. Absent when there is no cut-off."},"message":{"type":"string","description":"Amazon's own line, when it sends one.","example":"FREE delivery Monday, October 19"}}},"Delivery":{"type":"object","required":["standard"],"description":"lite + full, at no extra cost: the buy-box offer's delivery promise for an anonymous shopper in the marketplace. Only `standard` is guaranteed; the rest appear when Amazon shows them.","properties":{"standard":{"allOf":[{"$ref":"#/components/schemas/DeliveryPromise"}],"description":"The primary promise shown under the buy box."},"fastest":{"allOf":[{"$ref":"#/components/schemas/DeliveryPromise"}],"description":"The \"Or fastest delivery\" promise, when Amazon offers one."},"isPrime":{"type":"boolean","enum":[true],"description":"The buy-box offer is Prime eligible. Only ever `true`; absent otherwise."},"shipsFrom":{"type":"string","description":"Where the buy-box offer ships from. Absent when Amazon does not say.","example":"Amazon.com"},"freeOver":{"type":"number","description":"Orders at or over this amount ship free (\"FREE delivery on orders over $35\"). Only when the standard option is not free.","example":35},"currency":{"type":"string","description":"ISO 4217 of `cost` and `freeOver`; present with either.","example":"USD"}}},"ProductStatus":{"type":"string","enum":["ok","partial","not_found","unavailable"],"description":"`ok`: returned with no errors (charged). `partial`: returned, but some fields could not be read: do not trust price or stock, re-fetch at a higher tier (refunded). `not_found`: the retailer says the item does not exist: delist, do not retry (charged). `unavailable`: we could not get an answer this time: retry later, not evidence the item is gone (refunded)."},"Buybox":{"type":"object","required":["inStock","isFba"],"properties":{"price":{"type":"number","description":"In `currency`.","example":4.74},"currency":{"type":"string","description":"ISO 4217: the marketplace's currency. Present with `price`.","example":"USD"},"priceDisplay":{"type":"string","description":"lite + full.","example":"$4.74"},"listPrice":{"type":"number","description":"lite + full: the struck-through list or \"was\" price, in `currency`. Only when Amazon shows one above `price`.","example":8.99},"savings":{"type":"object","description":"lite + full: what Amazon says the buyer saves against `listPrice`.","properties":{"percent":{"type":"number","example":47},"amount":{"type":"number","description":"In `currency`.","example":4.25}}},"deal":{"type":"string","description":"lite + full: the deal badge on the buy-box offer, when there is one.","example":"Limited time deal"},"inStock":{"type":"boolean","description":"At least one option has a price and is not OUT_OF_STOCK."},"availabilityType":{"type":"string","example":"IN_STOCK","description":"IN_STOCK, OUT_OF_STOCK, …"},"fulfillerName":{"type":"string","example":"Amazon.com"},"isFba":{"type":"boolean","description":"fulfillerName starts with \"amazon\" (case-insensitive)."},"availabilityMessage":{"type":"string","description":"lite + full.","example":"In Stock"},"condition":{"type":"string","description":"lite + full: NEW, USED, PARENT_ASIN, …","example":"NEW"},"merchant":{"type":"object","description":"lite + full.","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"offerListingId":{"type":"string","description":"lite + full. The buy-box offer listing id, URL-decoded."}}},"ProductOffers":{"type":"object","description":"Every tier. pulse has `newCount` and `newMinPrice` only (lowest new price from any seller, not necessarily the buy box); lite adds used; refurbished and collectible are full only.","properties":{"newCount":{"type":"integer"},"newMinPrice":{"type":"number"},"usedCount":{"type":"integer"},"usedMinPrice":{"type":"number"},"refurbishedCount":{"type":"integer"},"refurbishedMinPrice":{"type":"number"},"collectibleCount":{"type":"integer"},"collectibleMinPrice":{"type":"number"},"currency":{"type":"string","description":"ISO 4217 of the min prices; present with any of them.","example":"USD"}}},"ProductFullDetails":{"type":"object","description":"full only.","required":["images","attributes","variationChildren"],"properties":{"images":{"type":"array","items":{"type":"string"},"description":"One URL per image variant, hi-res preferred: https://m.media-amazon.com/images/I/{id}.{ext}"},"attributes":{"type":"object","additionalProperties":{"type":"string"},"example":{"Publisher":"HarperCollins","Print length":"208 pages"}},"variationChildren":{"type":"array","items":{"type":"string"},"description":"Other editions of the same title (paperback, e-book, hardcover…): books and media. Empty for most products; size and colour variations are not listed."},"binding":{"type":"string","example":"Paperback"}}},"ProductResult":{"type":"object","required":["id","asin","status","fetchedAt"],"description":"One item. The platform-neutral fields (`id`, `price`, `availability`, `seller`, `fulfillment`, `url`, `images`) are the same on every platform; Amazon also keeps its own fields (`asin`, `buybox`, `offers`, `full`, …) at the top level, and other platforms put theirs under a field named after the platform.","properties":{"asin":{"type":"string","example":"B0009KNLV6","description":"Amazon only: the ASIN, equal to `id`."},"id":{"type":"string","description":"The item id as the platform knows it (the ASIN on Amazon).","example":"B0009KNLV6"},"price":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"The featured (buy-box) price, with its currency."},"availability":{"type":"object","required":["inStock"],"properties":{"inStock":{"type":"boolean"},"message":{"type":"string","example":"In Stock"}}},"seller":{"type":"object","required":["name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"fulfillment":{"type":"object","required":["byPlatform"],"properties":{"byPlatform":{"type":"boolean","description":"Shipped by the platform itself (Amazon: FBA)."},"name":{"type":"string"}}},"url":{"type":"string","description":"The product page on the marketplace."},"images":{"type":"array","items":{"type":"string"}},"status":{"$ref":"#/components/schemas/ProductStatus"},"fetchedAt":{"type":"string","format":"date-time","description":"When this item was read."},"buybox":{"allOf":[{"$ref":"#/components/schemas/Buybox"}],"description":"Present for `ok` and `partial` at lite and full. Never at pulse."},"title":{"type":"string","description":"lite + full."},"brand":{"type":"string","description":"lite + full: the brand Amazon shows under the title.","example":"Lumen"},"category":{"type":"string","description":"lite + full: Amazon's display category.","example":"Health and Beauty"},"description":{"type":"array","items":{"type":"string"},"description":"full only: one entry per paragraph."},"offers":{"$ref":"#/components/schemas/ProductOffers"},"reviews":{"type":"object","description":"lite + full.","properties":{"rating":{"type":"number","description":"Star rating, 0–5.","example":4.6},"count":{"type":"string","description":"The review count as Amazon prints it.","example":"1,204"}}},"isParent":{"type":"boolean","description":"lite: a PARENT_ASIN option; full: also no buyable option while the listing lists children."},"full":{"$ref":"#/components/schemas/ProductFullDetails"},"bestbuy":{"$ref":"#/components/schemas/BestBuyExtras"},"walmart":{"$ref":"#/components/schemas/WalmartDetails"},"target":{"$ref":"#/components/schemas/TargetDetails"},"delivery":{"oneOf":[{"$ref":"#/components/schemas/Delivery"},{"type":"null"}],"description":"lite + full, at no extra cost. null when there is no promise (see `deliveryError`). Never at pulse."},"deliveryError":{"type":"string","enum":["not_fetched","no_offer","no_promise","fetch_failed","deadline"],"description":"Only when `delivery` is null. `not_fetched`: the product was not ok/partial. `no_offer`: no buy-box offer. `no_promise`: the offer had no delivery date. `fetch_failed`: we could not get the promise this time (retry later). `deadline`: the call ran out of time."}}},"ProductsResponse":{"type":"object","required":["platform","marketplace","tier","results","stats","credits"],"description":"The envelope every item endpoint returns (`/v1/products`, `/v1/offers`): `platform`, `marketplace`, endpoint fields, `results`, `stats`, `credits`.","properties":{"platform":{"type":"string","example":"amazon","description":"The platform that was read."},"marketplace":{"type":"string","example":"us","description":"The marketplace that was read; every price is in its currency."},"tier":{"type":"string","enum":["pulse","lite","full","standard"],"description":"The tier that answered (`standard` on one-tier platforms)."},"include":{"type":"array","items":{"type":"string","enum":["delivery"]},"description":"Echoes the request's `include`; absent without it. It changes nothing."},"results":{"type":"array","items":{"$ref":"#/components/schemas/ProductResult"},"description":"One per unique requested id, in request order. Every id appears exactly once."},"stats":{"type":"object","required":["requested","ok","partial","notFound","unavailable","elapsedMs"],"properties":{"requested":{"type":"integer","description":"Unique items after de-dup."},"ok":{"type":"integer","description":"Answered in full (charged)."},"partial":{"type":"integer","description":"Answered with fields missing (refunded). Always 0 where an answer cannot be partial (offers)."},"notFound":{"type":"integer","description":"The platform says the item does not exist (charged)."},"unavailable":{"type":"integer","description":"No answer this time (refunded; retry later)."},"elapsedMs":{"type":"integer","description":"How long the call took, in milliseconds."},"delivery":{"type":"object","description":"lite + full.","required":["requested","ok","failed"],"properties":{"requested":{"type":"integer","description":"ASINs a delivery promise was looked up for (the ok + partial ones)."},"ok":{"type":"integer","description":"ASINs with a delivery promise."},"failed":{"type":"integer","description":"requested − ok."}}}}},"credits":{"type":"integer","description":"Credits charged for the call (also `X-Scrapely-Credits`).","example":3}}},"Money":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","example":4.74},"currency":{"type":"string","description":"ISO 4217.","example":"USD"}}},"ItemStats":{"type":"object","required":["requested","ok","partial","notFound","unavailable","elapsedMs"],"properties":{"requested":{"type":"integer","description":"Unique items after de-dup."},"ok":{"type":"integer","description":"Answered in full (charged)."},"partial":{"type":"integer","description":"Answered with fields missing (refunded). Always 0 where an answer cannot be partial (offers)."},"notFound":{"type":"integer","description":"The platform says the item does not exist (charged)."},"unavailable":{"type":"integer","description":"No answer this time (refunded; retry later)."},"elapsedMs":{"type":"integer","description":"How long the call took, in milliseconds."}}},"ComingSoon":{"type":"object","required":["error","coming_soon"],"properties":{"error":{"type":"object","properties":{"code":{"const":"NOT_IMPLEMENTED"},"message":{"const":"Coming soon"},"param":{"type":"string"},"docs":{"type":"string"}}},"coming_soon":{"const":true},"endpoint":{"type":"string","example":"google/search"}}},"MarketplaceComingSoon":{"type":"object","required":["error","coming_soon"],"description":"A platform or marketplace that is announced but not live yet. Nothing is charged.","properties":{"error":{"type":"object","properties":{"code":{"const":"NOT_IMPLEMENTED"},"message":{"type":"string","example":"Amazon UK is coming soon."},"param":{"type":"string","example":"marketplace"},"docs":{"type":"string"}}},"coming_soon":{"const":true}}},"Platform":{"type":"object","required":["id","object","name","status","id_field","default_marketplace","endpoints","marketplaces"],"properties":{"id":{"type":"string","example":"amazon","description":"The `platform` value."},"object":{"const":"platform"},"name":{"type":"string","example":"Amazon"},"status":{"type":"string","enum":["live","coming_soon"]},"id_field":{"type":"string","example":"asins","description":"The request field for item ids (`ids` is always accepted too)."},"id_name":{"type":"string","example":"ASIN"},"default_marketplace":{"type":"string","example":"us"},"endpoints":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"products"},"name":{"type":"string","example":"Product data"},"route":{"type":["string","null"],"example":"POST /v1/products"},"status":{"type":"string","enum":["live","coming_soon"]},"tiers":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"credits_per_item":{"type":"number"},"max_items_per_call":{"type":"integer"}}}}}}},"marketplaces":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"uk","description":"The `marketplace` value."},"name":{"type":"string","example":"Amazon UK"},"country":{"type":["string","null"],"example":"GB"},"currency":{"type":"string","example":"GBP"},"status":{"type":"string","enum":["live","coming_soon"]},"endpoints":{"type":"object","additionalProperties":{"type":"string","enum":["live","coming_soon"]},"example":{"products":"coming_soon","delivery":"coming_soon","offers":"coming_soon"}}}}}}},"PlatformList":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Platform"}}}},"WatchlistSchedule":{"oneOf":[{"type":"object","title":"Every","required":["type","every","every_seconds"],"properties":{"type":{"const":"every"},"every":{"type":"string","example":"15m"},"every_seconds":{"type":"integer","example":900}}},{"type":"object","title":"Cron","required":["type","cron","timezone"],"properties":{"type":{"const":"cron"},"cron":{"type":"string","example":"0 9 * * 1-5"},"timezone":{"type":"string","example":"America/New_York"}}}],"discriminator":{"propertyName":"type"},"description":"When the list runs: a cadence (start to start) or a cron schedule in a time zone."},"WatchlistCreate":{"type":"object","required":["name","ids"],"description":"Send exactly one of `every` (a cadence) and `cron` (a schedule, with an optional `timezone`).","properties":{"name":{"type":"string","maxLength":100},"ids":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50000,"description":"1 to 50,000 item ids of `platform` (ASINs, item ids, TCINs, SKUs…; de-duplicated). A newline- or comma-separated string is also accepted."},"asins":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9]{10}$"},"maxItems":50000,"description":"Amazon only, legacy: the same as `ids` (ASINs are case-insensitive). Send `ids` or `asins`, not both.","deprecated":true},"every":{"type":"string","description":"Cadence, start to start: whole minutes, hours or days, at least 5 minutes, at most 7 days. E.g. `5m`, `15m`, `1h`, `6h`, `24h`. Send this or `cron`.","example":"15m"},"cron":{"type":"string","description":"Standard 5-field cron (minute hour day-of-month month day-of-week) read in `timezone`: `*`, lists (`1,15`), ranges (`9-17`), steps (`*/15`, `0-30/10`), names (`JAN`-`DEC`, `SUN`-`SAT`; 0 and 7 are Sunday), and `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`. No seconds. When both day fields are restricted a day matches either (Vixie cron). Must not fire more often than every 5 minutes. Across DST a skipped local time runs once, shifted forward by the gap, and a repeated one runs once, at its first occurrence. Send this or `every`.","example":"0 9 * * 1-5"},"timezone":{"type":"string","description":"IANA time zone the `cron` is read in, e.g. `America/New_York`, `Europe/London`. Default `UTC`. Only with `cron`.","example":"America/New_York","default":"UTC"},"webhook_url":{"type":"string","description":"One of your registered webhook endpoints (`/v1/webhook_endpoints`), by URL: this list's events go there only, signed with that endpoint's secret. An unregistered URL is a 400. Omitted: every endpoint subscribed to each event."},"webhook_endpoint_id":{"type":"string","description":"Alternative to `webhook_url`: the endpoint's id (`we_…`). Send one or the other."},"refresh_every_runs":{"type":"integer","minimum":0,"maximum":1000,"default":8,"description":"Default pipeline on Amazon: every Nth run sweeps every ASIN at `lite` instead of `pulse` (sees buy-box seller changes at the same price; refreshes offer listing ids). 0 = never. A custom pipeline sets this with `refresh`."},"pipeline":{"$ref":"#/components/schemas/WatchlistPipeline","description":"What each run does. Omitted: the platform default."},"platform":{"type":"string","default":"amazon","description":"Which platform to read. Platforms: `amazon` (live: us; coming soon: uk, de, fr, it, es, ca, mx, jp, au, in, br, nl, se, pl), `walmart` (live: us), `ebay` (coming soon), `target` (live: us), `bestbuy` (live: us; coming soon: ca), `aliexpress` (coming soon). A coming-soon platform or marketplace answers 501 `NOT_IMPLEMENTED` with `\"coming_soon\": true` (nothing charged); an unknown one is a 400 listing the valid values. GET /v1/platforms has the full list.","example":"amazon"},"marketplace":{"type":"string","default":"us","description":"The platform's regional storefront (`us`, `uk`, `de`…); default the platform's main one. Prices come back in its currency.","example":"us"}}},"WatchlistPatch":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"every":{"type":"string","example":"1h","description":"Switch to (or change) a cadence; clears a cron schedule. Send this or `cron`."},"cron":{"type":"string","example":"0 9 * * 1-5","description":"Switch to (or change) a cron schedule. Standard 5-field cron (minute hour day-of-month month day-of-week) read in `timezone`: `*`, lists (`1,15`), ranges (`9-17`), steps (`*/15`, `0-30/10`), names (`JAN`-`DEC`, `SUN`-`SAT`; 0 and 7 are Sunday), and `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`. No seconds. When both day fields are restricted a day matches either (Vixie cron). Must not fire more often than every 5 minutes. Across DST a skipped local time runs once, shifted forward by the gap, and a repeated one runs once, at its first occurrence. Send this or `every`."},"timezone":{"type":"string","example":"Europe/London","description":"With `cron`: its zone (omitted: the list keeps its zone, UTC for a list switching from `every`). Alone: re-zone an existing cron schedule (400 on an every-list)."},"webhook_url":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"A registered endpoint URL; `null` clears it (events go to every subscribed endpoint)."},"webhook_endpoint_id":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Alternative to `webhook_url`: a registered endpoint's id."},"refresh_every_runs":{"type":"integer","minimum":0,"maximum":1000},"pipeline":{"oneOf":[{"$ref":"#/components/schemas/WatchlistPipeline"},{"type":"null"}],"description":"`null` goes back to the platform default. Each item keeps what it last showed."},"status":{"type":"string","enum":["active","paused"],"description":"Resuming clears an auto-pause and its skip count."}}},"Watchlist":{"type":"object","properties":{"id":{"type":"string","example":"wl_3f1c2a9e8d4b4c61"},"object":{"const":"watchlist"},"name":{"type":"string"},"platform":{"type":"string","example":"amazon","description":"Whose item ids the list holds (`id` on each item)."},"marketplace":{"type":"string","example":"us","description":"Every run fetches the list here."},"currency":{"type":"string","example":"USD","description":"The currency of every price in its snapshots, changes and webhooks."},"status":{"type":"string","enum":["active","paused"]},"paused_reason":{"oneOf":[{"type":"string","enum":["user","insufficient_credits"]},{"type":"null"}]},"schedule":{"$ref":"#/components/schemas/WatchlistSchedule"},"every":{"oneOf":[{"type":"string","example":"15m"},{"type":"null"}],"description":"The cadence of an every-list; `null` on a cron list (see `schedule`)."},"every_seconds":{"oneOf":[{"type":"integer"},{"type":"null"}],"description":"The cadence in seconds; `null` on a cron list."},"refresh_every_runs":{"type":"integer"},"pipeline":{"$ref":"#/components/schemas/WatchlistPipeline"},"default_pipeline":{"type":"boolean","description":"True when the list runs its platform default."},"webhook_url":{"oneOf":[{"type":"string"},{"type":"null"}]},"item_count":{"type":"integer","description":"Items on the list, every state."},"items_by_state":{"type":"object","properties":{"new":{"type":"integer"},"active":{"type":"integer"},"delisted":{"type":"integer"}}},"asin_count":{"type":"integer","deprecated":true,"description":"Deprecated alias, same value as `item_count` (every platform)."},"asins_by_state":{"type":"object","properties":{"new":{"type":"integer"},"active":{"type":"integer"},"delisted":{"type":"integer"}},"deprecated":true,"description":"Deprecated alias, same value as `items_by_state` (every platform)."},"estimated_credits":{"type":"object","description":"Up-front cost of the next runs: a sweep run with nothing changed (Amazon: pulse), a refresh run, and the one-off baseline fetch of `new` items (`newAsins`, on every platform). On Amazon, escalations add lite credits per moved ASIN.","properties":{"pulseRun":{"type":"integer"},"refreshRun":{"type":"integer"},"newAsins":{"type":"integer"}}},"run_count":{"type":"integer"},"consecutive_skips":{"type":"integer","description":"Runs skipped in a row for credits; the third pauses the list."},"last_run_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_run_status":{"oneOf":[{"type":"string","enum":["running","completed","insufficient_credits","failed"]},{"type":"null"}]},"next_run_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"null while paused."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"url":{"type":"string"}}},"WatchlistList":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Watchlist"}},"has_more":{"type":"boolean"}}},"WatchlistSnapshot":{"type":"object","description":"The tracked fields from the last detail fetch, named as in `/v1/products` results (each platform tracks its own; these are Amazon's). `null` = the retailer did not say.","properties":{"price":{"oneOf":[{"type":"number"},{"type":"null"}]},"inStock":{"type":"boolean"},"availabilityType":{"oneOf":[{"type":"string"},{"type":"null"}]},"isFba":{"type":"boolean"},"fulfillerName":{"oneOf":[{"type":"string"},{"type":"null"}]},"offerListingId":{"oneOf":[{"type":"string"},{"type":"null"}]},"merchant":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},{"type":"null"}]},"condition":{"oneOf":[{"type":"string"},{"type":"null"}]},"newCount":{"oneOf":[{"type":"integer"},{"type":"null"}]},"newMinPrice":{"oneOf":[{"type":"number"},{"type":"null"}]},"usedCount":{"oneOf":[{"type":"integer"},{"type":"null"}]},"usedMinPrice":{"oneOf":[{"type":"number"},{"type":"null"}]},"title":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"WatchlistItem":{"type":"object","properties":{"id":{"type":"string","example":"B0009KNLV6","description":"The item's id on the list's platform: an ASIN on Amazon, an item id on Walmart, a TCIN on Target, a SKU on Best Buy."},"asin":{"type":"string","deprecated":true,"description":"Amazon lists only: the same value as `id`, kept for clients written before platforms. Absent on every other platform."},"state":{"type":"string","enum":["new","active","delisted"],"description":"`new`: waiting for its first (baseline) fetch. `delisted`: the retailer said not_found; never fetched again (add it again to retry)."},"added_at":{"type":"string","format":"date-time"},"last_status":{"oneOf":[{"type":"string","enum":["ok","partial","not_found","unavailable"]},{"type":"null"}]},"pulse":{"oneOf":[{"type":"object","properties":{"newCount":{"oneOf":[{"type":"integer"},{"type":"null"}]},"newMinPrice":{"oneOf":[{"type":"number"},{"type":"null"}]},"observed_at":{"type":"string","format":"date-time"}}},{"type":"null"}]},"snapshot":{"oneOf":[{"$ref":"#/components/schemas/WatchlistSnapshot"},{"type":"null"}]},"snapshot_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"snapshot_tier":{"oneOf":[{"type":"string","description":"The tier the snapshot came from (Amazon: `lite` or `full`).","example":"full"},{"type":"null"}]},"buybox_above_lowest":{"type":"boolean","description":"The buy box cost more than the lowest new offer at the last fetch, so every run checks it at lite."},"pending_standard":{"type":"boolean","description":"A detail fetch (Amazon: lite) is owed: pulse moved, or the last one failed or was deferred."},"changed_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_change":{"oneOf":[{"type":"object","additionalProperties":{"type":"object","properties":{"before":{},"after":{}},"required":["before","after"]}},{"type":"null"}]},"delisted_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"WatchlistItemList":{"type":"object","properties":{"object":{"const":"list"},"platform":{"type":"string","example":"amazon"},"marketplace":{"type":"string","example":"us"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WatchlistItem"}},"has_more":{"type":"boolean"},"next_starting_after":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"The last `id` of this page."}}},"WatchlistPipeline":{"type":"object","description":"Up to 10 steps, each running one scraper over the items sent to it; its routes send the items on a branch to another step (`run`), the webhook (`notify`), or both. Chains cannot loop.","required":["steps"],"properties":{"entry":{"type":"string","description":"The step every run starts with. Default: the first step."},"baseline":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Where items never read before start instead. Default: `entry`."},"refresh":{"oneOf":[{"type":"object","required":["every_runs","entry"],"properties":{"every_runs":{"type":"integer","minimum":1,"maximum":1000},"entry":{"type":"string"}},"description":"Every Nth run starts at this step instead."},{"type":"null"}]},"steps":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["id","scraper"],"properties":{"id":{"type":"string","pattern":"^[a-z0-9_-]{1,32}$"},"scraper":{"type":"string","enum":["amazon.pulse","amazon.lite","amazon.full","amazon.offers","amazon.offer_check","walmart.standard","target.standard","bestbuy.standard"],"description":"GET /v1/watchlists/scrapers lists them with their fields."},"condition":{"type":"string","enum":["all","new","used"],"description":"`amazon.offers` only."},"routes":{"type":"array","maxItems":8,"items":{"type":"object","required":["when"],"properties":{"when":{"type":"string","enum":["new","changed","unchanged","ok","failed","not_found","always"]},"field":{"type":"string","description":"With `changed`: only this field counts. With `ok`: the field `op` tests."},"op":{"type":"string","enum":["increased","decreased","below","above","is","is_not"]},"value":{"oneOf":[{"type":"number"},{"type":"boolean"},{"type":"string"}]},"run":{"type":"string","description":"A step id to run next for the matching items."},"notify":{"type":"boolean","description":"Send the matching items (`changed`: watchlist.product.changed; else watchlist.product.matched)."}}}}}}}}},"WatchlistMatchedEvent":{"type":"object","properties":{"watchlist_id":{"type":"string","description":"The list (`wl_…`)."},"watchlist_name":{"type":"string"},"platform":{"type":"string","example":"amazon"},"marketplace":{"type":"string","example":"us"},"currency":{"type":"string","example":"USD"},"run_id":{"type":"string","description":"The run (`wlrun_…`): `GET /v1/watchlists/{id}/runs` lists it."},"run_number":{"type":"integer","description":"The run counter of the list, from 1."},"part":{"type":"integer"},"parts":{"type":"integer","description":"How many deliveries this event was split into."},"products":{"type":"array","maxItems":500,"items":{"type":"object","properties":{"id":{"type":"string","example":"B0009KNLV6","description":"The item's id on the list's platform: an ASIN on Amazon, an item id on Walmart, a TCIN on Target, a SKU on Best Buy."},"asin":{"type":"string","deprecated":true,"description":"Amazon lists only: the same value as `id`, kept for clients written before platforms. Absent on every other platform."},"matched_at":{"type":"string","format":"date-time"},"step":{"type":"string"},"scraper":{"type":"string","example":"amazon.offers"},"branch":{"type":"string","enum":["new","changed","unchanged","ok","failed","not_found","always"]},"status":{"type":"string","example":"ok"},"values":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"description":"What the step saw (its scraper fields)."}}}}}},"WatchlistTierStats":{"type":"object","properties":{"requested":{"type":"integer"},"ok":{"type":"integer"},"partial":{"type":"integer"},"not_found":{"type":"integer"},"unavailable":{"type":"integer"},"credits":{"type":"integer"}}},"WatchlistRun":{"type":"object","properties":{"id":{"type":"string","example":"wlrun_5f0c8a1b2d3e4f56"},"object":{"const":"watchlist_run"},"watchlist_id":{"type":"string"},"run_number":{"type":"integer"},"trigger":{"type":"string","enum":["schedule","manual"]},"kind":{"type":"string","enum":["sweep","refresh"],"description":"`sweep`: a regular run from the pipeline's entry step. `refresh`: every Nth run, from the refresh entry (`refresh_every_runs`)."},"status":{"type":"string","enum":["running","completed","insufficient_credits","failed"]},"credits":{"type":"integer","description":"Charged, after refunds."},"stats":{"oneOf":[{"type":"object","properties":{"tracked":{"type":"integer"},"entry":{"type":"string","description":"The step the run started from."},"new_items":{"type":"integer","description":"Items read for the first time."},"steps":{"type":"object","description":"Per step that ran, in run order.","additionalProperties":{"allOf":[{"$ref":"#/components/schemas/WatchlistTierStats"},{"type":"object","properties":{"scraper":{"type":"string"},"skipped":{"type":"integer"}}}]}},"matched":{"type":"integer","description":"Items a notify rule matched on a branch other than `changed`."},"sweep_tier":{"type":"string","deprecated":true,"description":"Runs before pipelines. Amazon: `pulse`, or `lite` on a refresh run. One-tier platforms: their one tier.","example":"pulse"},"calls":{"type":"object","deprecated":true,"description":"Runs before pipelines, keyed by tier.","properties":{"pulse":{"$ref":"#/components/schemas/WatchlistTierStats"},"lite":{"$ref":"#/components/schemas/WatchlistTierStats"},"full":{"$ref":"#/components/schemas/WatchlistTierStats"}},"additionalProperties":{"$ref":"#/components/schemas/WatchlistTierStats"}},"escalated":{"type":"object","deprecated":true,"properties":{"changed":{"type":"integer"},"buybox_above_lowest":{"type":"integer"},"pending":{"type":"integer"}}},"deferred":{"type":"integer","description":"Step items postponed to the next run: the balance could not cover them."},"changed":{"type":"integer"},"delisted":{"type":"integer"},"retry_next_run":{"type":"integer","description":"partial + unavailable items (free, retried next run, never a change)."},"credits_needed":{"type":"integer","description":"On `insufficient_credits`: what the run needed up front."}}},{"type":"null"}]},"error":{"oneOf":[{"type":"string"},{"type":"null"}]},"started_at":{"type":"string","format":"date-time"},"finished_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"WatchlistRunList":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WatchlistRun"}},"has_more":{"type":"boolean"}}},"WatchlistChange":{"type":"object","properties":{"id":{"type":"string","example":"B0009KNLV6","description":"The item's id on the list's platform: an ASIN on Amazon, an item id on Walmart, a TCIN on Target, a SKU on Best Buy."},"asin":{"type":"string","deprecated":true,"description":"Amazon lists only: the same value as `id`, kept for clients written before platforms. Absent on every other platform."},"changed_at":{"type":"string","format":"date-time"},"tier":{"type":"string","example":"lite","description":"The tier that fetched it (Amazon: `lite` or `full`; one-tier platforms: their one tier)."},"step":{"type":"string","example":"check","description":"The pipeline step that saw the change."},"scraper":{"type":"string","example":"amazon.lite","description":"That step's scraper."},"changes":{"type":"object","additionalProperties":{"type":"object","properties":{"before":{},"after":{}},"required":["before","after"]},"description":"Only the fields that moved, each `{ before, after }`. Each platform tracks its own fields; on Amazon: `price`, `inStock`, `availabilityType`, `isFba`, `offerListingId`, `merchant`, `condition`, `newCount`, `newMinPrice`, `usedCount`, `usedMinPrice` (`merchant` compared by id)."},"snapshot":{"$ref":"#/components/schemas/WatchlistSnapshot"}}},"WatchlistChangedEvent":{"type":"object","properties":{"watchlist_id":{"type":"string","description":"The list (`wl_…`)."},"watchlist_name":{"type":"string"},"platform":{"type":"string","example":"amazon"},"marketplace":{"type":"string","example":"us"},"currency":{"type":"string","example":"USD","description":"The currency of every price in this payload."},"run_id":{"type":"string","description":"The run (`wlrun_…`): `GET /v1/watchlists/{id}/runs` lists it."},"run_number":{"type":"integer","description":"The run counter of the list, from 1."},"part":{"type":"integer","description":"1-based; a run with many changes sends several deliveries."},"parts":{"type":"integer","description":"How many deliveries this event was split into."},"changes":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/WatchlistChange"}}}},"WatchlistDelistedEvent":{"type":"object","properties":{"watchlist_id":{"type":"string","description":"The list (`wl_…`)."},"watchlist_name":{"type":"string"},"platform":{"type":"string","example":"amazon"},"marketplace":{"type":"string","example":"us"},"currency":{"type":"string","example":"USD","description":"The currency of every price in this payload."},"run_id":{"type":"string","description":"The run (`wlrun_…`): `GET /v1/watchlists/{id}/runs` lists it."},"run_number":{"type":"integer","description":"The run counter of the list, from 1."},"part":{"type":"integer"},"parts":{"type":"integer","description":"How many deliveries this event was split into."},"products":{"type":"array","maxItems":500,"items":{"type":"object","properties":{"id":{"type":"string","example":"B0009KNLV6","description":"The item's id on the list's platform: an ASIN on Amazon, an item id on Walmart, a TCIN on Target, a SKU on Best Buy."},"asin":{"type":"string","deprecated":true,"description":"Amazon lists only: the same value as `id`, kept for clients written before platforms. Absent on every other platform."},"delisted_at":{"type":"string","format":"date-time"},"detected_by":{"type":"string","description":"The tier that saw it (Amazon: `pulse`, `lite` or `full`; one-tier platforms: their one tier, e.g. `standard`).","example":"standard"},"step":{"type":"string"},"scraper":{"type":"string"},"last_snapshot":{"oneOf":[{"$ref":"#/components/schemas/WatchlistSnapshot"},{"type":"null"}]}}}}}},"WatchlistRunCompletedEvent":{"allOf":[{"$ref":"#/components/schemas/WatchlistRun"},{"type":"object","properties":{"watchlist":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string"},"marketplace":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"paused_reason":{"oneOf":[{"type":"string"},{"type":"null"}]},"next_run_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}}}]},"WebhookEnvelope":{"type":"object","required":["id","type","created_at","data"],"description":"The body of every webhook delivery.","properties":{"id":{"type":"string","example":"evt_1a2b3c4d5e6f7a8b9c0d","description":"The event id. The same on every retry (also `Scrapely-Delivery`): deduplicate on it."},"type":{"type":"string","enum":["watchlist.product.changed","watchlist.product.matched","watchlist.product.delisted","watchlist.run.completed","webhook.test"],"description":"The event (also `Scrapely-Event`)."},"created_at":{"type":"string","format":"date-time","description":"When the event was created (not when this attempt was sent)."},"data":{"type":"object","description":"The event's payload."}}},"WebhookTestEvent":{"type":"object","properties":{"message":{"type":"string","example":"Test delivery from Scrapely."},"endpoint_id":{"type":"string","example":"we_3f9a1c2e4b5d6a7f8e9c","description":"The endpoint being tested."}}},"WebhookEndpoint":{"type":"object","required":["id","object","url","events","enabled","secret_hint","created_at"],"properties":{"id":{"type":"string","example":"we_3f9a1c2e4b5d6a7f8e9c"},"object":{"const":"webhook_endpoint"},"url":{"type":"string","description":"Normalised. A watchlist's `webhook_url` must equal it to be delivered here."},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"events":{"oneOf":[{"type":"array","items":{"type":"string","enum":["watchlist.product.changed","watchlist.product.matched","watchlist.product.delisted","watchlist.run.completed"]}},{"type":"null"}],"description":"Account-wide events this endpoint receives. `null` (the default): every event. `[]`: none — only deliveries that name this endpoint (a watchlist's `webhook_url`), which it always receives."},"enabled":{"type":"boolean","description":"A disabled endpoint receives nothing; deliveries naming it are recorded as failed."},"secret_hint":{"type":"string","example":"whsec_…9c41","description":"The last four characters of the current signing secret. The secret itself is never returned after create or rotate."},"previous_secret_expires_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"During a rotation with overlap: when the previous secret stops signing (a second `v1=` until then, 24 hours after the rotation)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WebhookEndpointWithSecret":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","example":"whsec_5b0e…","description":"The signing secret. Shown this once: store it now (it is kept encrypted and cannot be read back)."}}}]},"WebhookEndpointInput":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS, a public host, port 443 or 1024–65535. Unique per account."},"description":{"oneOf":[{"type":"string","maxLength":120},{"type":"null"}]},"events":{"oneOf":[{"type":"array","items":{"type":"string","enum":["watchlist.product.changed","watchlist.product.matched","watchlist.product.delisted","watchlist.run.completed"]}},{"type":"null"}],"description":"Account-wide events this endpoint receives. `null` (the default): every event. `[]`: none — only deliveries that name this endpoint (a watchlist's `webhook_url`), which it always receives."},"enabled":{"type":"boolean","default":true}}},"S3Destination":{"type":"object","required":["object","bucket","region","prefix","enabled","access_key_id"],"properties":{"object":{"const":"s3_destination"},"bucket":{"type":"string","example":"my-scrapes"},"region":{"type":"string","example":"us-east-1"},"endpoint":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"null: AWS (`https://s3.<region>.amazonaws.com`). Else the https origin of an S3-compatible service."},"path_style":{"type":"boolean","description":"`https://<endpoint>/<bucket>/<key>` instead of `https://<bucket>.<endpoint>/<key>`."},"prefix":{"type":"string","example":"scrapely/"},"enabled":{"type":"boolean","description":"On: every watchlist event is written to `<prefix>watchlists/<watchlist_id>/<run_id>/<event>-<part>.json`."},"access_key_id":{"type":"string","example":"••••MPLE","description":"Masked: the last four characters only. The secret access key is never returned."},"last_test":{"oneOf":[{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"ok":{"type":"boolean"},"error":{"oneOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"S3DestinationInput":{"type":"object","properties":{"bucket":{"type":"string","description":"S3 bucket naming rules: 3–63 lowercase letters, numbers, dots and hyphens."},"region":{"type":"string","description":"An AWS region (us-east-1, us-east-2, us-west-1, us-west-2, …). With `endpoint`: the region that service signs with, e.g. `auto` for Cloudflare R2."},"access_key_id":{"type":"string","writeOnly":true,"description":"Send with `secret_access_key` to set or replace the keys; leave both out to keep the stored ones."},"secret_access_key":{"type":"string","writeOnly":true,"description":"Write-only. Stored encrypted (AES-256-GCM) and never returned."},"prefix":{"type":"string","default":"scrapely/","description":"Key prefix for everything written. `\"\"` for the bucket root."},"endpoint":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"An S3-compatible service: https only, a public host, port 443 or 1024–65535, no path. null for AWS."},"path_style":{"type":"boolean","description":"Default: true with `endpoint`, false for AWS."},"enabled":{"type":"boolean","default":true,"description":"`true` needs a passing connection test."},"test":{"type":"boolean","default":true,"description":"Write `<prefix>scrapely-connection-test.txt` before saving. `false` skips it (allowed with `enabled: true` only when the bucket, region, endpoint, prefix and keys are unchanged since a passing test)."}}},"S3ExportEntry":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["watchlist","test"]},"key":{"type":"string"},"status":{"type":"string","enum":["ok","failed"]},"status_code":{"oneOf":[{"type":"integer"},{"type":"null"}]},"error":{"oneOf":[{"type":"string"},{"type":"null"}]},"bytes":{"type":"integer"},"attempt":{"type":"integer"},"at":{"type":"string","format":"date-time"}}},"OffersRequest":{"type":"object","description":"Send the items as `asins` (Amazon) or the generic `ids`.","properties":{"platform":{"type":"string","default":"amazon","description":"Which platform to read. Platforms: `amazon` (live: us; coming soon: uk, de, fr, it, es, ca, mx, jp, au, in, br, nl, se, pl), `walmart` (live: us), `ebay` (coming soon), `target` (live: us), `bestbuy` (live: us; coming soon: ca), `aliexpress` (coming soon). A coming-soon platform or marketplace answers 501 `NOT_IMPLEMENTED` with `\"coming_soon\": true` (nothing charged); an unknown one is a 400 listing the valid values. GET /v1/platforms has the full list.","example":"amazon"},"marketplace":{"type":"string","default":"us","description":"The platform's regional storefront (`us`, `uk`, `de`…); default the platform's main one. Prices come back in its currency.","example":"us"},"ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"description":"The generic name for the item list (`asins` on Amazon)."},"asins":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^[A-Za-z0-9]{10}$"},"description":"1 to 100 ASINs. Upper-cased and de-duplicated; empty strings are ignored. Duplicates are fetched and charged once.","example":["B0009KNLV6","BZZZZZZZZZ"]},"condition":{"type":"string","enum":["new","used","all"],"default":"all","description":"`all` (default), `new`, or `used` (every non-new condition: used, renewed/refurbished, collectible)."}}},"Offer":{"type":"object","required":["offerListingId","price","condition","seller","fulfillment","isBuybox"],"properties":{"offerListingId":{"type":"string","description":"Identifies this exact offer."},"price":{"type":"number","description":"In `currency`.","example":77.43},"currency":{"type":"string","description":"ISO 4217: the currency of the marketplace, for `price` and `shipping`.","example":"USD"},"priceDisplay":{"type":"string","example":"$77.43"},"shipping":{"type":"number","description":"In `currency`; 0 for free delivery; absent when Amazon does not state it.","example":0},"condition":{"type":"string","description":"`new`, `used_like_new`, `used_very_good`, `used_good`, `used_acceptable`, `refurbished`, `collectible_*`.","example":"new"},"conditionNote":{"type":"string","description":"The seller's condition comment."},"seller":{"type":"object","required":["name"],"properties":{"id":{"type":"string","description":"Merchant id (Amazon itself on the us marketplace is `ATVPDKIKX0DER`).","example":"A2R2RITDJNW1Q6"},"name":{"type":"string","example":"Retro Lunch Co"},"rating":{"type":"number","description":"Stars, 0–5.","example":4.5},"ratingCount":{"type":"integer","example":1287}}},"fulfillment":{"type":"object","required":["isFba"],"properties":{"isFba":{"type":"boolean","description":"Shipped by Amazon."},"fulfillerName":{"type":"string","example":"Amazon.com"}}},"isBuybox":{"type":"boolean","description":"The featured (buy-box) offer."},"availability":{"type":"string","example":"Only 3 left in stock - order soon."},"delivery":{"type":"string","description":"The delivery promise as Amazon words it.","example":"FREE delivery Tuesday, October 21"}}},"OffersResult":{"type":"object","required":["id","asin","status","fetchedAt","offers"],"properties":{"id":{"type":"string","description":"The item id (the ASIN on Amazon).","example":"B0009KNLV6"},"asin":{"type":"string","example":"B0009KNLV6"},"status":{"type":"string","enum":["ok","not_found","unavailable"],"description":"`ok`: the offer list was read (charged; may be empty). `not_found`: Amazon has no such product (charged). `unavailable`: we could not get an answer this time, or the call ran out of time (refunded; retry later)."},"fetchedAt":{"type":"string","format":"date-time","description":"When this item was read."},"buyboxOfferListingId":{"type":"string","description":"The featured offer, when there is one (reported even if `condition` filters it out of `offers`)."},"totalOffers":{"type":"integer","minimum":0,"description":"Offers on the listing in every condition, the buy box included. 1 or less: charged the single-offer rate."},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"},"description":"Featured offer first, then the rest cheapest first. Every offer for the ASIN, up to 31."}}},"OfferCheckRequest":{"type":"object","required":["offers"],"properties":{"platform":{"type":"string","default":"amazon","description":"Which platform to read. Platforms: `amazon` (live: us; coming soon: uk, de, fr, it, es, ca, mx, jp, au, in, br, nl, se, pl), `walmart` (live: us), `ebay` (coming soon), `target` (live: us), `bestbuy` (live: us; coming soon: ca), `aliexpress` (coming soon). A coming-soon platform or marketplace answers 501 `NOT_IMPLEMENTED` with `\"coming_soon\": true` (nothing charged); an unknown one is a 400 listing the valid values. GET /v1/platforms has the full list.","example":"amazon"},"marketplace":{"type":"string","default":"us","description":"The platform's regional storefront (`us`, `uk`, `de`…); default the platform's main one. Prices come back in its currency.","example":"us"},"offers":{"type":"array","minItems":1,"maxItems":2000,"items":{"type":"object","required":["asin","offerListingId"],"properties":{"asin":{"type":"string","example":"B0009KNLV6"},"offerListingId":{"type":"string","example":"pQ4/z9Lr0sT="}}},"description":"1 to 2000 offers, each its ASIN and offer listing id as /v1/products (`asin` + `buybox.offerListingId`) or /v1/offers (`asin` + `offers[].offerListingId`) returned them. Both are required. `ids` is accepted too."}}},"OfferCheckResult":{"type":"object","required":["id","asin","offerListingId","status","fetchedAt"],"properties":{"id":{"type":"string","description":"The offer listing id."},"asin":{"type":"string"},"offerListingId":{"type":"string"},"status":{"type":"string","enum":["ok","unavailable"],"description":"`ok`: answered (charged). `unavailable`: no answer this time (refunded; retry later)."},"fetchedAt":{"type":"string","format":"date-time","description":"When this item was read."},"buyable":{"type":"boolean","description":"On `ok`: Amazon accepts this exact offer for purchase right now. Scarce, backorder and pre-order offers are buyable; no price or stock level. `false` does not say why (a gone offer and a mistyped id read the same)."}}},"OfferCheckResponse":{"type":"object","required":["platform","marketplace","results","stats","credits"],"properties":{"platform":{"type":"string","example":"amazon"},"marketplace":{"type":"string","example":"us"},"results":{"type":"array","items":{"$ref":"#/components/schemas/OfferCheckResult"},"description":"One per unique requested id, in request order."},"stats":{"type":"object","required":["requested","ok","partial","notFound","unavailable","elapsedMs"],"properties":{"requested":{"type":"integer","description":"Unique items after de-dup."},"ok":{"type":"integer","description":"Answered in full (charged)."},"partial":{"type":"integer","description":"Answered with fields missing (refunded). Always 0 where an answer cannot be partial (offers)."},"notFound":{"type":"integer","description":"The platform says the item does not exist (charged)."},"unavailable":{"type":"integer","description":"No answer this time (refunded; retry later)."},"elapsedMs":{"type":"integer","description":"How long the call took, in milliseconds."}}},"credits":{"type":"integer","description":"Credits charged for the call (also `X-Scrapely-Credits`).","example":1}}},"OffersResponse":{"type":"object","required":["platform","marketplace","results","stats","credits"],"description":"The same envelope as /v1/products.","properties":{"platform":{"type":"string","example":"amazon"},"marketplace":{"type":"string","example":"us"},"results":{"type":"array","items":{"$ref":"#/components/schemas/OffersResult"},"description":"One per unique requested ASIN, in request order."},"stats":{"type":"object","required":["requested","ok","partial","notFound","unavailable","elapsedMs"],"properties":{"requested":{"type":"integer","description":"Unique items after de-dup."},"ok":{"type":"integer","description":"Answered in full (charged)."},"partial":{"type":"integer","description":"Answered with fields missing (refunded). Always 0 where an answer cannot be partial (offers)."},"notFound":{"type":"integer","description":"The platform says the item does not exist (charged)."},"unavailable":{"type":"integer","description":"No answer this time (refunded; retry later)."},"elapsedMs":{"type":"integer","description":"How long the call took, in milliseconds."}}},"credits":{"type":"integer","description":"Credits charged for the call (also `X-Scrapely-Credits`).","example":5}}},"BestBuyExtras":{"type":"object","required":["sku","state","purchasable","onSale"],"description":"Best Buy only (`platform: \"bestbuy\"`): what Best Buy says beyond the neutral fields.","properties":{"sku":{"type":"string","example":"6505727"},"state":{"type":"string","enum":["available","sold_out","in_store_only","pre_order","coming_soon","queue","unavailable","other"],"description":"Where the product stands for an online shopper. `available`: can be bought online now (the only state where `availability.inStock` is true). `sold_out`: sold out online. `in_store_only`: only through a store. `pre_order`, `coming_soon`: not shipping yet. `queue`: released in limited drops. `unavailable` / `other`: not buyable online at the moment.","example":"available"},"purchasable":{"type":"boolean","description":"Best Buy says it can be bought at all (online or in store)."},"brand":{"type":"string","example":"Sony"},"condition":{"type":"string","example":"new"},"regularPrice":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"The regular (non-sale) price."},"savings":{"allOf":[{"$ref":"#/components/schemas/Money"}],"description":"regularPrice − price; present when on sale."},"onSale":{"type":"boolean","description":"The current price is below the regular price."},"category":{"type":"object","properties":{"department":{"type":"string","example":"AUDIO"},"class":{"type":"string","example":"HEADPHONES"},"subclass":{"type":"string","example":"WIRELESS ON/OVER EAR"}}}}},"TargetDetails":{"type":"object","required":["tcin","soldOut"],"description":"Target only (`platform: \"target\"`): what Target says beyond the neutral fields. Stock and pickup are for one reference store.","properties":{"tcin":{"type":"string","description":"The item that was priced: the requested TCIN, or for a variation parent its featured variant.","example":"83887639"},"parentTcin":{"type":"string","description":"The variation parent, when the item has one.","example":"1011697103"},"brand":{"type":"string"},"priceDisplay":{"type":"string","description":"Target's own price text (may be a range).","example":"$399.99"},"regularPrice":{"type":"number","description":"The regular (non-sale) price, in the marketplace currency.","example":399.99},"unitPrice":{"type":"string","example":"$0.06/fluid ounce"},"itemType":{"type":"string","example":"Video Game Consoles"},"soldOut":{"type":"boolean","description":"Sold out online and in every store."},"shipping":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"IN_STOCK, LIMITED_STOCK, OUT_OF_STOCK, UNAVAILABLE, …","example":"IN_STOCK"},"free":{"type":"boolean"},"minDeliveryDate":{"type":"string","format":"date"},"maxDeliveryDate":{"type":"string","format":"date"}}},"pickup":{"type":"object","required":["status","storeId"],"properties":{"status":{"type":"string","description":"IN_STOCK, LIMITED_STOCK, OUT_OF_STOCK, UNAVAILABLE, …","example":"IN_STOCK"},"storeId":{"type":"string"},"storeName":{"type":"string"},"quantity":{"type":"number"},"date":{"type":"string","format":"date"}}},"sameDayDelivery":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"IN_STOCK, LIMITED_STOCK, OUT_OF_STOCK, UNAVAILABLE, …","example":"IN_STOCK"}}}}}},"parameters":{"Platform":{"name":"platform","in":"query","required":false,"schema":{"type":"string","default":"amazon"},"description":"Which platform to read. Platforms: `amazon` (live: us; coming soon: uk, de, fr, it, es, ca, mx, jp, au, in, br, nl, se, pl), `walmart` (live: us), `ebay` (coming soon), `target` (live: us), `bestbuy` (live: us; coming soon: ca), `aliexpress` (coming soon). A coming-soon platform or marketplace answers 501 `NOT_IMPLEMENTED` with `\"coming_soon\": true` (nothing charged); an unknown one is a 400 listing the valid values. GET /v1/platforms has the full list."},"Marketplace":{"name":"marketplace","in":"query","required":false,"schema":{"type":"string","default":"us"},"description":"The platform's regional storefront (`us`, `uk`, `de`…); default the platform's main one. Prices come back in its currency."}}}}