Build an Autonomous Agent That Finishes Tasks with /v1/runs
Many automation tools break when a UI changes or a popup appears. The /v1/runs endpoint lets you spin up an agent that sees the screen and acts like a human. It takes a task description, a cloud machine, and a deadline, then returns a live event stream you can watch in real time. You do not need brittle selectors or fragile APIs.
How it works
You POST to /v1/runs with a machine_id, a task string, and optional parameters. The server spawns an agent on a live desktop or browser, runs steps, and streams events back to you. Each agent step costs $0.05. The endpoint supports cua_version, max_steps, deadline_seconds, and on_awaiting_human. You can cancel or resume a run later. The response includes a run_id you can use with GET /v1/runs/{id} and the event stream GET /v1/runs/{id}/events.
#!/usr/bin/env bash
# POST /v1/runs with an existing machine_id
# Replace MACHINE_ID with a real cloud VM ID from /v1/machines
COASTY_API_KEY="${COASTY_API_KEY}"
MACHINE_ID="${MACHINE_ID}"
TASK='open https://example.com in the browser, type a search term into the query box, and click the first result'
curl --silent --show-error --fail \
-H "X-API-Key: ${COASTY_API_KEY}" \
-H "Content-Type: application/json" \
-d "{
\"machine_id\": \"${MACHINE_ID}\",
\"task\": \"${TASK}\",
\"cua_version\": \"v4\",
\"max_steps\": 400,
\"deadline_seconds\": 360,
\"on_awaiting_human\": \"pause\"
}" \
https://coasty.ai/v1/runsKey request fields
- ●machine_id: required, from /v1/machines. The agent runs on this cloud VM.
- ●task: required, a natural language description of what to do.
- ●cua_version: defaults to v3; v4 adds a pass/fail verifier and autonomous behavior.
- ●max_steps: optional, maximum number of agent steps. Each step bills $0.05.
- ●deadline_seconds: optional, wall‑clock seconds before the run times out.
- ●on_awaiting_human: optional, one of pause, fail, cancel. What to do when the agent needs human input.
- ●webhook_url: optional, for asynchronous callbacks. The server signs webhooks with Coasty-Signature header (t=unix,v1=hex).
One line to remember: each agent step on /v1/runs costs $0.05.
Where this beats brittle automation
API-only tools rely on stable endpoints and stable selector patterns. When a site updates a class name or inserts a new modal, those tools stop working. A computer use agent sees the screen, reads text, and clicks buttons exactly where they appear. It can handle pop‑ups, captcha prompts, and unexpected layout changes. You describe the goal in plain language, not in a fragile mapping of selectors.
Track progress with the event stream
Use GET /v1/runs/{id}/events to receive Server-Sent Events. The stream returns a state per event: queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out. Reconnect with the Last-Event-ID header if you lose the connection. This gives you real‑time visibility into the agent’s actions, not just a final status.
You now know how to POST /v1/runs and stream events for an autonomous computer use agent. Build workflows with /v1/workflows or drive the agent from MCP clients. Get a key at https://coasty.ai/developers and start automating real desktops and browsers.