> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Submit a task, receive a result — with webhooks or by polling.

## 1. Set your credentials

```bash theme={null}
export BASE="https://api.querying.ai"
export API_KEY="<your-key>"
```

## 2. Submit a task

Ask Gemini a question. `taskType` picks the engine; `payload.prompt` is what you ask.

```bash theme={null}
curl -X POST "$BASE/v1/async/task" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "GEMINI",
    "payload": { "prompt": "best wireless earbuds 2026", "country": "US" }
  }'
```

The task is accepted and queued:

```json theme={null}
{
  "success": true,
  "task": {
    "id": "8f2c1e40-...",
    "taskType": "GEMINI",
    "status": "QUEUED",
    "priority": 1,
    "createdAt": "2026-07-09T04:12:00.000Z"
  },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
}
```

<Note>
  `credits` exists only so Cloro clients that read it keep working. Nothing is billed. On
  submit and poll it is always zero; the webhook reports a nominal per-engine figure
  mirroring Cloro's pricing table.
</Note>

## 3. Collect the result

<Tabs>
  <Tab title="Webhook (recommended)">
    Add `webhook.url` when you submit. When the task reaches a terminal state we POST
    the full result there, and you never poll.

    ```bash theme={null}
    curl -X POST "$BASE/v1/async/task" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "taskType": "GEMINI",
        "payload": { "prompt": "best wireless earbuds 2026" },
        "webhook": { "url": "https://your-server.example.com/hook" }
      }'
    ```

    Your endpoint receives `{ task, credits, response }`. See [Webhooks](/concepts/webhooks)
    for the delivery and retry contract.
  </Tab>

  <Tab title="Polling">
    Omit `webhook` and poll the task by id. `response` is absent until the task is
    terminal.

    ```bash theme={null}
    curl "$BASE/v1/async/task/8f2c1e40-..." \
      -H "Authorization: Bearer $API_KEY"
    ```

    ```json theme={null}
    {
      "success": true,
      "task": { "id": "8f2c1e40-...", "status": "COMPLETED", "...": "..." },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
      "response": {
        "text": "The best wireless earbuds in 2026 are ...",
        "sources": [{ "position": 1, "url": "https://...", "label": "..." }],
        "timing": { "...": "..." }
      }
    }
    ```

    <Warning>
      Results are retained for a limited window and then swept. Poll within 24 hours or
      a completed task will 404 as expired.
    </Warning>
  </Tab>
</Tabs>

## 4. Submit in bulk

`POST /v1/async/task/batch` takes a JSON **array** of the same task objects, up to 500
per request. You may mix engines freely within one batch.

```bash theme={null}
curl -X POST "$BASE/v1/async/task/batch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "taskType": "GEMINI",     "payload": { "prompt": "best wireless earbuds 2026" } },
    { "taskType": "PERPLEXITY", "payload": { "prompt": "best wireless earbuds 2026" } },
    { "taskType": "GOOGLE",     "payload": { "query":  "best wireless earbuds 2026" } }
  ]'
```

Batch always returns `200` for a well-formed request. Individual failures surface as
`results[].success = false` so one bad task never sinks the rest — see
[Batch submission](/api-reference/create-task-batch).

<Note>
  Google-family engines (`GOOGLE`, `AIMODE`, `NAVER_*`) read `payload.query`. LLM engines
  read `payload.prompt`. Supplying either satisfies validation, but the engine only reads
  the one it expects.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Pick an engine" icon="cpu" href="/engines/overview">
    Every `taskType`, what it returns, and how fast you may push it.
  </Card>

  <Card title="Handle failures" icon="triangle-alert" href="/concepts/errors">
    Error codes, status codes, and what is retryable.
  </Card>
</CardGroup>