You want an agent that can open a browser, navigate a site, fill a form, click a button, and then report success or failure. You do not want to write brittle selectors or maintain a script for every UI change. The /v1/runs endpoint is the entry point for task runs where Coasty provisions a cloud VM, starts a desktop, and drives it with a computer use agent. You send a task and optional instructions, and you get back a run you can stream events from, cancel, and resume.
How /v1/runs works
POST /v1/runs starts a task run. You provide a machine_id to run on, a task description, and optional parameters. The request body looks like this. { "machine_id": "machine-abc123", "task": "Open https://example.com and click the login button", "cua_version": "v3", "max_steps": 100, "deadline_seconds": 600, "on_awaiting_human": "pause", "webhook_url": "https://your-server.com/webhook" } The server creates a run and returns a run object with an id, current state (queued, running, succeeded, failed, cancelled, timed_out), and start time. You can poll GET /v1/runs or GET /v1/runs/{id} to check status. To follow the run in real time, subscribe to GET /v1/runs/{id}/events with Last-Event-ID for reconnection.
curl https://coasty.ai/v1/runs \ \
-H "Content-Type: application/json" \ \
-H "X-API-Key: $COASTY_API_KEY" \ \
-d '{
"machine_id": "machine-abc123",
"task": "Open https://example.com and click the login button",
"cua_version": "v3",
"max_steps": 100,
"deadline_seconds": 600,
"on_awaiting_human": "pause",
"webhook_url": "https://your-server.com/webhook"
}'Task run states and lifecycle
- queued: run is in the queue and not yet running
- running: the agent is actively driving the desktop
- awaiting_human: the agent paused waiting for human approval (on_awaiting_human: pause)
- succeeded: the agent finished the task
- failed: the agent hit a failure condition or max_steps
- cancelled: you sent POST /v1/runs/{id}/cancel
- timed_out: the run exceeded deadline_seconds
POST /v1/runs starts a task run, and GET /v1/runs/{id}/events streams the agent's actions in real time.
Where this beats brittle automation
Traditional automation relies on stable selectors, XPath, or API wrappers that break when UI changes or when elements are obscured. The computer use agent sees the screen, understands the context, and reacts like a human. It can handle dynamic layouts, popups, and navigation flows without you rewriting selectors. With /v1/runs you get a complete lifecycle management model where you can cancel a run, resume it later, and integrate with webhooks for event notification.
Next steps
- Provision a machine with POST /v1/machines to get a machine_id
- Add instructions to the base prompt for more control
- Use cua_version "v4" for an autonomous run with pass/fail verification
- Stream events to build dashboards or logs
- Integrate with workflows to orchestrate multiple runs
The /v1/runs endpoint gives you a production-ready way to run autonomous computer use agents on cloud VMs. You can cancel, resume, and monitor runs in real time, and you pay by agent step at $0.05 per step. Get your API key at https://coasty.ai/developers and start building agents that finish real desktop tasks.
Want to see this in action?
View Case Studies