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

# Idempotency

> Retry a run safely without starting it twice or paying twice.

Send an `Idempotency-Key` header on every `POST /v1/runs`: a UUID you create for the intent and store with your task
before sending.

* Reuse the same key for every retry of the same intent, including after a restart.
* A replay returns the original run with `Idempotent-Replayed: true` and the original status code, never a second run
  or charge.
* While the first request is still being handled, a retry answers `409 IDEMPOTENCY_IN_PROGRESS` with `Retry-After`.
* Keys are scoped to the API key and remembered for 3 days.
* Use a new key only to start a new run on purpose.

If a create times out or the connection drops, retry with the same key: never switch keys until you know the first
request did not create a run. The MCP `run` tool sends a key for you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.