Idempotency key

A client-supplied identifier attached to a request so that submitting it again, after a timeout, a retry, or a cron job firing twice, resolves to the original result instead of creating a duplicate capture or double-billing. It is the mechanism that makes a scheduled, unattended capture pipeline safe to retry blindly.

In AI Search API

Pass idempotencyKey on any POST /v1/search (or batch item) and a retried submission with the same key returns the original job rather than starting a second one. This matters most for scheduled monitoring workflows, where a cron-driven daily sweep must produce exactly one record per (prompt, surface, region, day) even if the trigger fires twice, a duplicate record would corrupt a stored dataset as badly as a missing one. Scheduled visibility-monitoring and share-of-voice pipelines use the same mechanism for the same reason: a retried request must never silently double the size of a stored dataset.

POST /v1/search, an idempotent scheduled submit

{
  "query": "best crm for startups",
  "surfaces": ["chatgpt"],
  "regions": [{ "country": "US" }],
  "idempotencyKey": "daily-2026-07-01-q17"
}

Related terms

See it in the product

Every definition here is enforced in the Envelope contract. Run a capture and read the fields yourself.

Start with 500 free credits All terms