Skip to content
/Batch endpoints

Batch endpoints

Standard batches up to 1 000 values. Poll for results, then download. Results are retained for 72 hours.

Operations

Submit a batch job

Request

Submit a list of values to crawl. Returns immediately with a job object; results are assembled asynchronously.

The request schema is discriminated on source. Select the source tab below to see the valid key, topic, and country values for that source.

Security
ApiKeyAuth or BearerAuth or BasicAuth
Bodyapplication/jsonrequired
sourcestringrequired
Value:"idealo"
Discriminator
countrystringrequired

ISO 3166-1 alpha-2 country code (lowercase).

Enum:"de""at""uk""gb""fr""it""es"
Example:"de"
keystring

Type of values being submitted. Valid values depend on source.

Default:"term"
Enum:"term""id""gtin""pzn"
topicstring

Processing mode. Valid values depend on source.

Default:"search"
Enum:"search""convert""remove_conversions"
valuesArray of strings, <= 1000 itemsrequired

Values to query. Maximum 1 000 per request. Duplicates are removed.

A comma-separated string is also accepted as a convenience form ("a,b,c" → ["a","b","c"]), but is not compatible with key: product — product values contain commas internally.

Example:
[
  "4006381333962",
  "4719512101148"
]
max_pagesinteger, [ 1 .. 10 ]

Number of result pages to fetch per value. Applicable to Idealo and Amazon. Ignored by Google and eBay.

Default:1
max_ageinteger, [ 0 .. 259200 ]

Maximum acceptable age of a result, in seconds. Default: 1200 (20 minutes). Maximum: 259200 (3 days) — the retention period for results; larger values are clamped.

When a value was already crawled inside this window, the stored result is returned without re-crawling it and the response is not charged. Set to 0 to always force a fresh crawl.

Available on eligible accounts; elsewhere every value is always crawled fresh.

Default:1200
sort_bystring

Sort order for offers within each result.

Default:"ranking_descending"
timeoutinteger, [ 1 .. 1440 ]

Job hard timeout in minutes. The job is forcibly finished with whatever partial results exist after this time. Default: 1 440 (24 h).

Default:1440
callback_urlstring or null, (uri)

Webhook URL to receive results when the job finishes. For incremental push delivery, use the Stream endpoint instead.

not_found_max_ageinteger, >= 1

How many days a not-found cache entry is honoured before the product is re-queried. Applies to GTIN and PZN lookups (Idealo gtin/pzn, Amazon gtin, Google product). Set to 1 to force a fresh lookup on the next job after a single day. Ignored for term and id keys.

Default:10
include_metaboolean

When true, each result carries a meta provenance block — the crawl trail (meta.crawls[]) with URL, HTTP status, timing and observation timestamp per fetch. See Audit & provenance.

Default:false
waitinteger or boolean
One of:

Hold the request open for up to this many seconds (true = the maximum, 120) and, if the job finishes in time, return the results inline — the response gains a results array identical to what GET /job/{id}/download serves. If the job is still running when the wait elapses, the normal job object is returned with wait_timed_out: true; keep waiting with GET /job/{id}?wait=N or poll GET /job/{id} as usual. Accepts exactly one value (more returns "error": true); leave it off for batches.

[ 1 .. 120 ]
integer
fetch_seller_namesboolean

When true, seller detail pages are crawled for marketplace offer sellers whose names are not yet in the database. Seller names already cached in the database are always applied regardless of this flag.

Enabling this adds one additional request per unresolved seller, billed at the standard rate.

Default:false
curl -i -X POST \
  https://docs.kwery.co/_mock/api-reference/job \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "source": "idealo",
    "country": "de",
    "key": "gtin",
    "values": [
      "4006381333962",
      "4719512101148"
    ]
  }'

Responses

Job created. Always check the error field — validation failures also return HTTP 200.

Bodyapplication/json
One of:
errorboolean
Example:false
jobobject(Job)
resultsArray of objects(JobResult)

Present only when the request carried wait and the job settled in time. Same items as GET /job/{id}/download.

wait_timed_outboolean

Present only when the request carried wait and the job was still running when the wait elapsed. Keep waiting with GET /job/{id}?wait=N or poll.

Response
{
  "error": false,
  "job": {
    "_id": "64f1c2d3e4b5a6c7d8e9f0a1",
    "source": "idealo",
    "country": "de",
    "key": "gtin",
    "topic": "search",
    "values": [ … ],
    "max_pages": 1,
    "max_age": 1200,
    "timeout": 1440,
    "status": "new",
    "createdAt": "2026-04-03T10:00:00.000Z"
  }
}
© kwery. All rights reserved.