Build an Autonomous Agent That Finishes a Task with /v1/runs
You want an agent that opens an app, clicks around, fills a form, and confirms success. Hard-coding X,Y coordinates and brittle selectors breaks fast. The /v1/runs endpoint gives you a stateful, step-billed agent that actually sees the screen and acts like a human. It works in browsers, desktop apps, and terminals on real machines.
How /v1/runs works
POST /v1/runs accepts a machine_id, task description, and optional parameters. The server launches an agent on that machine, repeatedly captures the screen, predicts actions, and executes them until the task succeeds or fails. Each agent step costs $0.05. The response returns a run_id, state, and a stream of events. You can pause, resume, or cancel the run at any time.
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "mach-12345",
"task": "Open Chrome, navigate to https://example.com, find the search bar, type \"hello\", and click the first result",
"cua_version": "v3",
"max_steps": 60,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}' | jq .Run states and lifecycle
- ●queued: run accepted and waiting for an agent
- ●running: agent actively predicting and acting
- ●awaiting_human: human approval requested, controlled by on_awaiting_human
- ●succeeded: task finished successfully
- ●failed: task could not complete, check events for reasons
- ●cancelled: canceled by your client
- ●timed_out: deadline_seconds exceeded
Use GET /v1/runs/{id}/events to stream state and agent actions, then reconnect with the Last-Event-ID header.
Where this beats brittle automation
API-only tools require you to know every endpoint, parameter, and response shape ahead of time. They break when UI changes. With /v1/runs the agent sees the actual screen, understands natural language instructions, and retries by itself. It handles missing buttons, dynamic IDs, and layout shifts without you writing extra selectors.
Next steps
Try a simple task in a real browser or desktop. Then explore workflows for multi-step flows, conditionals, and retries. Get a key at https://coasty.ai/developers and start shipping agents that finish work instead of breaking on the first UI change.
The /v1/runs endpoint gives you a stateful, step-billed computer use agent. Each agent step costs $0.05. Use GET /v1/runs/{id}/events to watch progress. Build agents that see screens and act like humans, not brittle scripts. Get your key at https://coasty.ai/developers .