Build an Autonomous Agent That Finishes a Task With /v1/runs
You want a single API call that spins up an agent, watches the screen, interacts with UI elements, and returns a final result. The /v1/runs endpoint does exactly that. It provisions a machine, runs a task with a computer use agent, and streams events until the task succeeds, fails, or times out. You do not manage screenshots, frames, or state. You just send a task and get a result.
How /v1/runs works
POST /v1/runs is the entry point for a task run. The body must include machine_id, task, and cua_version. machine_id is the ID of a cloud VM you provisioned with POST /v1/machines. task is the objective the agent must complete. cua_version defaults to v3, but v4 adds an autonomous pass/fail verifier. You can append instructions, provide a custom system prompt, set max_steps, deadline_seconds, and on_awaiting_human to pause, fail, or cancel the run. The server then returns a run ID. Use GET /v1/runs/{id} to poll the status or stream events via GET /v1/runs/{id}/events.
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "m-12345",
"task": "Open Chrome and go to https://example.com",
"cua_version": "v3",
"instructions": "Do not close the browser.",
"max_steps": 100,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}'Key request fields
- ●machine_id: the ID of a VM provisioned with POST /v1/machines
- ●task: the objective the agent must complete
- ●cua_version: v3 for guided runs, v4 for autonomous runs with a verifier
- ●instructions: optional text appended to the agent prompt
- ●system_prompt: optional system-level instructions
- ●max_steps: maximum number of agent steps before stopping
- ●deadline_seconds: timeout in seconds for the entire run
- ●on_awaiting_human: action when the agent needs human input (pause, fail, cancel)
Response and status lifecycle
The initial POST /v1/runs returns a run object with id, status, and created_at. Valid statuses include queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out. Use GET /v1/runs/{id} to fetch the current status. For real-time updates, stream events from GET /v1/runs/{id}/events. The server sends Server-Sent Events with a status field and a data payload that describes the step's action, screenshot, or error. Reconnect with the Last-Event-ID header if the connection drops.
Where this beats brittle automation
Traditional automation relies on brittle selectors, XPath, or hard-coded coordinates. When UI changes, selectors break and you must rewrite scripts. The computer use agent sees the screen, interprets text and layout, and uses vision to click, type, and drag like a human. This means the same agent can adapt to different sites, window states, and layout shifts without code changes. You get a single endpoint that handles the complexity of screenshots, mouse movements, and error recovery.
POST /v1/runs costs $0.05 per agent step, billed against your prepaid wallet.
Start by provisioning a machine with POST /v1/machines, then submit a task with POST /v1/runs. Watch the run status and events to monitor progress. Build workflows by orchestrating multiple runs with /v1/workflows. Get a key and try it out at https://coasty.ai/developers.