Skip to main content
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.