You want an agent that can open an app, fill a form, verify results, and close everything without you writing brittle selectors. The /v1/runs endpoint gives you that. It launches an agent on a real desktop, drives it step by step, and reports state changes via events. You get back a task run ID, a status, and a stream of events until the task succeeds, fails, or times out.
How /v1/runs works
POST /v1/runs takes a machine_id, a task description, and optional settings. The server provisions a cloud VM, starts the agent, and begins the run. You can set cua_version to 'v4' for an autonomous run with a pass/fail verifier. You can supply instructions, system_prompt, max_steps, deadline_seconds, and a webhook_url for async results. The response gives you the run ID. GET /v1/runs/{id} returns the current state. GET /v1/runs/{id}/events streams Server-Sent Events with queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out states. You can pause or cancel a run with POST /v1/runs/{id}/cancel and resume with POST /v1/runs/{id}/resume. Each agent step costs $0.05.
# Start an autonomous run on machine_id 'my-desktop-1'
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "my-desktop-1",
"cua_version": "v4",
"task": "Open Chrome, go to https://example.com, type in the search box and press Enter, then close Chrome",
"system_prompt": "You are a helpful assistant that operates a desktop.",
"max_steps": 100,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}'
Key request fields
- machine_id: cloud VM identifier
- cua_version: v3 (guided) or v4 (autonomous with pass/fail verifier)
- task: description of the task
- system_prompt: custom behavior instructions
- max_steps: maximum agent steps before stopping
- deadline_seconds: time limit for the run
- on_awaiting_human: pause, fail, or cancel when the agent needs human input
- webhook_url: optional endpoint to receive run events asynchronously
- billing: $0.05 per agent step
The run ID you get from /v1/runs is your anchor to monitor progress and control the agent.
Where this beats brittle automation
Traditional web or desktop automation relies on selectors, XPath, or hardcoded coordinates that break when UI changes. The computer use agent sees the same screen you see, interprets images and text, and clicks or types naturally. It can handle dynamic elements, popups, and multi-step workflows without brittle selectors. You describe what you want in plain language, and the agent does the rest on a real desktop.
Use /v1/runs to launch an autonomous agent that can complete a variety of tasks on a real desktop. Monitor state via events, cancel or resume runs as needed, and scale your workflows. Get a key and start building at https://coasty.ai/developers.
Want to see this in action?
View Case Studies