Build an Autonomous Agent That Finishes a Task With /v1/runs
Most desktop automation depends on brittle selectors or hardcoded APIs. You click X on Y only if the element exists. If the UI changes, your script breaks. The /v1/runs endpoint changes that. It provisions a machine, launches a computer use agent, and drives the UI like a human. You send a machine_id and a task. The agent captures screens, predicts actions, and updates the task state until it succeeds, fails, times out, or reaches a human handoff. This works for browsers, terminals, and any app with a graphical interface.
How /v1/runs works
The core request is a POST to /v1/runs. Required fields are machine_id and task. The task is a human-readable instruction. Optional but important fields are cua_version (v3 or v4), max_steps, deadline_seconds, and on_awaiting_human. If the agent asks for human help, on_awaiting_human decides what to do: pause, fail, or cancel the run. The server returns a run_id. You poll /v1/runs or stream events via GET /v1/runs/{id}/events. The agent is billed $0.05 per step. You manage credits in a prepaid USD wallet. States are queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out.
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "aws-t3-small-default",
"task": "Open Chrome and navigate to https://coasty.ai/docs, then take a screenshot of the first heading.",
"cua_version": "v3",
"max_steps": 20,
"deadline_seconds": 180,
"on_awaiting_human": "pause"
}'Track the agent state
- ●GET /v1/runs lists all runs for your key.
- ●GET /v1/runs/{id} shows the current state and metadata.
- ●GET /v1/runs/{id}/events streams Server-Sent Events. Reconnect with Last-Event-ID.
- ●States include queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
- ●You can cancel a run with POST /v1/runs/{id}/cancel or resume it with POST /v1/runs/{id}/resume.
POST /v1/runs initiates an autonomous agent on your machine and returns a run_id to track the task.
When to use v4
The v4 cua_version adds an autonomous pass/fail verifier. The agent attempts the task, checks if it succeeded, and reports the result. This is useful for production pipelines where you want the agent to self-evaluate. You can still provide instructions and a system_prompt to shape behavior. The billing model stays $0.05 per step.
Where this beats brittle automation
With selectors, you must know the class name, ID, or XPath in advance. If the layout changes, your automation fails. With the /v1/runs endpoint, the agent reads the screen, understands text and layout, and clicks the most likely element. It adapts to UI changes on the fly. It can handle apps that expose no API, navigate complex multi-step flows, and fall back to human approval when needed. This is a true computer use agent, not a script that assumes a fixed DOM.
The /v1/runs endpoint gives you an autonomous agent that drives real desktops and browsers. You define a task and let the agent handle the steps. Track state via runs and events, cancel or resume as needed, and integrate webhooks for notifications. Start building agents that finish tasks without brittle selectors. Get your API key at https://coasty.ai/developers.