Submit jobs to https://api.kwery.co/job and pass your organization API key in the Authorization header as Bearer YOUR_API_KEY. Keep the key on your server, never expose it in browser code or a public repository. Keys can be rotated and separated by environment so staging and production do not share credentials. API documentation.
No inbound access is required to submit or poll jobs; your system only needs outbound HTTPS access to api.kwery.co. If you use webhooks, your callback URL must be publicly reachable over HTTPS so kwery can deliver results. Verify every callback signature rather than relying only on source IP addresses.
Yes. The Try It console in the dashboard lets you enter a GTIN, choose a source, run a real lookup, and inspect the JSON response without setting up Postman or an application first. New accounts receive 1.000 one-time credits and do not need a credit card to test. Get API Key.
Verify the signature supplied with every webhook before processing its JSON body. kwery signs payloads with HMAC-SHA256 using the webhook secret returned for the job or configured for the endpoint. Compute the signature from the unmodified request body and compare it securely; reject callbacks that do not match. Webhook delivery.
Treat the key as compromised. Generate a replacement in Developer → API Keys, update your integration, confirm requests work with the new key, and revoke the exposed key immediately. Do not post the key in support messages, logs, screenshots, or issue trackers.
Short identifiers: amazon, google, ebay, idealo, kaufland, otto, billiger, guenstiger, lidl, walmart, rakuten, aliexpress. Display names such as google_shopping return "unknown source". Source identifiers in the docs.
1.000 for batch jobs, 100.000 for stream jobs, with stream results polled in pages of up to 1.000 (default 100). Errors and limits.
There's no fixed per-account request-rate limit — we don't throttle you by request volume. What can stop a burst is credits: if you use up your plan credits, or hit an optional daily credit cap you've set yourself, submissions come back with a clear error code telling you which limit you hit. For very large or sustained workloads, talk to us first so we can size capacity for you. Errors and limits.
Each resource has a semantic version. Additive changes ship without a bump; renames and removals ship as a new major version pinned via header. Old clients keep working; upgrading is opt-in.
Node / TypeScript is the primary SDK. Python is in beta. Any HTTP client works against the REST endpoints directly, the docs include cURL examples for every route. API documentation.
Lookups run as jobs. You submit a batch of identifiers, kwery resolves each one against the live marketplace, and results stream back as batches complete rather than blocking a single long request. Small jobs finish quickly; large jobs deliver progressively. For a single lookup, wait returns the result in the same response (up to 120 s). If it takes longer, you get a job ID to poll instead. Batches always run as jobs.
Provide a callback_url when you submit a job and results are delivered to it as JSON. Webhooks are signed so you can verify authenticity, retried automatically on failure, and replayable on demand if your endpoint was down. Webhook delivery.
Retry two things: a 503 response, after the interval in its Retry-After header, and any value whose result reason is "source currently unavailable", by re-submitting it in a later job rather than instantly. Do not retry validation errors, 401, 403 or 402, they will keep failing until something changes on your side. Use exponential backoff with a finite attempt count for network-level failures. Robustness guide.
Yes, with two per-job parameters. max_age (seconds, default 1200) sets how old a cached observation may be before kwery fetches again; set it to 0 to force a live fetch every time. not_found_max_age (days, default 10) sets how long a cached "not found" is honoured before the next check re-crawls. Anything answered from cache is free, so widening the windows lowers your credit consumption. Data quality details.
Every account starts with a one-time grant of 1.000 free credits and no credit card. You can run real calls from your own code or from the try-it console in the dashboard before committing to a plan. Get API Key.
kwery separates two kinds. Validation problems come back with HTTP 200 and an "error": true body carrying a message, so always check that field before consuming a response, it is the most common integration bug. Infrastructure problems use standard status codes: 401 for missing or invalid credentials, 402 when you are out of credits, 403 when you are authenticated but not allowed, and 503 when the API is under load. Errors and limits.
Outcomes are per value, not per job. A job of 1.000 values can contain found products, not-founds, and transient failures side by side. Each result carries success, a reason when relevant (for example "not found" or "source currently unavailable"), served_from (live or cache) and observed_at, so process results per value instead of treating a finished job as all good or one bad value as a failed batch.
72 hours. Download or consume the results within that window; after it, the job's results are no longer retrievable and the lookup has to be run again.
Request API access and the team will walk through sources, volumes, and integration in detail.