Automation scripts often break when UI changes or a hidden element moves. A computer use agent that reads the screen and acts like a human keeps working. The /v1/runs endpoint launches a server-driven agent on a virtual machine and bills per step. You submit a task and get back a run ID that you can query, cancel, or resume. This post walks through a concrete example of an agent that logs into a cloud dashboard, updates a status flag, and confirms success.
How /v1/runs works
POST /v1/runs launches a task run on a cloud machine. You provide the machine_id so the agent has a real desktop or browser environment. The task field contains the user intent in natural language. cua_version defaults to v3 but you can request v4 for autonomous mode with a pass/fail verifier. You can append instructions to the base prompt, set a system_prompt, limit max_steps to 20, or enforce a deadline_seconds. If the agent encounters an ambiguous state you can set on_awaiting_human to pause, fail, or cancel. The endpoint returns a run object with id, status, and metadata. You can stream events via GET /v1/runs/{id}/events to watch the agent in real time. The server bills $0.05 per agent step.
#!/bin/bash
export COASTY_API_KEY=$(cat $HOME/.coasty_key)
machine_id="m-abc123xyz"
# Start an agent that updates a ticket status
curl -s https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "'"$machine_id"'",
"task": "Log into the DevPortal at https://portal.example.com, navigate to the Tickets page, find the ticket with subject \"Bug in checkout\", change its status to \"Resolved\", and take a screenshot showing the updated status."
}' | jq .import os
import requests
import json
def start_task_run(task_description, machine_id):
api_key = os.getenv("COASTY_API_KEY")
url = "https://coasty.ai/v1/runs"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
payload = {
"machine_id": machine_id,
"task": task_description,
"cua_version": "v3",
"max_steps": 20,
"deadline_seconds": 300,
}
resp = requests.post(url, headers=headers, json=payload)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
run = start_task_run(
task_description="Log into the DevPortal, navigate to the Tickets page, find the ticket with subject 'Bug in checkout', change its status to 'Resolved', and take a screenshot showing the updated status.",
machine_id="m-abc123xyz"
)
print(json.dumps(run, indent=2))Key fields and options
- machine_id: identifier of the cloud VM the agent runs on
- task: natural language description of the end goal
- cua_version: v3 for guided steps, v4 for autonomous with a pass/fail verifier
- instructions: additional context appended to the base prompt
- system_prompt: custom persona for the agent
- max_steps: hard limit on agent steps (default is 20)
- deadline_seconds: server stops the run after this time
- on_awaiting_human: pause, fail, or cancel when the agent asks a human
- webhook_url: notify your service via an HMAC-signed event
- billed at $0.05 per step
The /v1/runs endpoint launches a server-driven agent on a cloud machine and bills $0.05 per step.
Where this beats brittle automation
API-only tools depend on stable endpoints, request bodies, and HTTP headers. When a UI changes, selectors break, and scripts fail. A computer use agent reads the screen using the /v1/predict endpoint (or the underlying sessions/predict API), understands the context, and clicks or types naturally. It can handle dynamic page layouts, popups, and contextual hints without hard-coded selectors. The agent works on a real desktop, browser, or terminal, not on mock responses. This makes it ideal for multi-step workflows that span different applications and require human-like attention.
What to build next
With /v1/runs you can deploy agents for onboarding, support triage, or internal tooling. Try a workflow that loops through a list of URLs, runs a task on each, and aggregates results. Use the MCP server to drive Coasty from Cursor or Claude Desktop. For more details and a key, visit the Coasty developer portal.
Start building an autonomous computer use agent that finishes real tasks with the Coasty Computer Use API. Get your API key at https://coasty.ai/developers.
Want to see this in action?
View Case Studies