Quickstart

This guide walks you through your first end-to-end request: submit a batch job, poll until it finishes, and download the results.

Every endpoint in this documentation can be exercised against a built-in mock server before you sign up: https://docs.kwery.co/_mock/api-reference. It returns correctly-shaped example responses — no API key (any dummy Authorization header passes) and no credits consumed:

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

The data is static example data, not a live crawl, but the shapes match production exactly — build and test your integration end-to-end, then swap the base URL for https://api.kwery.co and a real key. In the API Reference, pick Mock server in the Servers panel and all code samples switch to it.

Sign up at kwery.co. Your organization is created with a free credit allowance, and the dashboard issues an API key — kwy_live_… — that authenticates every data request. Manage keys (create, rotate, revoke) any time in the dashboard.

Send the key as a Bearer token (Authorization: Bearer kwy_live_…) or the x-api-key header. The examples below use $KWERY_API_KEY. See Authentication for details, including the legacy username/password option for accounts provisioned before self-serve.

Each source supports a fixed set of key types. The key determines what goes in values. source is the short identifier in the first column, exactly as written — google, not google_shopping; anything else returns unknown source.

Google has no bare gtin key: use product and send the GTIN with the title (see Google Shopping).

Access is granted per source.country pair. If your account is not enabled for the combination you request, the API responds with { "error": true, "message": "not subscribed to source" }. See the per-source pages under Sources for the exact fields each marketplace returns.

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", "4719512101148"]
  }'

The response returns immediately with a job object — results are assembled asynchronously:

{
  "error": false,
  "job": {
    "_id": "64f1c2d3e4b5a6c7d8e9f0a1",
    "source": "idealo",
    "country": "de",
    "key": "gtin",
    "topic": "search",
    "values": ["4006381333962", "4719512101148"],
    "status": "new",
    "createdAt": "2026-04-03T10:00:00.000Z"
  }
}

Always check error first — validation failures are returned with HTTP 200 and "error": true. See Errors & limits.

Testing one value? Add "wait": true and the API holds the request open (up to 120 s) and returns the results inline — one call, one response, no polling. wait accepts exactly one value; larger submissions return "error": true:

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 response carries a results array in exactly the shape step 5 describes. If the lookup is still running when the wait elapses, you get the job object back with wait_timed_out: true — keep waiting with GET /job/{id}?wait=60 (same inline results when it finishes) or continue with step 4. Use wait for one-off checks; submit batches without it. Building an AI agent on this? See Agent tool call.

curl -s https://api.kwery.co/job/64f1c2d3e4b5a6c7d8e9f0a1 \
  -H "Authorization: Bearer $KWERY_API_KEY"

Poll until status is finished.

curl -s https://api.kwery.co/job/64f1c2d3e4b5a6c7d8e9f0a1/download \
  -H "Authorization: Bearer $KWERY_API_KEY"

Each entry carries key, success, an optional reason, and the parsed content for that value. Results are retained for 72 hours. Add .csv to the download path for a CSV export.

• Batch (this guide) — up to 1 000 values, poll then download. Simple, great for ad-hoc lookups.
• Stream — up to 100 000 values, results pushed to your endpoint via signed webhooks as they complete. See Webhooks.

• Authentication — credentials and the subscription model.
• Sources — per-marketplace fields and supported keys.
• Code samples — Node.js and Python versions of every call here.