An AI agent that reasons about prices needs a tool that answers one question quickly: what does this product cost on that marketplace right now? kwery answers it with the same POST /job request every other integration uses, plus one flag, wait, that turns the asynchronous job into a single request-response.
This guide shows the tool definition for a merchant or shopping agent built on frameworks such as Anthropic's Claude Commerce Agents blueprint. Nothing here is agent-specific on the API side.
One identifier in, one scored result out, inside one HTTP request.
| Tool parameter | Maps to | Notes |
|---|---|---|
source | Marketplace to check | idealo, amazon, google, … see Sources |
country | Marketplace region | per-source list on each source page |
key | Identifier type | gtin is simplest when the catalogue carries EAN/GTIN codes |
values | The identifier | exactly one value with wait; more than one returns "error": true, "message": "too many values" |
wait | Hold the request open | true = the maximum (120 s), or a number of seconds |
curl -s https://api.kwery.co/job \
-H "Authorization: Bearer $KWERY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"source":"idealo","country":"de","key":"gtin","values":["4006381333962"],"wait":true}'The API key is sent as a Bearer token or in x-api-key, see Authentication.
If the lookup finishes inside the wait window, the response is the job object plus a results array, identical to what GET /job/{id}/download serves. Each result carries success, the parsed content for that value, and the trust score: trust.score with its components identity, completeness, price_integrity, offer_contamination, freshness, and flagged_offers.
Feed the price and the trust score into the agent's decision step together. A low identity or price_integrity component is the signal to route the recommendation to a human rather than act on it, which maps onto the approval gate most agent harnesses already have for pricing changes.
If the marketplace is slow and the wait elapses first, the response is the job object with wait_timed_out: true. Nothing is lost: keep waiting on the same job with GET /job/{id}?wait=60, which returns results inline as soon as the job finishes, or poll GET /job/{id} and download as described in Getting started.
A wait answer is synchronous, not instant. A live lookup is one to three requests to the marketplace through a proxy, roughly 5–15 seconds on idealo and Amazon and longer on Google. Results served from kwery's cache return immediately. Design the tool's timeout for the 120 s maximum, and treat wait_timed_out as "continue waiting", not as an error.
Validation problems come back as HTTP 200 with "error": true and a message, for example an unsupported source/country pair or a malformed identifier. Check error before reading anything else. 401 means the key is wrong, 402 means the organisation is out of credits. Details in Errors & limits.
The mock server does not run wait: by default it returns the asynchronous job object. Ask it for the settled shape instead by naming the example:
curl -s -X POST https://docs.kwery.co/_mock/api-reference/job \
-H "Authorization: Bearer test123" \
-H "x-redocly-response-body-example: wait" \
-H "Content-Type: application/json" \
-d '{"source":"idealo","country":"de","key":"gtin","values":["4006381333962"],"wait":true}'This returns the job plus an inline results array with a scored result, the same shape the live API returns when the lookup settles. Use wait_timed_out as the example name to see the other branch. The download mock (GET /_mock/api-reference/job/{id}/download) returns the same result items. Swap the base URL and the key when going live.
wait is for one identifier in the middle of a conversation. When the agent needs a whole catalogue priced, submit without wait:
- Batch API: up to 1 000 values per job, poll, then download. See Getting started.
- Stream API: up to 100 000 values per job, results pushed to your endpoint as signed webhooks while they complete. See Webhooks.
Credits are the same either way, see Pricing.
See the AI Shopping Agent use case → Integrating with Claude specifically? See the integration guide →