Build an Autonomous Agent That Finishes a Task With /v1/runs
You need an agent that launches an app, clicks through the UI, fills in data, and confirms success, without hardcoding selectors or maintaining brittle integrations. The /v1/runs endpoint is the simplest way to get a Coasty computer use agent onto a real desktop and drive it to completion. It handles the capture, prediction, and action loop for you, so you can focus on the task definition.
How /v1/runs works
Submit a POST request to /v1/runs with a machine_id and a task description. The server provisions a cloud VM, starts a desktop session, and launches the agent. The agent runs in a loop: it captures a screenshot, predicts the next action, and executes it until the task is done or the state changes to a terminal condition. You can stream live events with GET /v1/runs/{id}/events and poll GET /v1/runs/{id}. Key top-level fields on the request body include machine_id, task, cua_version (default is v3, v4 is autonomous with pass/fail verifier), instructions (appended to the base prompt), system_prompt, max_steps, deadline_seconds, on_awaiting_human (pause, fail, or cancel), and webhook_url for async callbacks. The response returns an id and initial state (queued, running, succeeded, failed, cancelled, 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": "machine-abc123",
"task": "Open a browser, navigate to https://example.com, and click the first link",
"cua_version": "v3",
"max_steps": 50,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}'
What you get back
- ●An id that you use to poll for status and stream events.
- ●Initial state: queued, running, succeeded, failed, cancelled, or timed_out.
- ●GET /v1/runs/{id}/events returns Server-Sent Events that include step results, actions, and status changes.
- ●You can cancel or resume a run with POST /v1/runs/{id}/cancel and POST /v1/runs/{id}/resume.
Read the machine_id from your provisioning system or use a default placeholder like "machine-abc123".
Where /v1/runs beats brittle automation
Selector-based solutions break as soon as a UI changes, requiring constant updates to XPaths and CSS selectors. The Coasty computer use agent sees the screen like a human, so it can adapt to layout shifts, dynamic IDs, and unfamiliar apps. It runs on real desktops, browsers, and terminals, not just an abstraction layer. You describe the task in plain English and let the agent discover the steps, which reduces maintenance and lets you cover more workflows with less code.
Pricing and limits
- ●Task runs are billed $0.05 per agent step, including capture, prediction, and action.
- ●You can cap steps with max_steps to control costs.
- ●Deadline_seconds set a hard timeout; a timed_out run does not incur further charges beyond the steps taken.
- ●Use webhook_url for asynchronous callbacks or poll GET /v1/runs/{id} for synchronous polling.
Now you can build autonomous agents that drive real desktops, browsers, and terminals to complete user tasks end-to-end. Next, try defining a workflow with /v1/workflows to chain multiple runs, assert outcomes, and handle retries. Get your API key at https://coasty.ai/developers to start running agents today.