Build an Autonomous Computer Use Agent with /v1/runs
Most automation tools rely on brittle selectors, fixed X/Y coordinates, or APIs that do not surface the whole UI. You want an agent that can see the screen, understand English instructions, and complete multi-step workflows on real browsers, desktop apps, and terminal sessions. The /v1/runs endpoint gives you a single entry point to launch a stateful, autonomous computer use agent. You provide a task, an optional verifier, and control over timeouts, retries, and human approvals. The API drives the session until the task finishes or fails, and you stream events and status throughout.
How /v1/runs works
To start a task run, send a POST to /v1/runs with these required fields. The agent runs in a fresh machine environment. It captures screenshots, predicts actions, and executes them in a loop until the server reports a final status. You can use cua_version to pick the agent model. cua_version v3 is a baseline, v4 is autonomous with a pass/fail verifier. The server bills $0.05 for each agent step. The returned run object includes an id, status, and metadata. You can poll GET /v1/runs/{id} or subscribe to Server-Sent Events at GET /v1/runs/{id}/events to follow progress.
import os, json, httpx, time
from typing import Optional, Dict, Any
def create_task_run(task: str, cua_version: str = "v4") -> Dict[str, Any]:
"""Start an autonomous agent run with /v1/runs."""
url = "https://coasty.ai/v1/runs"
api_key = os.getenv("COASTY_API_KEY")
if not api_key:
raise RuntimeError("COASTY_API_KEY environment variable must be set")
payload = {
"task": task,
"cua_version": cua_version,
"max_steps": 100,
"deadline_seconds": 600,
"on_awaiting_human": "pause"
}
headers = {"X-API-Key": api_key}
resp = httpx.post(url, json=payload, headers=headers, timeout=30)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
run = create_task_run("Navigate to coasty.ai and search for 'computer use API'")
run_id = run["id"]
print("Run started", run_id, run["status"])
# Optional: stream events from /v1/runs/{id}/eventsKey /v1/runs fields and options
- ●task: the natural language instruction for the agent.
- ●cua_version: 'v3' for baseline or 'v4' for autonomous with a pass/fail verifier.
- ●max_steps: maximum agent steps before stopping. Each step costs $0.05.
- ●deadline_seconds: time limit for the run. The server may time out the task.
- ●on_awaiting_human: pause, fail, or cancel when the agent needs human input.
- ●webhook_url: optional URL for webhook callbacks on state changes.
- ●id: unique identifier returned after the run is queued.
- ●status: one of queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
POST /v1/runs and stream events from /v1/runs/{id}/events to follow a stateful autonomous agent.
Where this beats brittle automation
API-only tools must guess IDs, classes, or positions that change on layout or localization. Selectors break when the DOM updates or when apps ship new versions. The computer use agent sees the same pixels a human sees. It can read text, recognize icons, and handle dynamic layouts. With /v1/runs you do not need to write selectors, hard-coded clicks, or brittle wait logic. The agent works across browsers, desktop apps, and terminals using a shared computer use API. This approach scales to complex workflows like multi-page forms, navigation flows, and error recovery.
Next steps
Try launching a run for a real task on your own machine. Use max_steps and deadline_seconds to control budget and latency. Switch to cua_version v4 to enable a pass/fail verifier for automated quality checks. Monitor events to understand how the agent interprets the UI and where it might need clearer instructions. If you want to orchestrate multi-step workflows, explore /v1/workflows. For per-step actions with vision, use /v1/predict. Get your API key at https://coasty.ai/developers and start building agents that truly see and act like humans.
The /v1/runs endpoint gives you a single, reliable way to launch autonomous computer use agents. You focus on the task description and the verifier. The API handles the loop, the screen captures, and the execution. Build workflows that adapt to real UI changes without maintaining brittle selectors. Get your key at https://coasty.ai/developers and start automating tasks with a computer use agent.