Build an Autonomous Agent with /v1/runs to Finish Tasks Automatically
You want to automate a multi-step process that involves clicking buttons, filling forms, and checking results on a live desktop or browser. Traditional UI automation relies on brittle selectors that break when a layout shifts. Instead, use the /v1/runs endpoint to start an autonomous computer use agent that can see the screen, interpret it, and act like a human. One request spins up a task run, the server drives the agent through steps, and you can stream events to follow progress and handle pauses.
How /v1/runs works
The /v1/runs endpoint accepts a JSON body and returns a run object that contains an ID, a status, and other metadata. You send a machine_id to specify which cloud machine the agent will use, and you provide a task description telling the agent what to do. You can also set cua_version to choose the agent behavior, add instructions that are appended to the system prompt, provide a system_prompt that customizes the agent’s personality, and define a deadline_seconds after which the run times out. You can configure how the server behaves when it encounters an awaiting_human state with on_awaiting_human set to pause, fail, or cancel. Optionally, you can provide a webhook_url to receive final results via an HMAC-signed webhook. The server bills $0.05 per agent step. Once the request succeeds, you receive a run ID. You can then GET /v1/runs/{id} to inspect status, GET /v1/runs to list runs, or stream events with GET /v1/runs/{id}/events using the Last-Event-ID header for reconnection. You can also cancel a run with POST /v1/runs/{id}/cancel or resume it with POST /v1/runs/{id}/resume.
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "m-abc123",
"task": "Open the Coasty website and find the pricing page",
"cua_version": "v4",
"instructions": "If you see a login modal, skip it",
"system_prompt": "You are a helpful assistant that uses the computer to complete tasks. Always try to finish the task before returning. If you get stuck, ask for clarification.",
"max_steps": 200,
"deadline_seconds": 600,
"on_awaiting_human": "pause",
"webhook_url": "https://your-domain.com/webhooks/coasty"
}'State machine and events
- ●When you POST /v1/runs, the run status starts as queued.
- ●The server assigns a run_id and begins executing the task.
- ●While running, the status changes to running and the agent performs actions on the machine.
- ●If the agent encounters a human approval step, the status becomes awaiting_human and on_awaiting_human determines the behavior.
- ●When the task finishes, the status becomes succeeded, failed, cancelled, or timed_out.
- ●You can stream progress with GET /v1/runs/{id}/events. Reconnect with the Last-Event-ID header if the connection drops.
- ●You can cancel any running or awaiting_human run with POST /v1/runs/{id}/cancel.
- ●You can resume a paused run with POST /v1/runs/{id}/resume.
POST /v1/runs starts an autonomous agent on a machine and returns a run_id that you use to stream events and control the run.
Where this beats brittle automation
Selectors and XPath patterns break when a developer changes a UI layout, adds a new class, or reorders elements. A computer use agent can see the screen, interpret visual elements, and decide where to click based on context. It can handle dynamic content, unexpected layouts, and mixed platforms such as desktop apps and browsers. Because the server drives the agent step by step, you can pause for human approval, cancel if something looks wrong, and resume later. This makes workflows more resilient and easier to maintain.
The /v1/runs endpoint gives you a simple way to spin up an autonomous computer use agent that drives a live machine and completes tasks. Use it to automate multi-step workflows that rely on visual state. Next, explore /v1/sessions for stateful trajectory memory or /v1/ground to map element descriptions to coordinates. Get your API key at https://coasty.ai/developers to start building.