API Parameters
Best Buy Search API request parameters.
Send requests to https://ecom.webscrapingapi.com/v1. Use GET for one input or POST with Content-Type: application/json and a non-empty JSON array of input objects for a batch.
Request and execution options
These parameters belong in the query string for both GET and POST requests.
| Parameter | Required | Type | Description |
|---|---|---|---|
api_key | Yes | string | Your WebScrapingAPI key with Best Buy access. |
engine | Yes | string | bestbuy for the default synchronous workflow, or bestbuy_async to submit in the background. |
type | No | string | product (default), progress, or snapshot. |
async | No | boolean | true or 1 submits a background job; false or 0 waits up to 120 seconds in total for results. Defaults to false for bestbuy. bestbuy_async always submits asynchronously. |
discover_by | No | string | Omit for product lookup. Use keywords for keyword discovery. Applies to the entire request. |
custom_output_fields | No | string | Pipe-separated product fields to return, for example url|product_id|title|final_price|currency. Field availability depends on the selected collection mode and product. |
include_errors | No | boolean | Include individual input errors in the returned records. Defaults to true. |
limit_per_input | No | positive integer | Limit returned records for each input. |
format | No | string | Output format. Only json is supported. |
snapshot_id | For polling | string | Returned job ID; required for type=progress or type=snapshot. |
Boolean query options accept true, false, 1, or 0. engine=bestbuy_async forces asynchronous submission regardless of the async value. Synchronous HTTP 200 responses contain results. Allow at least 125 seconds in your client. If an accepted job is still running at the synchronous deadline, HTTP 504 returns error_code=bestbuy_sync_timeout, status=running, and a snapshot_id. The job continues; use the retrieval workflow for that ID without resubmitting. See synchronous errors and recovery.
Product inputs
When discover_by is omitted, provide a Best Buy product URL for each input. For GET, place input fields in the query string. For POST, place them in each body object.
| Parameter | Required | Type | Description |
|---|---|---|---|
url | Yes | string | HTTPS Best Buy product page URL on bestbuy.com or www.bestbuy.com. URLs must not contain credentials or a custom port. |
all_variations | No | boolean | Collect available product variations. Use JSON true or false in a body object. Only supported for product URL inputs. |
all_variations can also be supplied in the query string as a batch default; a value in a body object overrides that default. Do not combine a POST input array with url or keywords in the query string. Fields that do not belong to the selected collection mode are rejected.
Keyword discovery
Set type=product and discover_by=keywords, then provide a non-empty keywords string for each input. For example, use wireless headphones to discover matching product URLs. GET accepts the keyword string in the query; POST accepts an array of objects containing keywords.
Keyword discovery returns product URLs. Submit those URLs in a new product lookup with discover_by omitted to collect full product details. The lookup is a separate, billable submission. Discovery inputs do not accept url or all_variations; category, UPC, and product ID shortcuts are not supported.
Limits and credits
Synchronous requests accept up to 20 input objects. Asynchronous requests accept up to 5000 input objects. Split larger workloads into separate requests. GET accepts one input; use POST for multiple inputs.
Product submissions initially use one credit per input object. When collection finishes, credits for confirmed failed inputs are refunded automatically, including failures discovered after a synchronous HTTP 504 or 502 response carrying a snapshot_id. Refund processing continues in the background even if you do not poll. A synchronous timeout by itself does not mean the collection failed.
For example, a batch of 100 products with 93 successful inputs and 7 failed inputs initially uses 100 credits, then receives a 7-credit refund. The final charge is 93 credits. Repeated polling does not repeat a refund. Discovery and product variation expansion can return multiple records for one input; an input that returns successful product data remains billable. Missing prices or out-of-stock products are not automatically treated as failed inputs.
Progress and snapshot retrieval consume zero additional credits. Your key must remain active and authorized when polling. Do not automatically resubmit an accepted job; a new submission creates a separate job and may consume additional credits.
Polling
Use GET with engine=bestbuy, type=progress, and snapshot_id to check a job, or type=snapshot to retrieve its results. Do not include product or discovery inputs in polling requests. The shared GET polling form with only api_key and snapshot_id is also supported.
See Best Buy Product for synchronous examples and Best Buy Async for complete submission and polling samples in all supported languages.