Idempotency Keys in the Computer Use API: Never Double Charge
When you spin up a computer use agent with POST /v1/runs, network glitches or retries can trigger the same task twice. Since each agent step costs $0.05, a single glitch can waste your prepaid wallet. The Coasty computer use API adds an Idempotency-Key header to write operations so retries produce the same result without extra charges.
How it works
POST /v1/runs accepts an Idempotency-Key header. If you retry the same request with an identical key while the run is still queued or running, the server returns the existing run ID instead of starting a new one. This keeps the prepaid wallet safe and guarantees idempotent task execution.
#!/usr/bin/env bash
# Example: Create a task run with idempotency key
# Uses the exact endpoint and headers from the API docs.
set -euo pipefail
COASTY_API_KEY="${COASTY_API_KEY:-}"
if [[ -z "$COASTY_API_KEY" ]]; then
echo "Error: COASTY_API_KEY environment variable is required." >&2
exit 1
fi
# Choose a unique, stable key for this task
IDEMPOTENCY_KEY="$(uuidgen)"
# POST /v1/runs
# machine_id, task, cua_version, max_steps, deadline_seconds are required
# on_awaiting_human, webhook_url, system_prompt, instructions are optional
curl -sS https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d ' {
"machine_id": "12345678",
"task": "open chrome, navigate to https://example.com, take a screenshot",
"cua_version": "v3",
"max_steps": 20,
"deadline_seconds": 120,
"on_awaiting_human": "pause",
"webhook_url": "https://your-domain.com/coasty-webhook"
} ' \
| jq '.'Required and optional fields for task runs
- ●machine_id: identifier of the cloud VM to drive.
- ●task: natural language description of the user intent.
- ●cua_version: 'v3' for guided, 'v4' for autonomous with pass/fail verifier.
- ●max_steps: upper bound on agent steps for this run.
- ●deadline_seconds: absolute timeout for the run.
- ●on_awaiting_human: 'pause', 'fail', or 'cancel' when agent needs human input.
- ●webhook_url: endpoint to be notified of events via Server-Sent Events.
- ●system_prompt: optional base system prompt to customize agent behavior.
- ●instructions: optional extra instructions appended to the task.
The Idempotency-Key header makes write operations safe to retry, preventing duplicate runs and overbilling.
Where this beats brittle automation
API-only tools often rely on brittle selectors that break when UI changes. The Coasty computer use API lets the agent see the screen, understand context, and act like a human. This means fewer flaky selectors, higher success rates, and more reliable workflows. Combined with idempotency keys, you can retry agents when the network hiccups without worrying about your prepaid wallet.
Handling webhook events safely
Webhooks are signed with HMAC. The Coasty-Signature header includes a Unix timestamp (t) and a hex HMAC (v1). Use this to verify authenticity. The events endpoint GET /v1/runs/{id}/events streams Server-Sent Events. If you reconnect, send the Last-Event-ID header to resume reading. This keeps your orchestration layer in sync without double-triggering runs.
Add idempotency keys to every POST /v1/runs call and your computer use agents will stay reliable and budget-aware. Get your API key and start building at https://coasty.ai/developers.