When you call the /v1/runs endpoint to start a task run, a small request can turn into a large bill. If your code retries the same request or a webhook fires twice, you might end up with two charges for the same work. Idempotency keys let you replay failed requests without incurring duplicate costs. This guide shows how to use idempotency keys with the computer use API and why they matter for production systems.
How idempotency works
The POST /v1/runs endpoint accepts an optional Idempotency-Key header. If the key is provided and the server has already processed a request with that key, it returns the existing result instead of starting a new run. This behavior applies only when the key is present on the exact original request. It does not retroactively protect requests that were made without an idempotency key. The server tracks keys per account, not per task run. If you retry the same request with the same key, you get the same task run ID and status. If you retry with a different key, the server starts a new run and bills you for it. You can also use the same key across multiple calls to the reserve-and-replay operations listed in our docs, which ensures safe replay without extra charges.
curl https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "m-abc123",
"task": "Open Chrome and navigate to example.com",
"cua_version": "v3",
"max_steps": 50,
"deadline_seconds": 600,
"on_awaiting_human": "pause"
}'Key behaviors you should know
- Idempotency-Key is an optional string header.
- The server uses the key to detect duplicate requests, not to deduplicate payloads.
- Replaying a failed request with the same key returns the original task run ID and status.
- Replaying with a different key creates a new run and incurs a new charge.
- Idempotency only protects the exact operations listed as reserve-and-replay in the docs.
- It does not prevent duplicate webhook deliveries; you must handle duplicate events on your side.
Always include an Idempotency-Key header when retrying a failed /v1/runs request to prevent double charges.
Where this beats brittle automation
Traditional automation often relies on brittle selectors or API-only workflows that can break without clear error handling. Even then, retries can unintentionally duplicate work. The computer use API lets you drive real desktops and browsers with vision-based actions, which are more robust to layout changes. By pairing that reliability with idempotency keys, you gain a safety net: if a request fails or a webhook fires twice, you can safely replay it without paying twice. This combination is essential for production systems where every dollar counts.
Next steps
Start using idempotency keys in your task runs to build resilient computer use agents. If you do not have a key yet, sign up at https://coasty.ai/developers to get started. The docs and keys page explain scope limits, billing, and all available endpoints.
Want to see this in action?
View Case Studies