Build an Autonomous Agent That Finishes Tasks with /v1/runs
You want an agent that can open a browser, log into an app, fill a form, and click a button. You could write a library of selectors and wait for elements to appear, but that breaks when layouts shift. The /v1/runs endpoint gives you a task runner that spins up a computer use agent, uses vision to see the screen, and acts like a human. The agent drives a real machine, not just API calls. You send a task, the system handles the steps, and you can poll for status or stream events.
How /v1/runs works
You POST to /v1/runs with a task description and a machine_id. The agent executes on a cloud VM with a real desktop. Fields you can use include task (string), cua_version (string, default v3), max_steps (integer), deadline_seconds (integer), and on_awaiting_human (string: pause, fail, or cancel). You can also provide system_prompt and instructions that append to the prompt. The response gives a run_id. You then GET /v1/runs/{id} or stream events from /v1/runs/{id}/events. States include queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out.
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "vm-12345",
"task": "Open https://example.com, find the login link, click it, type admin in the username field, type password in the password field, and click the submit button.",
"cua_version": "v3",
"max_steps": 50,
"deadline_seconds": 60,
"on_awaiting_human": "pause"
}'
Polling a run
- ●Use GET /v1/runs to list all runs or GET /v1/runs/{id} to inspect a single run.
- ●Each run has a status field and a result object if the run succeeded.
- ●A failed run includes an error object with code, message, and request_id.
- ●You can cancel an in-progress run with POST /v1/runs/{id}/cancel or resume it with POST /v1/runs/{id}/resume.
POST /v1/runs spins up a computer use agent on a real machine, charges $0.05 per agent step, and returns a run_id you can track.
Where this beats brittle automation
Traditional automation relies on selectors like XPath or CSS selectors. If a layout changes, those break. The computer use agent sees the screen through vision, understands natural language instructions, and clicks or types in the right place. It can handle dynamic popups, login prompts, and changing layouts without you rewriting selectors. You just describe the task in plain language and let the agent drive the machine. This makes your automation more robust and easier to maintain.
Next steps
- ●Provision a machine with POST /v1/machines and use the returned machine_id in your run.
- ●Stream events with GET /v1/runs/{id}/events to see real-time agent activity.
- ●Use workflows (POST /v1/workflows) to chain runs with tasks, asserts, and loops.
- ●Manage your wallet balance and billing with a prepaid USD wallet where 1 credit is $0.01.
Now you can build an autonomous agent that finishes tasks using /v1/runs. Spin up a machine, send a task, and let the computer use agent do the rest. Get your API key at https://coasty.ai/developers and start automating real workflows.