Quickstart

1. Set your credentials

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.

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:

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

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.

3. Collect the result

Webhook (recommended)
Polling

Add webhook.url when you submit. When the task reaches a terminal state we POST the full result there, and you never poll.

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 for the delivery and retry contract.

Omit webhook and poll the task by id. response is absent until the task is terminal.

curl "$BASE/v1/async/task/8f2c1e40-..." \
  -H "Authorization: Bearer $API_KEY"

{
  "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": { "...": "..." }
  }
}

Results are retained for a limited window and then swept. Poll within 24 hours or a completed task will 404 as expired.

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.

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.

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.

Next steps

Pick an engine

Every taskType, what it returns, and how fast you may push it.

Handle failures

Error codes, status codes, and what is retryable.

Get started

Core concepts

Engines

Migrating

1. Set your credentials

2. Submit a task

3. Collect the result

4. Submit in bulk

Next steps

Pick an engine

Handle failures

​1. Set your credentials

​2. Submit a task

​3. Collect the result

​4. Submit in bulk

​Next steps

Pick an engine

Handle failures

1. Set your credentials

2. Submit a task

3. Collect the result

4. Submit in bulk

Next steps