Build an Autonomous Agent with /v1/runs: The Computer Use API
Most automation tools rely on brittle selectors or full API wrappers. They break when a class name changes or a button moves. The /v1/runs endpoint puts a real agent in front of the screen. You send a task description, start the run, and stream events until the agent succeeds or fails. You can pause the run, cancel it, and resume later. It works on real browsers, desktop apps, and terminals, not just mock APIs.
How /v1/runs works
POST https://coasty.ai/v1/runs starts a task run. The request body describes the task and the agent behavior. Required fields: - machine_id: the cloud VM ID you want the agent to use. Provision one with POST /v1/machines. - task: the natural language instruction (e.g., "Navigate to https://coasty.ai" and click the sign-up button). - cua_version: the computer use agent version. Default is "v3". "v4" adds a pass/fail verifier. Optional fields: - instructions: extra text added to the base prompt. - system_prompt: a custom system prompt to steer behavior. - max_steps: maximum actions the agent can take. - deadline_seconds: time limit before the run times out. - on_awaiting_human: what to do if the agent asks for human help (pause, fail, or cancel). - webhook_url: where to receive live events via Server-Sent Events. The agent sees the screen, interprets the task, and emits actions. You receive a run ID and can query the status or stream events.
import os
import json
import requests
COASTY_API_KEY = os.getenv("COASTY_API_KEY")
BASE_URL = "https://coasty.ai/v1"
# Example POST /v1/runs to launch an agent with a webhook
def start_autonomous_run(machine_id: str, task: str, instructions: str = None, webhook_url: str = None):
url = f"{BASE_URL}/runs"
headers = {
"Authorization": f"Bearer {COASTY_API_KEY}",
}
body = {
"machine_id": machine_id,
"task": task,
"cua_version": "v3",
}
if instructions:
body["instructions"] = instructions
if webhook_url:
body["webhook_url"] = webhook_url
resp = requests.post(url, json=body, headers=headers)
resp.raise_for_status()
return resp.json()
# Example response
run = start_autonomous_run(
machine_id="vm-12345",
task="Open a browser and navigate to https://coasty.ai/docs",
instructions="Ensure you read the docs thoroughly before completing the task.",
webhook_url="https://your-server.com/hooks/coasty-events"
)
print(json.dumps(run, indent=2))
# Expected fields in the response object:
# {"id": "run-abc123", "machine_id": "vm-12345", "task": "...", "cua_version": "v3", "status": "queued"...}Run lifecycle and states
- ●queued: the run is waiting for a machine or resources.
- ●running: the agent is actively performing actions.
- ●awaiting_human: the agent paused for approval; use on_awaiting_human to fail or cancel.
- ●succeeded: the agent completed the task successfully.
- ●failed: the agent encountered an unrecoverable error.
- ●cancelled: the run was stopped via POST /v1/runs/{id}/cancel.
- ●timed_out: the run hit deadline_seconds without success.
Manage runs with HTTP methods
- ●GET /v1/runs lists all runs for your account.
- ●GET /v1/runs/{id} returns detailed information for a specific run.
- ●POST /v1/runs/{id}/cancel stops the agent immediately.
- ●POST /v1/runs/{id}/resume restarts a paused run.
- ●GET /v1/runs/{id}/events streams Server-Sent Events; reconnect with the Last-Event-ID header.
POST /v1/runs launches an agent, streams events, and bills $0.05 per agent step.
Where this beats brittle automation
Traditional automation uses hardcoded selectors, XPath, or full API wrappers. Changes in layout or class names break those scripts. The computer use agent sees the real screen, interprets text and layout, and chooses actions like humans. It can handle dynamic sites, popups, and non-API workflows. You get a single endpoint that works across browsers, desktop apps, and terminals. You can pause for human review, cancel on failure, or resume later. The /v1/runs endpoint gives you observable, controllable, and reliable automation at scale.
Start building autonomous computer use agents with POST /v1/runs. Provision a machine, describe the task, and stream events to your webhook. The agent works with real screens and handles complex workflows that brittle selectors cannot. Get your API key at https://coasty.ai/developers and start automating the hard stuff.