Build an Autonomous Agent That Finishes a Task with /v1/runs
You need an agent that can open a browser, log in, click around, and finish a multi-step task on a real desktop. Hard-coded selectors and API-only tools fail when UI changes or you need to inspect pages. The /v1/runs endpoint gives you a stateful task run where the server drives a computer use agent from start to finish. You provide a machine_id, task description, and optional constraints. The system returns a run object with an id, state, and an event stream you can poll or watch live.
How /v1/runs works
POST /v1/runs deploys an agent on a provisioned machine. The agent uses a computer use model (v3 or v4) to see the screen, understand natural language, and act via pyautogui-style actions. The request body includes machine_id, task, cua_version (default v3, v4 adds a pass/fail verifier), optional instructions, system_prompt, max_steps, deadline_seconds, on_awaiting_human, and webhook_url. The response is a run object with id, status, and metadata. Billing is $0.05 per agent step. You can cancel (POST /v1/runs/{id}/cancel) or resume (POST /v1/runs/{id}/resume) a run. GET /v1/runs/{id}/events streams Server-Sent Events, reconnecting on Last-Event-ID.
curl -X POST https://coasty.ai/v1/runs \
-H 'X-API-Key: $COASTY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"machine_id": "m-abc123",
"task": "Open https://example.com in Chrome, find the search box, type Python and hit enter",
"cua_version": "v3",
"max_steps": 60,
"deadline_seconds": 600,
"on_awaiting_human": "pause",
"webhook_url": "https://myserver.com/webhook/coasty"
}'Key fields and billing
- ●machine_id: required, the cloud VM where the agent runs.
- ●task: required, natural language description of the task.
- ●cua_version: default v3, v4 adds a verifier.
- ●instructions: optional, extra context you want appended to the prompt.
- ●system_prompt: optional, system-level instructions for the agent.
- ●max_steps: optional, cap on steps per run.
- ●deadline_seconds: optional, absolute time limit.
- ●on_awaiting_human: pause, fail, or cancel when the agent asks for human help.
- ●webhook_url: optional, POST callback when run state changes.
- ●Billing: $0.05 per agent step.
- ●States: queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
POST /v1/runs with machine_id and task, then watch events with GET /v1/runs/{id}/events. Billed $0.05 per agent step.
Where this beats brittle automation
API-only tools depend on stable endpoints and JSON responses. When UI changes, selectors break, and you need to inspect the page, selectors are fragile. The computer use agent sees the actual screen pixel data. It understands natural language, adapts to layout changes, and can click the right element even if its ID changes. You also get a stateful run with a clear state machine (queued, running, awaiting_human, succeeded, failed, cancelled, timed_out) and live event streams. You can pause, resume, cancel, or hook into webhooks instead of polling. This makes long-lived workflows and human-in-the-loop tasks much easier to build.
Now you can spin up a task run that drives a real desktop, browser, or terminal. Try it out with a real machine_id from POST /v1/machines. For more endpoints, pricing, and examples, get a key at https://coasty.ai/developers.