How to Use Idempotency Keys in the Computer Use API to Never Double-Charge
When you spin up a cloud machine and fire off a computer use agent to complete a task, every step costs money. A task run with POST /v1/runs bills $0.05 per agent step. A stateful session with POST /v1/sessions costs $0.10 per predict call. A new machine provisioning request with POST /v1/machines incurs usage too. Accidentally retrying the same request without safeguards can lead to duplicate charges. Idempotency keys fix this by allowing you to replay a request safely without creating a second billing event.
Idempotency keys are for reserve-and-replay operations
- ●Idempotency-Key only applies to the 18 documented reserve-and-replay operations.
- ●You must provide Idempotency-Key on the original request.
- ●You cannot add Idempotency-Key retroactively to an already processed request.
- ●If the request already succeeded, the server returns the stored response on replay.
- ●If the request failed, you can retry with the same key to get the same outcome.
- ●It does not affect operations outside this set (e.g., reading runs or snapshots).
How it works with POST /v1/runs
A task run is a server-driven agent that executes until success, failure, timeout, or cancellation. The endpoint accepts machine_id, task, cua_version, instructions (optional), system_prompt, max_steps, deadline_seconds, on_awaiting_human, and webhook_url. The server bills $0.05 per agent step. When you include Idempotency-Key, the API stores the request. If you call the same endpoint again with the same key, the server recognizes it as a replay and returns the stored result without creating a new run. This prevents duplicate billing.
curl https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: run-$(uuidgen)" \
-d '{"machine_id": "m-123","task": "open chrome and navigate to example.com","cua_version": "v3","max_steps": 10,"deadline_seconds": 300}'How it works with POST /v1/machines
Provisioning a cloud machine with POST /v1/machines also supports Idempotency-Key. The request body includes machine_id (optional), image_name, ssh_key, region, and other fields. Each successful provisioning counts against your prepaid USD wallet where 1 credit equals $0.01. Using an idempotency key ensures that retries do not spin up multiple machines for the same intent.
import os, requests, uuid, json
def provision_machine():
url = "https://coasty.ai/v1/machines"
key = os.getenv("COASTY_API_KEY")
payload = {
"image_name": "ubuntu-22.04",
"region": "us-east-1",
"ssh_key": os.getenv("SSH_KEY")
}
headers = {
"X-API-Key": key,
"Content-Type": "application/json",
"Idempotency-Key": f"machine-{uuid.uuid4()}"
}
resp = requests.post(url, json=payload, headers=headers)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
machine = provision_machine()
print(json.dumps(machine, indent=2))Always include Idempotency-Key on the original reserve-and-replay request and never add it later.
Where this beats brittle automation
Traditional automation relies on brittle selectors and fixed API endpoints. If a UI changes or an API contract shifts, your scripts fail. The computer use API lets agents see the screen and act like a human, adapting to dynamic layouts without hard selectors. Combining that flexibility with idempotency keys means you can retry agents, re-provision machines, or retry workflows without risking duplicate charges. This pairs well with webhooks for event-driven pipelines.
Use idempotency keys to make your computer use agent and machine provisioning requests replay-safe. This prevents duplicate billing and lets you build robust, event-driven automation. Get your API key at https://coasty.ai/developers and start building reliable computer use workflows today.