Writing scripts that click buttons by label or ID works for simple tasks. It breaks when layout changes, or elements are hidden, or you need to reason across multiple apps. The /v1/runs endpoint solves this by running a computer use agent on a real machine. You send a task and a machine ID, the agent sees the screen, plans steps, and drives the UI autonomously until success or failure.
How /v1/runs works
You start a task run by POSTing to /v1/runs with a machine_id, a task description, and optional controls. The server provisions a cloud VM (or uses an existing one) and launches an agent that sees the screen, follows instructions, and executes actions. The run flows through states like queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out. You can inspect the run's events stream with GET /v1/runs/{id}/events to watch progress in real time. Billed $0.05 per agent step.
# Start an autonomous run
export COASTY_API_KEY="your-key-here"
curl -X POST https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "vm-12345",
"task": "Open Chrome, navigate to https://example.com, and click the first link.",
"cua_version": "v4",
"on_awaiting_human": "pause",
"max_steps": 30,
"deadline_seconds": 120
}'Key request fields
- machine_id: A VM you provision via POST /v1/machines or an existing one.
- task: Natural-language description of the goal.
- cua_version: Use "v3" for basic autonomous runs or "v4" for runs with a pass/fail verifier.
- on_awaiting_human: What to do when the agent needs human input, pause, fail, or cancel.
- max_steps: Maximum number of agent steps before the run stops.
- deadline_seconds: Timeout in seconds after which the run times out.
- webhook_url (optional): HTTPS endpoint to receive completion notifications with HMAC signature.
Start a run with POST /v1/runs, then stream events with GET /v1/runs/{id}/events.
Where /v1/runs beats brittle automation
API-only tools rely on stable selectors. If a button is hidden, nested inside an iframe, or the layout shifts, your script fails. A computer use agent sees the UI like a human does. It reads the text, position, and context, then chooses actions that match the current state. This works across browsers, desktop apps, and terminals without maintaining brittle selectors. You express intent in natural language and let the agent adapt to whatever the screen shows.
The /v1/runs endpoint gives you a computer use agent that drives real machines to completion. Start with a simple task, then experiment with workflows and machine provisioning. Get your key and start building at https://coasty.ai/developers.
Want to see this in action?
View Case Studies