Build an Autonomous Agent That Finishes a Task with /v1/runs
Writing scripts that click buttons by coordinate or text is brittle. A layout change breaks everything. You need an agent that can see the screen and act like a human. The /v1/runs endpoint spins up a computer use agent, drives real desktops or browsers, and waits until the task succeeds, fails, or times out. You only pay $0.05 per agent step. This post shows how to build a task runner that finishes work on its own.
How /v1/runs works
POST /v1/runs creates a task run. The server provisions a machine (cloud VM), starts a computer use agent, and executes your prompt. Required fields: machine_id, task, cua_version. cua_version can be "v3" or "v4". v4 is autonomous with a pass/fail verifier. Optional fields: instructions (appended to the base prompt), system_prompt, max_steps, deadline_seconds, on_awaiting_human (pause, fail, cancel), and webhook_url. The request returns a run_id. You poll GET /v1/runs/{id} to see the state: queued, running, awaiting_human, succeeded, failed, cancelled, timed_out. GET /v1/runs/{id}/events streams Server-Sent Events for real-time progress. Billing is $0.05 per agent step. Use the events stream to show progress in your UI.
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "machine_12345",
"task": "Open Chrome and navigate to https://example.com, click the first heading, and close the tab.",
"cua_version": "v4",
"max_steps": 50,
"deadline_seconds": 600,
"on_awaiting_human": "pause"
}'State machine and events
- ●queued: the run is waiting for a machine and agent.
- ●running: the agent is actively performing steps.
- ●awaiting_human: the agent paused and waits for your decision.
- ●succeeded: all steps completed and the task finished as expected.
- ●failed: the agent hit an unrecoverable state or the verifier failed.
- ●cancelled: you sent POST /v1/runs/{id}/cancel.
- ●timed_out: deadline_seconds elapsed without completion.
Use GET /v1/runs/{id}/events to stream real-time progress and update your UI.
Where this beats brittle automation
Most automation tools rely on fixed selectors like CSS classes or XPath. A layout change or a different browser version breaks the selector. A computer use agent sees the screen like a human. It reads text, distinguishes buttons from labels, and follows visual context. It handles dynamic elements, popups, and unexpected layouts without brittle selectors. The /v1/runs endpoint also provisions a real cloud VM. The agent can open browsers, edit documents, or run terminal commands. You orchestrate multi-step workflows with a single API call. You only pay per successful agent step, so you control costs.
You can now spin up autonomous agents for real desktops and browsers. Use /v1/runs to drive tasks, poll GET /v1/runs/{id} for state, and stream events for progress. Build workflows, verify outcomes, and integrate with your existing systems. Get your API key at https://coasty.ai/developers and start building.