You want an agent that sees the screen, interprets natural language, and performs actions until a task succeeds or fails. The Coasty /v1/runs endpoint lets you start a full autonomous run from a single request. The server drives the agent through a machine, takes screenshots, predicts actions, and reports progress via Server-Sent Events. You can cancel or resume the run at any time. This guide shows the exact request format, the event stream, and code you can copy to build a bounded, stateful automation.
How /v1/runs works
POST /v1/runs launches a task run on a provisioned machine. The request body contains the machine identifier, the task description, the CUA version, and optional controls. The agent repeatedly captures the screen, predicts actions, and executes them until status is done. The response includes the run ID. Progress is streamed via GET /v1/runs/{id}/events. The server returns events of type queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out. You can stop or resume the run with POST /v1/runs/{id}/cancel and POST /v1/runs/{id}/resume.
export COASTY_API_KEY=your_key_here
# 1. Launch a task run
RUN_RESPONSE=$(curl -s -X POST https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "your_machine_id",
"task": "Open Chrome, navigate to https://example.com, find the heading containing "Hello", and click the first link",
"cua_version": "v3",
"max_steps": 100,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}')
RUN_ID=$(echo $RUN_RESPONSE | jq -r '.id')
echo "Run ID: $RUN_ID"
# 2. Stream events
curl -N -H "Authorization: Bearer $COASTY_API_KEY" \
https://coasty.ai/v1/runs/$RUN_ID/eventsKey request fields
- machine_id: a cloud VM provisioned via /v1/machines. The agent drives a real desktop, browser, or terminal.
- task: natural language describing the task. The server interprets it and maps it to screen perception and actions.
- cua_version: current version of the computer use agent. Use "v3" for standard behavior or "v4" for autonomous mode with a pass/fail verifier.
- max_steps: upper bound on the number of agent steps. Each step is billed $0.05.
- deadline_seconds: hard timeout for the entire run. If exceeded, the run status becomes timed_out.
- on_awaiting_human: what to do when the agent needs human input. Options are pause, fail, or cancel.
One POST to /v1/runs gives you a bounded, stateful autonomous run that you can cancel or resume at any time.
Where this beats brittle automation
Traditional automation relies on fixed selectors, IDs, and DOM snapshots. When UI changes, your bot breaks. The Coasty computer use API lets the agent see the screen at every step and infer the right action from natural language. It handles dynamic layouts, hidden elements, and context shifts without hard-coded selectors. This makes it ideal for exploratory testing, data extraction from evolving dashboards, and any workflow that spans multiple applications.
You now know how to launch an autonomous agent with /v1/runs, monitor its progress via events, and control it with cancel and resume operations. Use this endpoint to build bounded, semantically driven automation that works across real desktop environments. Get a key and start building at https://coasty.ai/developers.
Want to see this in action?
View Case Studies