Send up to 500 tasks in one request

The batch endpoint queues up to 500 tasks across any mix of engines in a single call and reports the result for each one.

What you get

• POST /v1/async/task/batch takes an array of up to 500 tasks, each in the same shape as a single task.
• Engines mix freely, so one call sends a prompt set to ChatGPT, Gemini and Perplexity together.
• results[] reports every item on its own: the task it created, or the reason that item was refused.
• idempotencyKey works per item, so a retried batch returns the tasks it already created.

How it works

A well-formed batch always answers 200. Each item is checked on its own, so a malformed prompt shows up in its own results[] entry while the rest of the batch is queued. Every created task then runs, completes and is billed exactly like a single task, and each one sends its own webhook.

Batching turns thousands of HTTP calls into a handful, which keeps scheduled jobs fast and easy to reason about.

Where it helps

• Run a full prompt set across several engines every morning with one call.
• Load a large keyword list in a few requests and let the queue work through it.

Send a request

Send up to 500 tasks as one JSON array, each in the same shape as a single task. Engines and countries mix freely within one batch.

curl -X POST https://api.querying.ai/v1/async/task/batch \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "CHATGPT",
      "payload": { "prompt": "best CRM for startups", "country": "US" }
    },
    {
      "taskType": "GEMINI",
      "payload": { "prompt": "best CRM for startups", "country": "US" }
    },
    {
      "taskType": "PERPLEXITY",
      "payload": { "prompt": "best CRM for startups", "country": "US" }
    }
  ]'

Response

The call answers 200 with one entry per task, in the order you sent them. Task IDs are shortened here.

{
  "success": true,
  "summary": { "total": 3, "succeeded": 3, "failed": 0 },
  "results": [
    {
      "success": true,
      "index": 0,
      "task": {
        "id": "…",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…"
      },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
    },
    {
      "success": true,
      "index": 1,
      "task": {
        "id": "…",
        "taskType": "GEMINI",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…"
      },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
    },
    {
      "success": true,
      "index": 2,
      "task": {
        "id": "…",
        "taskType": "PERPLEXITY",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…"
      },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
    }
  ]
}

summaryobject

Counts for the batch: total, succeeded and failed.

resultsarray

One entry per task, in the order you sent them: index, success and the queued task, or error with its code.

Receive the result

The request returns the task right away with status QUEUED. Poll GET /v1/async/task/{id} until status is COMPLETED or FAILED, or add webhook.url and the finished task arrives at your server with the same task, credits and response. Results stay available for 24 hours after a task finishes.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Errors

The whole batch answers 400 VALIDATION_ERROR when the body is an empty array or holds more than 500 items, and 413 above 8 MiB. Inside a batch that fits, an item over your plan’s concurrency or the engine’s queue limit comes back with success set to false and its code in error.code, and the other items are queued. Send those items again after a short wait.

PLAN_CONCURRENCY_LIMITHTTP 429

Your queued and running tasks reached the plan’s limit: 2 on the free plan, 10 on Basic, 25 on Pro, 50 on Scale and 100 on Max. Send again after Retry-After seconds.

QUEUE_BACKPRESSUREHTTP 429

The engine’s queue is full for the moment. Send again after Retry-After seconds.

VALIDATION_ERRORHTTP 400

A field is missing or out of range. details names the field.

PAYLOAD_TOO_LARGEHTTP 413

The body is over 1 MiB, or over 8 MiB for a batch.

Pricing

A batch costs the sum of its tasks at each engine’s price, and each task is charged when it completes.