Network retries and transient failures can cause the same task to be submitted multiple times. If you are not guarding against it, your prepaid wallet drains with every retry. Idempotency-Key gives you replay safety for the exact operations where duplicates are a risk, such as creating a task run. This guide shows the real fields and how to use them so you never pay twice.
How it works
When you POST to /v1/runs, include an Idempotency-Key header. The server checks for an existing run with the same key. If it exists and its state is still one that allows replay (like queued or running), it returns that run instead of creating a new one. The response body is identical to a fresh create. You can safely retry the request without incurring another $0.05 charge per step. The key must be unique per logical operation, not globally unique per key. Use a stable identifier such as a request ID or a hash of the task payload. This applies to any of the 18 documented reserve-and-replay operations that support idempotency.
curl -X POST https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Idempotency-Key: run-$(date +%s)-$(uuidgen | tr -d -)" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "vm-123",
"task": "install python3.13 && pip install requests",
"cua_version": "v4",
"max_steps": 50,
"deadline_seconds": 600
}'When the key already exists
- The same key returns the existing run with status one of queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
- You can still inspect the run with GET /v1/runs/{id} or stream events with GET /v1/runs/{id}/events.
- If you cancelled the run, the key no longer matches an active run. A new request with the same key will create a fresh run.
- Idempotency does not prevent changing the task or other mutable fields on a new request.
Include Idempotency-Key on every POST /v1/runs request you make from your client library. Treat it as a replay guard, not a deduplication filter across unrelated operations.
Where this beats brittle automation
Traditional automation relies on brittle selectors and static APIs that either fail silently or require fragile workarounds when a UI changes. A computer use agent sees the screen and acts like a human, adapting to layout shifts, new controls, and dynamic content. This flexibility reduces the chance of task logic breaking but also means your client can accidentally submit the same intent multiple times. Idempotency-Key gives you a reliable safety net so you can trust retries and retries without fear of double charges. Combine this with the stateful trajectory memory from session-based predict calls to build workflows that recover gracefully from failures while staying on budget.
Network reliability should not come at the cost of your wallet. Use Idempotency-Key on POST /v1/runs to replay the same task safely. Build production-grade computer use agents that run once and pay once. Get your API key at https://coasty.ai/developers to start building.
Want to see this in action?
View Case Studies