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

# Idempotency

> Retry run creation safely without creating duplicate work.

Run creation is asynchronous, so a client can lose the response after Infragrid has already accepted the work. Add `X-Idempotency-Key` to make retries recover the original run.

```http theme={null}
X-Idempotency-Key: customer-job-123-v1
```

## How keys are bound

Infragrid binds an idempotency record to:

* the workspace
* the API credential
* the route
* the normalized request body

A retry with the same key and equivalent body returns the stable original result. Reusing the key with a different body returns `409 Conflict`.

<Warning>
  A key is not global deduplication. The same string used by a different credential or route has a separate idempotency scope.
</Warning>

## Choose a key

Use a durable application identifier that represents one logical mutation.

| Pattern             | Example                   |
| ------------------- | ------------------------- |
| Business job        | `invoice-sync-inv_123-v2` |
| Scheduled execution | `daily-risk-2026-08-15`   |
| Queue message       | `message-01JABC...`       |
| Webhook delivery    | `provider-event-evt_123`  |

Keys must contain 1–255 printable ASCII characters without spaces. Do not include secrets or personal data.

## SDK behavior

<CodeGroup>
  ```typescript TypeScript theme={null}
  const run = await client.runs.create({
    task: "Summarize the account portal.",
    idempotencyKey: "account-portal-acct-123-v1"
  })
  ```

  ```python Python theme={null}
  run = client.runs.create(
      task="Summarize the account portal.",
      idempotency_key="account-portal-acct-123-v1",
  )
  ```
</CodeGroup>

The SDKs retry transient create failures only when an idempotency key is present. Without one, a create request is attempted once.

## Blueprint runs

The same behavior applies to `POST /v1/blueprints/{blueprint_id}/runs`. Include the pinned revision and inputs in your logical operation design so a changed payload cannot silently reuse an earlier run.

<Tip>
  Persist both your application job ID and the returned Infragrid run ID. The application ID protects creation; the run ID supports direct recovery and support diagnostics.
</Tip>


## Related topics

- [Errors and retries](/production/errors-retries.md)
- [API overview](/reference/overview.md)
- [Authentication](/authentication.md)
- [MCP server](/tools/mcp.md)
- [Limits](/production/limits.md)