# Submit a batch job

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.

Endpoint: POST /job
Version: 4.0
Security: ApiKeyAuth, BearerAuth, BasicAuth

## Security:

  - `ApiKeyAuth` (unknown)
    apiKey in header x-api-key

  - `BearerAuth` (unknown)
    http bearer JWT

  - `BasicAuth` (unknown)
    http basic

## Request fields (application/json):

  - `source` (string, required)
    Enum: "idealo"

  - `country` (string, required)
    Supported Idealo countries.
    Enum: "de", "at", "uk", "gb", "fr", "it", "es"

  - `key` (string)
    | Value | Values format |
|  --- | --- |
| `term` | Free-text search query |
| `id` | Idealo product ID (numeric string) |
| `gtin` | EAN / GTIN-13 barcode |
| `pzn` | Pharmacy product number (DE only) |
    Enum: "term", "id", "gtin", "pzn"

  - `topic` (string)
    | Value | Meaning |
|  --- | --- |
| `search` | Standard price search — returns offers from all sellers (default) |
| `convert` | Resolve GTIN to Idealo product ID only; no price data returned |
| `remove_conversions` | Clear cached GTIN→ID mappings for the submitted GTINs |
    Enum: "search", "convert", "remove_conversions"

  - `values` (array, required)
    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_pages` (integer)
    Number of result pages to fetch per value. Applicable to Idealo and Amazon.
Ignored by Google and eBay.

  - `max_age` (integer)
    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.

  - `sort_by` (string)
    Sort order for offers within each result.

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

  - `callback_url` (string)
    Webhook URL to receive results when the job finishes.
For incremental push delivery, use the Stream endpoint instead.

  - `not_found_max_age` (integer)
    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.

  - `include_meta` (boolean)
    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](/guides/audit-and-provenance).

  - `wait` (any)
    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.

  - `fetch_seller_names` (boolean)
    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.

  - `country` (string)
    Amazon marketplace country code.
    Enum: "us", "ca", "mx", "br", "uk", "gb", "de", "at", "ch", "es", "fr", "it", "jp", "in", "ae", "au", "nl", "se", "pl", "be", "sg", "tr"

  - `key` (string)
    | Value | Values format |
|  --- | --- |
| `term` | Free-text search query |
| `asin` | Amazon ASIN — 10-character alphanumeric identifier |
| `gtin` | EAN / GTIN-13 — resolved to ASIN internally before fetching |
    Enum: "term", "asin", "gtin"

  - `topic` (string)
    | Value | Meaning |
|  --- | --- |
| `search` | Standard product search (default) |
| `search_and_offers` | Fetch all seller offers from the Amazon Offer Listing page (AOD) |
| `remove_conversions` | Clear cached GTIN→ASIN mappings for the submitted GTINs |
    Enum: "search", "search_and_offers", "remove_conversions"

  - `country` (string)
    Supported Google Shopping countries.
    Enum: "de", "at", "ch", "fr", "it", "es", "uk", "gb", "us", "au", "ca", "nl", "be", "pl", "se", "no", "dk"

  - `key` (string)
    | Value | Values format | Result shape |
|  --- | --- | --- |
| `term` | Free-text search | List of product cards (`GoogleTermContent`) |
| `id` | Google Shopping product ID | Full product page with seller offers (`GoogleProductContent`) |
| `product` | `GoogleProductValue` — pipe-separated record | Full product page with seller offers (`GoogleProductContent`) |
    Enum: "term", "id", "product"

  - `topic` (string)
    Only `search` is supported for Google Shopping.
    Enum: "search"

  - `values` (array)
    For `key: product`, each element must be a `GoogleProductValue` string.
For `key: term` or `key: id`, any plain string is valid — `GoogleProductValue`
is a `string` type so the schema remains compatible.

  - `country` (string)
    Supported eBay countries.
    Enum: "de", "at", "fr", "it", "es", "uk", "gb", "us", "au", "ca"

  - `key` (string)
    | Value | Values format |
|  --- | --- |
| `term` | Free-text search query |
| `id` | eBay item ID (numeric string) |
| `gtin` | EAN / GTIN-13 barcode |
    Enum: "term", "id", "gtin"

  - `topic` (string)
    | Value | Meaning |
|  --- | --- |
| `search` | Standard listing search (default) |
| `remove_conversions` | Clear cached GTIN mappings for the submitted GTINs |
    Enum: "search", "remove_conversions"

## Request examples:

  - `Idealo — GTIN lookup` (unknown)

  - `Amazon — ASIN with all seller offers` (unknown)

  - `Google Shopping — keyword search` (unknown)

  - `Google Shopping — product record lookup` (unknown)

  - `eBay — GTIN search` (unknown)

  - `Kaufland — GTIN search with seller offers (Czech market)` (unknown)

  - `Guenstiger — keyword search with offers` (unknown)

## Response 200:

  - `200` (unknown)
    Job created. **Always check the `error` field** — validation failures
also return HTTP 200.

## Response 200 fields (application/json):

  - `error` (boolean)
    Example: false

  - `job` (object)

  - `job._id` (string)
    MongoDB ObjectId.

  - `job.source` (string)
    Enum: "idealo", "amazon", "google", "ebay", "kaufland", "otto", "billiger", "guenstiger", "walmart", "lidl", "aliexpress", "rakuten"

  - `job.country` (string)
    Example: de

  - `job.key` (string)
    Example: gtin

  - `job.topic` (string)
    Example: search

  - `job.values` (array)

  - `job.max_pages` (integer)

  - `job.max_age` (integer)

  - `job.timeout` (integer)
    Timeout in minutes.

  - `job.status` (string)
    | Value | Meaning |
|  --- | --- |
| `new` | Created, queued for processing |
| `working` | Crawls in progress |
| `finished` | All results assembled |
| `failed` | Timed out or unrecoverable error |
    Enum: "new", "working", "finished", "failed"

  - `job.createdAt` (string)

  - `job.updatedAt` (string)

  - `results` (array)
    Present only when the request carried `wait` and the job settled in
time. Same items as `GET /job/{id}/download`.

  - `results.key` (string)
    The input value this result corresponds to.
    Example: 4006381333962

  - `results.success` (boolean)

  - `results.reason` (string)
    Enum: "not found", "source currently unavailable", "timeout", "parameter_invalid", null

  - `results.content` (any)
    Source-specific result payload. `null` when `success` is `false`.
The shape depends on `source` and `key`:
- Idealo → `IdealoContent`
- Amazon → `AmazonContent`
- Google `term` → `GoogleTermContent`
- Google `id` / `product` → `GoogleProductContent`
- eBay → `EbayContent`

  - `results.content.id` (string)
    Idealo product ID.
    Example: 205062515

  - `results.content.name` (string)
    Example: Festool Bit PZ1 -25/10

  - `results.content.url` (string)

  - `results.content.category_ids` (array)
    Primary category id(s) for the product.
    Example: ["3308"]

  - `results.content.rating` (number)
    Keyword `search` results only.
    Example: 4.7

  - `results.content.rating_count` (integer)
    Keyword `search` results only.
    Example: 150

  - `results.content.categories` (array)
    Category name(s). Product results: German markets (`de`/`at`) only.
    Example: ["Tintenstrahldrucker"]

  - `results.content.available_since` (string)
    Date the product appeared on Idealo. Keyword `search` results only.
    Example: 2023-05-12

  - `results.content.price_min` (number)
    Example: 4.9

  - `results.content.price_max` (number)
    Example: 19.85

  - `results.content.price_avg` (number)
    Example: 12.34

  - `results.content.offers_count` (integer)
    Example: 5

  - `results.content.offers` (array)

  - `results.content.offers.position` (integer)
    Example: 1

  - `results.content.offers.price` (number)
    Example: 4.9

  - `results.content.offers.currency` (string)
    Example: EUR

  - `results.content.offers.shipping` (number)
    Example: 5.95

  - `results.content.offers.total` (number)
    Price + shipping.
    Example: 10.85

  - `results.content.offers.seller_name` (string)
    Example: mima.de

  - `results.content.offers.seller_url` (string)

  - `results.content.offers.seller_type` (string)
    Enum: "standalone-shop", "marketplace-shop"

  - `results.content.offers.marketplace_name` (string)
    Populated when `seller_type` is `marketplace-shop`.
    Example: Amazon

  - `results.content.offers.seller_rating` (number)

  - `results.content.offers.seller_rating_count` (integer)

  - `results.content.offers.voucher` (boolean)

  - `results.content.offers.free_return` (boolean)

  - `results.content.offers.availability_code` (string)
    `green` = in stock, `orange` = limited, `red` = out of stock.
    Enum: "green", "orange", "red"

  - `results.content.offers.availability_text` (string)
    Example: sofort lieferbar, 1 - 3 Werktage

  - `results.content.product_id` (string)
    The ASIN (unified schema — `product_id` on every source).
    Example: B0847ZTV5Q

  - `results.content.brand_name` (string)

  - `results.content.category` (string)

  - `results.content.buybox` (object)
    Buy-box snapshot — the same object shape on Amazon, Walmart, and Kaufland (unified schema).

  - `results.content.buybox.price` (number)
    Buy-box price. On a Prime-exclusive deal this is the regular (non-Prime) price; the Prime price is in `prime_price`.
    Example: 27.99

  - `results.content.buybox.seller_name` (string)
    Seller currently winning the buy box.
    Example: Amazon.de

  - `results.content.buybox.seller_id` (string)
    Example: A3JWKAKR8XB7XF

  - `results.content.seller_type` (string)
    Fulfilment of the buy-box seller.
    Enum: "amazon", "fba", "fbm"

  - `results.content.is_prime` (boolean)
    True when the buy box carries a Prime-exclusive price.

  - `results.content.prime_price` (number)
    The Prime-exclusive price when `is_prime` is true, else null.

  - `results.content.offers` (array)
    Populated when `topic` is `search_and_offers`.

  - `results.content.offers.seller_id` (string)

  - `results.content.offers.is_prime` (boolean)

  - `results.content.offers.condition` (string)
    Example: New

  - `results.content.offers_count` (integer)
    Number of product cards returned.

  - `results.content.id` (string)
    Google Shopping product ID.
    Example: 7294553093490218809

  - `results.content.description` (string)

  - `results.content.url` (string)
    Canonical Google Shopping product URL.

  - `results.content.rating` (number)

  - `results.content.rating_count` (integer)

  - `results.served_from` (string)
    `live` — at least one fetch was made for this job. `cache` — the
result was re-served from a cached observation without a fetch.
    Enum: "live", "cache"

  - `results.observed_at` (string)
    When the data was observed (UTC): the last fetch for `live`, the
cached observation's date for `cache`. `null` when nothing was
observed (failed lookup) or the cache date is unknown.
    Example: 2026-09-08T10:00:00.000Z

  - `results.trust` (object)
    Confidence score attached to every result. `score` is a weighted average
(0–1) of the five `components`. See the
[Trust](/guides/trust) guide for interpretation.

  - `results.trust.score` (number)
    Overall confidence, 0 (do not trust) to 1 (fully trusted).
    Example: 0.81

  - `results.trust.components` (object)
    The five sub-scores that make up `score`, each 0–1.

  - `results.trust.components.identity` (number)
    Is this the requested product? (weight 0.25)
    Example: 1

  - `results.trust.components.completeness` (number)
    Are the expected fields populated? (weight 0.20)
    Example: 0.85

  - `results.trust.components.price_integrity` (number)
    Pricing consistent and outlier-free? (weight 0.25)
    Example: 0.7

  - `results.trust.components.offer_contamination` (number)
    Fraction of offers that are clean. (weight 0.15)
    Example: 0.9

  - `results.trust.components.freshness` (number)
    Recency of the data; decays with age. (weight 0.15)
    Example: 0.55

  - `results.trust.flagged_offers` (array)
    Indices into `content.offers` of offers flagged as price outliers.
    Example: [2,5]

  - `results.meta` (object)
    Provenance metadata. Present only when the job was submitted with
`include_meta: true`.

  - `results.meta.crawls` (array)
    One entry per fetch that contributed to this result.

  - `results.meta.crawls.crawl_id` (string)
    Stable ID for this individual fetch — quote it to support.
    Example: 9f1c2d3e4b5a6c7d8e9f0a1b

  - `results.meta.crawls.url` (string)
    The exact URL that was fetched.

  - `results.meta.crawls.http_status` (integer)
    Example: 200

  - `results.meta.crawls.duration_ms` (integer)
    Fetch round-trip time, in milliseconds.
    Example: 2341

  - `results.meta.crawls.observed_at` (string)
    When the data was observed (UTC).

  - `results.meta.crawls.geo` (string)
    Country the request was made from.
    Example: de

  - `results.meta.crawls.job_type` (string)
    Internal crawl step that produced this fetch.
    Example: idealo.search

  - `results.meta.partial` (boolean)
    Google only. `true` when the marketplace reports more sellers than
were gathered in this snapshot. Absent for other sources.

  - `wait_timed_out` (boolean)
    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.

  - `message` (string)
    Example: country not supported by source

## Response 401:

  - `401` (unknown)
    Missing or invalid credentials.

## Response 401 fields (application/json):

  - `error` (string)
    Example: user not found

  - `message` (string)

## Response 403:

  - `403` (unknown)
    Authenticated but not subscribed to this source/country.

## Response 403 fields (application/json):

  - `error` (string)
    Example: user not found

  - `message` (string)

## Response 200 examples:

  - `success` (unknown)

  - `validation_error` (unknown)

  - ``wait` settled — results inline` (unknown)
    Mock server: send `x-redocly-response-body-example: wait` to get this
shape instead of the default job object.

  - ``wait` elapsed — job still running` (unknown)