Build an Autonomous Agent with /v1/runs
You want an agent that opens a browser, navigates a site, fills a form, and clicks Submit without brittle XPath selectors or driver code. The /v1/runs endpoint lets you send a task description and a machine_id. The Coasty server runs a computer use agent on that machine until the task is done. You get a single run ID, events stream, and final status.
How /v1/runs works
POST /v1/runs accepts a JSON body. It requires machine_id and task. You can set cua_version to 'v3' or 'v4'; v4 includes an automatic pass/fail verifier. You can also supply optional instructions (appended to the base prompt), system_prompt, max_steps, deadline_seconds, on_awaiting_human, and webhook_url. The server returns a run object with id, machine_id, task, status, and other fields. You track progress with GET /v1/runs/{id} or via the Server-Sent Events stream at GET /v1/runs/{id}/events.
import os
import requests
import json
def start_task():
url = "https://coasty.ai/v1/runs"
api_key = os.environ.get("COASTY_API_KEY")
if not api_key:
raise ValueError("COASTY_API_KEY environment variable is required")
machine_id = "your-machine-id-here" # from /v1/machines
task = "Open https://example.com in the browser, click the 'About' link, and print the page title."
cua_version = "v4"
payload = {
"machine_id": machine_id,
"task": task,
"cua_version": cua_version,
"max_steps": 30,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
resp = requests.post(url, json=payload, headers=headers)
resp.raise_for_status()
run = resp.json()
print("Run ID:", run["id"])
print("Status:", run["status"])
return run
if __name__ == "__main__":
run = start_task()Key fields and configuration
- ●machine_id: a cloud VM provisioned via POST /v1/machines. The agent runs directly on that machine's desktop.
- ●task: a natural language description the agent interprets. It can include app names, URLs, and desired outcomes.
- ●cua_version: 'v3' for guided tasks, 'v4' for autonomous tasks with a pass/fail verifier.
- ●max_steps: upper bound on the number of agent steps. Each step costs $0.05.
- ●deadline_seconds: absolute timeout for the run. Exceeding it ends the run with timed_out status.
- ●on_awaiting_human: behavior when the agent encounters a prompt it cannot resolve: 'pause', 'fail', or 'cancel'.
- ●webhook_url: optional URL for asynchronous status updates. Coasty sends an HMAC-signed webhook with header Coasty-Signature.
POST /v1/runs with machine_id, task, and cua_version (v4 recommended) to launch an autonomous computer use agent on a real desktop.
Where this beats brittle automation
Traditional automation relies on brittle selectors like CSS classes, IDs, or XPath that change with UI releases. A computer use agent sees the screen like a human, responds to layout changes, and works across browsers, terminals, and native apps. With /v1/runs you offload the entire execution flow to the server, including navigation, input handling, and error recovery guided by your task description. You still pay per agent step ($0.05), but you save on driver maintenance, selector updates, and fragile scripts.
Next steps
Provision a machine with POST /v1/machines, then call /v1/runs to launch your first task. Stream events with GET /v1/runs/{id}/events to receive real-time status updates. Explore workflows (POST /v1/workflows) for multi-step orchestrations, or use the free /v1/parse endpoint to convert PyAutoGUI snippets into structured actions. Get your API key at https://coasty.ai/developers and start building autonomous agents that drive real desktops.