You have a browser task that clicks a button, fills a form, and confirms a success message. No public API exists, the DOM is dynamic, and your selectors break on every deploy. Traditional automation tools can only follow a fixed script, so every change means a new update. The /v1/runs endpoint flips that model: you give the agent a goal, a cua_version, and it watches the screen, decides what to do next, and keeps acting until the task is done. This is how you build a real computer use agent for real tasks.
How /v1/runs works
The task run is a stateful lifecycle that you start with a POST request to /v1/runs. The server provisions a cloud machine, launches a computer use agent, and drives it until the task finishes. The request body includes a machine_id to target a specific VM, the task text that describes the goal, and the cua_version that configures how the agent behaves. For v4 you enable a pass/fail verifier that stops the run if the task does not succeed. Optional fields let you set a deadline_seconds, append instructions to the base prompt, define a webhook_url for async results, and configure on_awaiting_human to pause, fail, or cancel the run if the agent needs human approval. The server returns a run object with an id and an initial status of queued. The endpoint bills $0.05 per agent step, so you pay only for the actions the agent actually takes.
curl -X POST https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "cloud-vm-12345",
"task": "Go to https://coasty.ai/docs, click the Get API Key button, and take a screenshot of the key modal.",
"cua_version": "v4",
"deadline_seconds": 300,
"on_awaiting_human": "pause",
"webhook_url": "https://myapp.com/coasty/webhook"
}'Watching the agent progress
- GET /v1/runs returns a paginated list of recent runs.
- GET /v1/runs/{id} fetches the current state of a specific run.
- GET /v1/runs/{id}/events streams Server-Sent Events that emit events like queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
- When reconnecting to the stream include the Last-Event-ID header to resume from the last received event.
- Each event includes a timestamp, a status, an optional message, and an optional action log from the agent.
Use GET /v1/runs/{id}/events with Last-Event-ID to reliably stream agent actions and status updates.
Where this beats brittle automation
API-only automation must know every field, URL, and payload ahead of time. If the UI changes, your script breaks without a human noticing. The computer use API lets the agent see the actual screen, understand what it sees, and choose the next click or keystroke based on context. This means the same agent can handle different layouts, dynamic content, and even rare workflows without you rewriting selectors. You can also integrate the agent into workflows that call other services, validate results, or retry failed steps, all while paying only for the actions the agent actually takes. Because the agent runs on a real machine, it can interact with native apps, terminals, and browser tooling that no pure API can reach.
You now have a concrete way to spin up an autonomous computer use agent that watches the screen, decides where to click, and keeps going until the task is done. With /v1/runs you get a full lifecycle with status tracking, webhooks, and per-step billing. Try it out with your own task, stream the events to build real-time dashboards, and integrate it into larger workflows. Ready to build your own agent? Get a key at https://coasty.ai/developers and start running tasks with the computer use API.
Want to see this in action?
View Case Studies