Idempotency: deduplicate submissions with idempotencyKey

idempotencyKey is an optional string you set on a submission. Send the same key again and you get the task the first submission created; no new work is queued and no new credit hold is placed.

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "GEMINI", "idempotencyKey": "job-42:prompt-7:gemini", "payload": { "prompt": "best CRM for a small team", "country": "US" } }'

Without a key there is no deduplication: every submission creates a new task. Set a key on anything a cron job or a retrying worker might send twice.

Build the key from the unit of work, not the attempt. A key like "{jobId}:{promptId}:{engine}" comes out the same on every retry of that work.

How each endpoint treats a repeated key

Endpoint	Repeated key
`POST /v1/async/task`	`409 RESOURCE_ALREADY_EXISTS`. The task already exists.
`POST /v1/async/task/batch`	Success: `results[i]` carries the existing task.
`POST /v1/batches` (batch `idempotencyKey`)	`200` with the first batch, unchanged. A new batch returns `202`.
`POST /v1/batches` (item `idempotencyKey`)	Two items with one key in the same batch are rejected. An item key that matches an existing task resolves to that task.
`POST /v1/async/task/grid`	Points that exist return their tasks; only missing points are created.

The single-task endpoint keeps explicit-create semantics: you asked to create a task that already exists, so you get a conflict.

{
  "success": false,
  "error": {
    "code": "RESOURCE_ALREADY_EXISTS",
    "message": "Task already exists.",
    "timestamp": "2026-10-19T04:12:00.000Z"
  }
}

The 500-task batch absorbs duplicates as success, so a worker can resend a whole job after a restart without the batch failing on the items that already went in.

Location grids

The grid’s idempotencyKey becomes its id (a UUID is generated when you omit it). Each point’s task key is <grid id>:r<row>c<col>. Sending the same grid again under that id returns the existing points and admits only the missing ones. Sending a grid with a different center, size or radius under the same id fails the points whose coordinates differ with RESOURCE_ALREADY_EXISTS; use a new key for a new grid.

Scope and length

Keys are scoped to your account: another account can use the same string without colliding with yours.

Key	Length
`POST /v1/batches` batch `idempotencyKey`	1 to 256 characters
Grid `idempotencyKey`	1 to 200 characters, no leading or trailing spaces

UUID format is not required.

Matching results to submissions

Handle	Use
`results[].index`	Position in your `POST /v1/async/task/batch` array
`items[].customId`	Your own id on `POST /v1/batches` items
`task.idempotencyKey`	Echoed on polls and webhooks. Use it to match a webhook that arrives later, out of order.

If you did not send a key, idempotencyKey is omitted from the task object, not returned as null.

Key lifetime

A key stays reserved after the task completes or fails, and after the 24-hour polling window closes. A polling 404 does not release the key. Use the same key for transport retries of one submission, and a new key (for example with a :r1 suffix) for a separate run of the same work.

Get started

Core concepts

Answer engines

Search and web data

Request options

Research

GEO monitoring

Account and data

Idempotency: deduplicate submissions with idempotencyKey

How each endpoint treats a repeated key

Location grids

Scope and length

Matching results to submissions

Key lifetime

Next steps

Batches and grids

Errors

​How each endpoint treats a repeated key

​Location grids

​Scope and length

​Matching results to submissions

​Key lifetime

​Next steps

Batches and grids

Errors

How each endpoint treats a repeated key

Location grids

Scope and length

Matching results to submissions

Key lifetime

Next steps