# 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.

## 1. Get an API key

Sign up at [kwery.co](https://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](/guides/authentication) for details,
including the legacy username/password option for accounts provisioned before self-serve.

## 2. Pick a source, key, and country

Each **source** supports a fixed set of **key** types. The `key` determines what goes in
`values`.

| Source | Key | Values format | Example countries |
|  --- | --- | --- | --- |
| `idealo` | `term` | Free-text search | de at uk fr it es |
| `idealo` | `id` | Idealo product ID (numeric) | de at uk fr it es |
| `idealo` | `gtin` | EAN / GTIN-13 | de at uk fr it es |
| `idealo` | `pzn` | Pharmacy product number | de |
| `amazon` | `term` | Free-text search | de at ch fr it es uk us … |
| `amazon` | `asin` | Amazon ASIN (10 chars) | de at ch fr it es uk us … |
| `amazon` | `gtin` | EAN / GTIN-13 | de at ch fr it es uk us … |
| `google` | `term` | Free-text search | de at ch fr it es uk us nl be … |
| `google` | `id` | Google Shopping product ID | de at ch fr it es uk us nl be … |
| `google` | `product` | Pipe-separated product record | de at ch fr it es uk us nl be … |
| `ebay` | `term` | Free-text search | de at fr it es uk us au ca |
| `ebay` | `id` | eBay item ID (numeric) | de at fr it es uk us au ca |
| `ebay` | `gtin` | EAN / GTIN-13 | de at fr it es uk us au ca |


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](/sources) for the exact
fields each marketplace returns.

## 3. Submit a batch job

```bash
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:

```json
{
  "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](/guides/errors-and-limits).


## 4. Poll until finished

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

Poll until `status` is `finished`.

## 5. Download the results

```bash
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 vs Stream

- **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](/guides/webhooks).


## Next steps

- [Authentication](/guides/authentication) — credentials and the subscription model.
- [Sources](/sources) — per-marketplace fields and supported keys.
- [Code samples](/guides/code-samples) — Node.js and Python versions of every call here.