When an agent drives a real desktop through the computer use API, each step costs money. A network error, a retry, or a power cycle can cause the same step to be processed twice. Idempotency keys solve this by marking a specific request as already handled only when they appear on the original request. This prevents you from paying for the same agent step twice.
How it works
The idempotency-key header is an optional, string-valued field that you send on reserve-and-replay operations. When the server receives a request with an idempotency-key that has been used before for the same operation type and payload, it returns the cached result instead of running the operation again. This applies only to the 18 documented reserve-and-replay operations, such as creating a machine, starting a workflow, or resuming a run. On the original request, the server accepts the key and starts the operation. On a retry with the same key, it detects the existing state and returns the previously stored response without charging again. The key is stored for a limited duration on the server to prevent accidental reuse, and each key is tied to the scope of the key you use for the request. If you try to reuse a key for a different operation or a different resource, the server rejects it with a 400 error.
curl -X POST https://coasty.ai/v1/runs \
-H "Content-Type: application/json" \
-H "X-API-Key: ${COASTY_API_KEY}" \
-H "Idempotency-Key: run-123-resume" \
-d '{
"machine_id": "m-abc123",
"task": "Open Chrome and navigate to cozy.ai",
"cua_version": "v3",
"max_steps": 20
}'When idempotency keys prevent double charges
- You send a resume request for a run that is already running. The server returns cached state and does not bill again.
- You retry a POST /v1/machines request due to a network glitch. The server reuses the existing machine instead of creating a new one.
- You replay a workflow step after a timeout. The server returns the step outcome without charging for the operation again.
Include Idempotency-Key on the original reserve-and-replay request to prevent double billing on retries.
Where this beats brittle automation
Traditional automation relies on fragile selectors and fixed API endpoints. When a UI changes, selectors break and you must manually update them. The computer use API lets the agent see the screen and act like a human, which means it adapts to layout changes without requiring you to update selectors. Idempotency keys add a layer of billing safety so you can rely on the agent’s adaptability without worrying about accidental retries. This makes it easier to build production-grade computer use agents that drive real desktops, browsers, and terminals reliably and predictably.
Start building reliable computer use agents with idempotency keys to guarantee single-agent-step billing. Get your API key at https://coasty.ai/developers and try the computer use API today.
Want to see this in action?
View Case Studies