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

# idempotency_token

> The provider idempotency token for the attempt this executor is running (SPEC-v0.7 §4).

`ctrlrun.idempotency_token` — function, defined at `src/ctrlrun/control.py:204`

```python theme={null}
from ctrlrun import idempotency_token
```

```python theme={null}
def idempotency_token() -> str
```

The provider idempotency token for the attempt this executor is running (SPEC-v0.7 §4).

Send it to the provider as its idempotency key. It is
`ctrlrun.effect.idempotency_token_for(effect_key, attempt)` for the attempt that holds the
reservation, so it is stable across a `Control.resume` of the same attempt and **different
after a renewal**: a token stable across v0.1 §5.4's renewal would have the provider answer
the one retry the kernel permits with the cached failure of the attempt that failed (§4.1).

What it is for is reconciliation: a deterministic handle to ask the provider what became of
an attempt whose outcome is unknown, by a key the provider already indexes (§4.7). It does
not make a retry safe, and after an `AMBIGUOUS` outcome the kernel still refuses one.

Nothing is stored: the token is a pure function of two fields every receipt of an attempt
that ran already carries, so a receipt re-derives it with `idempotency_token_for` and a
`reconcile` hook reads the attempt off the record (§4.5).

**Outside an executor this raises `InvalidArgument`**, because a token invented outside an
attempt identifies nothing. So does an executor whose action has no effect key, an
observe-mode attempt whose reservation was refused, and a thread the executor started
without copying its context: a missing value is refused rather than guessed (§4.3).

## Next

* [Python API index](/docs/reference/api/index).
* [Get started](/docs/get-started/quickstart) · [Why](/docs/why).


## Related topics

- [OWASP Top 10 for Agentic Applications](/docs/OWASP-AGENTIC-TOP10.md)
- [Python API](/docs/reference/api/index.md)
- [Roadmap](/docs/ROADMAP.md)
- [CTRLRun and idempotency keys](/docs/compare/idempotency-keys.md)
- [Frequently asked questions](/docs/faq.md)