Build an Autonomous Agent That Finishes a Task With /v1/runs
You want an agent that can log in, click buttons, fill forms, and navigate a real browser or desktop to finish a task. Traditional tools rely on brittle selectors and APIs that only expose a small surface. The /v1/runs endpoint lets you describe a goal and hand it off to a computer use agent that sees the screen and acts like a human. It returns a run ID you can poll or stream events from.
How /v1/runs works
POST /v1/runs starts a task run on a machine. The request body can include machine_id, task, cua_version, instructions, system_prompt, max_steps, deadline_seconds, on_awaiting_human, and webhook_url. The server provisions a machine, runs the agent, and updates the run state. You can GET /v1/runs to list runs, GET /v1/runs/{id} for details, POST /v1/runs/{id}/cancel, POST /v1/runs/{id}/resume, or stream events with GET /v1/runs/{id}/events (Server-Sent Events). States include queued, running, awaiting_human, succeeded, failed, cancelled, timed_out. Billing is $0.05 per agent step.
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 the GitHub homepage, search for Coasty, and click the first result",
"cua_version": "v4",
"max_steps": 20,
"deadline_seconds": 120,
"on_awaiting_human": "pause",
"webhook_url": "https://your-server.com/webhook/coasty"
}'Key fields and options
- ●machine_id: identifier of the machine to use (required)
- ●task: natural language description of the goal (required)
- ●cua_version: protocol version; v4 provides autonomous execution with a pass/fail verifier
- ●instructions: appended to the base prompt for extra context
- ●system_prompt: custom system prompt for the agent
- ●max_steps: maximum agent steps before stopping (default is higher)
- ●deadline_seconds: time limit for the run
- ●on_awaiting_human: how to handle human approval; options are "pause", "fail", "cancel"
- ●webhook_url: endpoint to receive run events and status updates
- ●Billing: $0.05 per agent step
The core idea: POST /v1/runs with a machine_id, task, and cua_version, then poll /v1/runs/{id} or stream events to know when the agent finishes.
Where this beats brittle automation
Selector-based tools break when UI changes or elements are dynamically generated. The computer use agent sees the actual screen, parses text and layout, and acts on what it observes. It can handle new buttons, hidden fields, or unexpected prompts without code changes. It also supports real desktops, browsers, and terminals, not just a limited API surface. This makes it suitable for complex, multi-step workflows that would require dozens of brittle selectors or multiple scripts.
Next steps
Try running a task with /v1/runs, then hook up the webhook to store results or trigger downstream jobs. Explore workflows, sessions, or the MCP server to integrate Coasty into Cursor, Claude Desktop, or other tools. Get your API key and start building autonomous agents at https://coasty.ai/developers.