WebScrapingAPI Docs
Retailer APIsTarget Search APIGetting Started

API Parameters

Target 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.

ParameterRequiredTypeDescription
api_keyYesstringYour WebScrapingAPI key with Target access.
engineYesstringtarget for the default synchronous workflow, or target_async to submit in the background.
typeNostringproduct (default), progress, or snapshot.
asyncNobooleantrue or 1 submits a background job; false or 0 waits up to 120 seconds in total for results. Defaults to false for target. target_async always submits asynchronously.
discover_byNostringOmit for product lookup. Use keywords, url (category URL), or upc for discovery. Applies to the entire request.
custom_output_fieldsNostringPipe-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_errorsNobooleanInclude individual input errors in the returned records. Defaults to true.
limit_per_inputNopositive integerLimit returned records for each input.
formatNostringOutput format. Only json is supported.
snapshot_idFor pollingstringReturned job ID; required for type=progress or type=snapshot.

Boolean query options accept true, false, 1, or 0. engine=target_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=target_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 one product locator for each input. For GET, place the input fields in the query string. For POST, place them in each body object.

ParameterRequiredTypeDescription
urlOne product locatorstringHTTPS Target product page URL on target.com or www.target.com, with a path ending in /-/A- followed by the product's numeric ID. URLs must not contain credentials or a custom port. Use instead of product_id.
product_idOne product locatorstringTarget product ID, such as A-89846564 or 89846564. Use instead of url.
zipcodeNostringFive-digit US ZIP code, such as 10001. Keep it as text so leading zeroes are preserved.
all_variationsNobooleanRequest available product variations. Use JSON true or false in a body object.

Optional input fields can also be supplied in the query string as batch defaults; a value in a body object overrides that default. Do not combine a POST input array with product locators, keywords, or UPC in the query string. Fields that do not belong to the selected collection mode are rejected.

Discovery inputs

Set type=product and choose one discover_by value. All objects in a batch use the same discovery mode. zipcode and all_variations are available in every mode.

discover_byRequired inputPurpose
keywordskeywords (non-empty string)Find Target products for a search phrase, such as wireless headphones.
urlurl (Target category URL)Discover products from a Target category page.
upcupc (string of 8–14 digits)Find products by UPC. Keep the identifier as text to preserve leading zeroes.

Category discovery (discover_by=url) also accepts these fields in each input:

ParameterRequiredTypeDescription
begin_pageNopositive integerStarting category page; minimum 1.
shipping_typeNostringShipping option used for category discovery.
limitationsNoarray of stringsCategory discovery limitations. Send a JSON array in POST inputs, or a JSON-encoded array in a GET query value.
max_productNopositive integerMaximum number of products requested for the category input; minimum 1.

Discovery returns records for matching products or discovered product URLs. To collect full details for a returned URL, use it in a product lookup with discover_by omitted. See product data for the available output fields.

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 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=target, 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 Target Product for synchronous examples and Target Async for complete submission and polling samples in all supported languages.

On this page