You want an agent that can click, type, and navigate like a human. But the API gives you two CUA versions. v3 gives you control over every step. v4 runs autonomously and verifies success. Knowing which to use saves money and headaches.
What the versions do
- PUT /v1/runs accepts cua_version. Set cua_version to v3 for a controllable agent. Set it to v4 for an autonomous agent with a pass/fail verifier.
- v3 runs tasks in steps you can monitor and cancel. Each step costs $0.05.
- v4 also bills $0.05 per agent step but adds a verifier. The verifier checks if the agent succeeded or failed. It returns a pass/fail result.
- Both versions use the same POST /v1/runs request body. cua_version is the only extra field.
How to create a task run
Use POST /v1/runs to start a task run. The body requires machine_id and task. You can also include instructions, system_prompt, max_steps, deadline_seconds, on_awaiting_human, and webhook_url. Set cua_version to either v3 or v4. The server returns a run_id. Use GET /v1/runs/{id} to poll status. Status can be queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out.
Create a v3 task run in bash. Replace YOUR_COASTY_API_KEY, YOUR_MACHINE_ID, and YOUR_TASK with real values.
COASTY_API_KEY="$(cat ~/.coasty-key 2>/dev/null || echo 'YOUR_COASTY_API_KEY')"
machine_id="YOUR_MACHINE_ID"
task="Open Chrome and navigate to https://coasty.ai"
response=$(curl -s -X POST https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "'$machine_id'",
"task": "'$task'",
"cua_version": "v3",
"max_steps": 15,
"on_awaiting_human": "pause"
}')
echo "$response"
# Example output (truncated)
# {"run_id":"abc123","status":"queued","cua_version":"v3"...}Create a v4 task run in Python. Use the COASTY_API_KEY environment variable.
import os
import requests
COASTY_API_KEY = os.getenv("COASTY_API_KEY")
machine_id = "YOUR_MACHINE_ID"
task = "Open Chrome and navigate to https://coasty.ai"
url = "https://coasty.ai/v1/runs"
headers = {"Authorization": f"Bearer {COASTY_API_KEY}", "Content-Type": "application/json"}
payload = {
"machine_id": machine_id,
"task": task,
"cua_version": "v4",
"max_steps": 20,
"on_awaiting_human": "pause"
}
resp = requests.post(url, headers=headers, json=payload)
resp.raise_for_status()
run = resp.json()
print(run)
# Example output (truncated)
# {"run_id":"def456","status":"queued","cua_version":"v4"...}Polling and events
- GET /v1/runs returns a list of runs. GET /v1/runs/{id} returns a single run.
- GET /v1/runs/{id}/events streams Server-Sent Events (SSE). Reconnect with Last-Event-ID if you lose the connection.
- When status is succeeded or failed, the run object includes a result field with pass/fail and details.
- You can cancel a running task with POST /v1/runs/{id}/cancel and resume with POST /v1/runs/{id}/resume.
Where this beats brittle automation
Traditional automation relies on selectors, XPath, or static selectors that break when UI changes. The CUA versions act on real screenshots. They see what you see. v3 lets you inspect actions. v4 lets you offload to the server and still verify success. Both versions drive real desktops, browsers, and terminals. This is why the Coasty OSWorld benchmark shows 85.6% success on in-house models and 82.81% on public leaderboards.
Set cua_version to v3 for control and debugging, or v4 for autonomous runs with a pass/fail verifier.
Start building with the right CUA version. Create a machine, then spin up a v3 or v4 task run. Use POST /v1/runs and monitor the status. Get your API key at https://coasty.ai/developers.
Want to see this in action?
View Case Studies