Build an Autonomous Agent That Finishes a Task With /v1/runs
Most automation code relies on brittle selectors, versioned APIs, or fragile wrappers around popular services. You end up rewriting selectors when a UI changes or debugging timeouts when a third-party API ramps up. The /v1/runs endpoint gives you a different approach. You provision a real cloud machine, describe the task in plain English, and let an agent that sees the screen and acts like a human finish the work for you. The server streams events back so you can track progress and react to human approvals, cancellations, or failures.
How it works
The flow starts with a POST to /v1/runs. You provide a machine_id (provisioned from /v1/machines), a task string, the cua_version (default v3, v4 adds a pass/fail verifier), and optional instructions, system_prompt, max_steps, deadline_seconds, on_awaiting_human, and a webhook_url. The server spins up the machine, launches the agent, and streams events back via Server-Sent Events from /v1/runs/{id}/events. States include queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out. Billing is $0.05 per agent step. You can query runs with GET /v1/runs or get a specific run with GET /v1/runs/{id}, cancel with POST /v1/runs/{id}/cancel, or resume with POST /v1/runs/{id}/resume.
#!/bin/bash
set -e
COASTY_API_KEY="${COASTY_API_KEY}"
BASE="https://coasty.ai/v1"
# 1. Provision a cloud machine
MACHINE_RESPONSE=$(curl -s -X POST "$BASE/machines" \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "ubuntu-22.04", "type": "small"}')
machine_id=$(echo "$MACHINE_RESPONSE" | jq -r .id)
echo "Provisioned machine $machine_id"
# 2. Start a task run
task_id=$(curl -s -X POST "$BASE/runs" \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "$machine_id",
"task": "browse https://coasty.ai, find the pricing page, and click the get started button",
"cua_version": "v3",
"max_steps": 20,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}' | jq -r .id)
echo "Task run $task_id started"
# 3. Stream events (reconnect with Last-Event-ID)
curl -N "$BASE/runs/$task_id/events" \
-H "X-API-Key: $COASTY_API_KEY" | while read line; do
echo "$line"
done
# 4. Cancel if you want to stop early (optional)
curl -s -X POST "$BASE/runs/$task_id/cancel" \
-H "X-API-Key: $COASTY_API_KEY"Key fields you provide to /v1/runs
- ●machine_id: the ID of a cloud VM provisioned from /v1/machines.
- ●task: plain language description of what the agent should do.
- ●cua_version: v3 (default) or v4 (autonomous with pass/fail verifier).
- ●instructions: optional extra instructions appended to the base prompt.
- ●system_prompt: optional system-level instructions for the agent.
- ●max_steps: hard limit on agent steps (helps control cost).
- ●deadline_seconds: hard deadline the server enforces.
- ●on_awaiting_human: pause, fail, or cancel when the agent requests human input.
- ●webhook_url: optional URL to POST JSON results with HMAC signature.
POST /v1/runs with machine_id and task returns an id; then GET /v1/runs/{id}/events streams state updates and $0.05 per agent step.
Where this beats brittle automation
With traditional selectors you must know exactly which class, id, or xpath will exist in the future. When a UI changes, your script breaks. The computer use agent sees the screen and decides where to click, what to type, and how to navigate. It works with real desktops, browsers, and terminals, not just mocked APIs. You can also handle human approvals by setting on_awaiting_human to pause and react in your own workflow. The server-side memory and the ability to provision machines mean you can run end-to-end workflows on real environments without building your own bot framework.
Spin up a machine, submit a task to /v1/runs, and stream events to know when the agent is done. Use the output to drive your own systems or integrate with webhooks for async results. The agent works with real desktops and browsers, so you can automate complex workflows without brittle selectors. Get a key and start building at https://coasty.ai/developers