Building an Autonomous Agent That Finishes a Task with /v1/runs
You do not want to track IDs, CSS selectors, or fragile XPath expressions for every button, dialog, or loading spinner. You want an agent that sees the screen and acts like a human. The /v1/runs computer use API endpoint gives you a server-driven agent that watches your desktop or browser, follows natural language instructions, and reports back when done. It bills $0.05 per agent step, streams events in real time, and supports pausing for human approval.
How /v1/runs works
You send a POST request to /v1/runs with a machine_id, a task description, and optional parameters. The server provisions a VM, starts the agent, and loops through prediction steps that capture a screenshot, compute actions, and apply them. The response includes a run_id you can use to inspect status, events, and results. You can cancel or resume a run at any time. The agent state machine follows states like queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out.
curl -X POST https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "vm-1234",
"task": "Open a new browser tab, navigate to example.com, and print the page title to the terminal",
"cua_version": "v4",
"max_steps": 50,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}'Request fields you need
- ●machine_id: the identifier of the cloud VM you provisioned via POST /v1/machines.
- ●task: plain language instructions that the agent interprets to drive the desktop.
- ●cua_version: set to "v4" for autonomous behavior with a pass/fail verifier, or the default "v3".
- ●max_steps: maximum number of agent steps allowed to prevent runaway runs.
- ●deadline_seconds: time limit for the run to complete before it times out.
- ●on_awaiting_human: one of pause, fail, or cancel when the agent encounters a human interaction point.
- ●webhook_url (optional): where the server sends final status updates.
One line to remember: POST /v1/runs, read COASTY_API_KEY from environment, and poll GET /v1/runs/{id} (or stream events) to see your agent in action.
Tracking progress with events
Use GET /v1/runs/{id}/events to stream Server-Sent Events. The event stream includes status updates, step results, and any human approval prompts. You can reconnect using the Last-Event-ID header if the connection drops. This gives you real-time visibility into what the agent sees and does on the screen.
Where this beats brittle automation
Traditional automation tools rely on stable selectors and hard-coded steps. When a UI changes, your scripts break. A computer use agent uses vision to read the screen, understand context, and adapt its actions. It can handle dynamic content, multiple windows, and human-like interactions like clicking, typing, and scrolling. You do not need to maintain a library of selectors, only a clear task description.
You can now spin up an autonomous agent that watches your desktop, follows natural language instructions, and completes complex workflows. Use max_steps and deadline_seconds to control cost, and on_awaiting_human to pause for human input when needed. Ready to build your own computer use agent? Get a key at https://coasty.ai/developers.