Getting started

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/openapi. 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/openapi/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.

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.

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.