Build an Autonomous Agent That Finishes a Task with /v1/runs
Most automation tools rely on brittle selectors and static APIs. When a UI changes or an element moves, your script breaks. The /v1/runs endpoint changes that. It sends your task to a real desktop or browser, watches the screen, and lets the agent act like a human. You just define the goal and a few guardrails. The server runs the agent to completion. You pay per step, not per hour.
How /v1/runs works
You POST a run definition to /v1/runs. The server creates a task run and starts a machine with a desktop. The agent repeatedly captures the screen, predicts the next action, executes it, and streams events back. The run finishes when the agent reaches the final state or you cancel it. The response includes the run ID, status, and links to events and cancellation. The server tracks the state machine: queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
#!/usr/bin/env bash
# POST /v1/runs to launch an autonomous agent
export COASTY_API_KEY="$COASTY_API_KEY"
curl -s https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "vm-12345",
"task": "Open Chrome, visit https://coasty.ai/docs, and click the Get a Key link",
"cua_version": "v4",
"max_steps": 50,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}' | jq .Run lifecycle and state machine
- ●queued: the request arrived and the server is allocating resources.
- ●running: the agent is capturing screenshots, predicting actions, and executing them.
- ●awaiting_human: the agent encountered a step that needs human input. You can pause, fail, or cancel the run.
- ●succeeded: the agent finished all steps and achieved the task.
- ●failed: the run stopped due to an error or a failure guard.
- ●cancelled: you called POST /v1/runs/{id}/cancel.
- ●timed_out: the run exceeded deadline_seconds.
Each agent step costs $0.05. The server drives real desktops, browsers, and terminals, not just API calls.
Where this beats brittle automation
Instead of writing CSS selectors or XPath expressions that break when a UI changes, you describe what you want. The agent looks at the screen and finds the right element. It handles dynamic text, missing IDs, and layout shifts. You can drive real browsers and terminals, not just mocked APIs. This makes your agent more resilient to the real world, not less.
What to build next
Start with a simple browser task: visit a site, fill a form, navigate to a confirmation page. Then move to desktop tasks: click through an installer, update a file, or run a CLI command. Use workflows to orchestrate multiple runs, checkpoints, and conditional logic. Explore the MCP server to drive Coasty from Cursor or Claude Desktop. Get a key and start building autonomous agents at https://coasty.ai/developers.