Build an Autonomous Agent with /v1/runs in Three Steps
You want an agent that opens a browser, types into a login form, submits, navigates some steps, and then verifies success without you writing explicit selectors or a full Python script. The /v1/runs endpoint handles this for you. It provisions a computer use agent, sends a natural language task, and streams events until the agent succeeds, fails, or requests human input. This post shows the real request fields, the response flow, and a working Python example.
How /v1/runs works
The /v1/runs endpoint is the entry point for autonomous task runs. You POST a JSON payload with a machine_id, a task string, and optional parameters. The server creates a task run, spins up a computer use agent on the specified machine, and streams events back to you. The run progresses through states such as queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out. Billing is $0.05 per agent step.
import os
import json
import requests
from typing import Dict, Any
def create_task_run() -> Dict[str, Any]:
url = "https://coasty.ai/v1/runs"
api_key = os.getenv("COASTY_API_KEY")
if not api_key:
raise RuntimeError("COASTY_API_KEY must be set")
payload = {
"machine_id": os.getenv("COASTY_MACHINE_ID"),
"task": "Open Chrome, navigate to example.com, and click the first link.",
"cua_version": "v3",
"max_steps": 50,
"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()
return resp.json()
if __name__ == "__main__":
run = create_task_run()
print(json.dumps(run, indent=2))Key request fields
- ●"machine_id" (required): The id of a provisioned machine to run the agent on.
- ●"task" (required): A natural language description of what the agent should do.
- ●"cua_version" (optional, default "v3"): The computer use agent version to use.
- ●"max_steps" (optional): Maximum number of agent steps before the run times out.
- ●"deadline_seconds" (optional): Total time limit for the run.
- ●"on_awaiting_human" (optional): Action when the agent encounters human input. Options are "pause", "fail", "cancel".
- ●"webhook_url" (optional): Callback URL to receive run events via POST.
POST /v1/runs creates a live task run that streams events and bills $0.05 per agent step.
Monitoring runs with events
To track progress, you can either poll GET /v1/runs or stream events from GET /v1/runs/{id}/events. The events endpoint returns Server-Sent Events (SSE). You can use the Last-Event-ID header to reconnect after a disconnect. Each event contains information about the run state, actions the agent took, or errors. Polling GET /v1/runs/{id} also returns the current state.
Where this beats brittle automation
Traditional automation relies on CSS selectors, XPath, or hardcoded element IDs. If a page changes, your scripts break. The computer use agent in a /v1/runs task sees the screen and acts like a human. It clicks, types, and navigates based on visual cues. This makes your automation resilient to layout changes, dynamic content, and multi-step flows that are hard to express in declarative selectors.
With /v1/runs you can focus on describing what needs to happen instead of how to click or type. Try running the example above, then explore workflows, stateful sessions with /v1/sessions, or the ground /v1/parse endpoint for more control. Get an API key at https://coasty.ai/developers to start building autonomous agents.