Build an Autonomous Agent That Finishes a Task With /v1/runs
Writing selectors for every button and field is brittle. You want an agent that can see a screen and take actions like a human. The /v1/runs endpoint gives you exactly that. You submit a task, a machine, and a few runtime controls, and the server drives the desktop until the job succeeds, fails, or times out. No manual retries, no rework for layout changes. You just define the goal, and the agent does the rest.
How /v1/runs works
POST /v1/runs starts a task run on a provisioned machine. You provide machine_id, task, and optional instructions. The server boots the cloud VM, starts a desktop, and runs the computer use agent (CUA) version v3 by default, or v4 for autonomous mode with a pass/fail verifier. The agent captures screenshots, plans actions, and executes them. Billing is $0.05 per agent step. The endpoint returns a run_id, its current state, and a webhook_url for event notifications. You can GET /v1/runs, GET /v1/runs/{id}, or stream events with GET /v1/runs/{id}/events. You can cancel or resume a run by ID.
curl -X POST https://coasty.ai/v1/runs \
-H 'X-API-Key: $COASTY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"machine_id": "machine_abc123",
"task": "Open Chrome, navigate to https://example.com, and print the page title",
"cua_version": "v4",
"max_steps": 30,
"deadline_seconds": 300,
"on_awaiting_human": "pause",
"webhook_url": "https://your-server.com/hooks/coasty"
}'Request fields you define
- ●machine_id (required): the VM to drive, provisioned via POST /v1/machines.
- ●task (required): the natural-language goal the agent must achieve.
- ●cua_version (optional): 'v3' for guided runs, 'v4' for autonomous with a pass/fail verifier.
- ●instructions (optional): extra guidance appended to the base prompt.
- ●system_prompt (optional): custom system instructions for the agent.
- ●max_steps (optional): cap on agent steps to avoid runaway work.
- ●deadline_seconds (optional): how long the run can live before timing out.
- ●on_awaiting_human (optional): 'pause' to stop on human approval, 'fail' to abort, or 'cancel' to stop.
- ●webhook_url (optional): endpoint for Server-Sent Events about run state.
Responses and states
- ●On success, the run transitions to 'succeeded' and the agent has achieved the task.
- ●On failure, it becomes 'failed' and the final event explains why.
- ●States include queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
- ●GET /v1/runs lists your runs. GET /v1/runs/{id} returns the latest state.
- ●GET /v1/runs/{id}/events streams events with Last-Event-ID for reconnects.
POST /v1/runs for a task run billed $0.05 per agent step.
Where this beats brittle automation
Traditional automation depends on stable IDs, XPath, or CSS selectors. Changing a layout or upgrading an app breaks everything. With a computer use agent, the system sees the screen in real time, interprets text and layout, and clicks or types naturally. It adapts to minor UI shifts without you to rewrite selectors. You also drive real browsers, desktop apps, and terminals, not simulated clicks. This makes it ideal for workflows that involve chat interfaces, dynamic dashboards, or third-party apps without official APIs.
Start with a simple task run against a single machine. Add workflows to orchestrate multiple runs, checkpoints, and error handling. As your agents handle more complex jobs, integrate with your own systems via webhook events. Get your API key at https://coasty.ai/developers and begin building autonomous desktop agents with the /v1/runs endpoint.