Build an Autonomous Agent That Finishes a Task with /v1/runs
Most automation tools rely on brittle selectors or mock APIs. The /v1/runs endpoint lets you spin up a real computer use agent that drives a cloud VM and finishes a task end-to-end. You send a task description, the agent acts like a human, and you get a success or failure status. This works for CLI tasks, browser workflows, or any desktop interaction.
How /v1/runs works
POST /v1/runs starts an agent run. You provide a machine_id to target a cloud VM, a task description, and optional instructions that are appended to the base prompt. The cua_version defaults to v3, but you can request v4 for an autonomous agent with a pass/fail verifier. You can also set max_steps, deadline_seconds, and on_awaiting_human to pause, fail, or cancel if the agent expects a human. The server returns a run_id and initial state (queued, running, etc.). You can stream events with GET /v1/runs/{id}/events or poll GET /v1/runs/{id} until the run finishes. Each agent step costs $0.05. The run state can be succeeded, failed, cancelled, or timed_out. There is no retry logic for the run step itself, but you can cancel or resume a run.
#!/usr/bin/env bash
set -euo pipefail
COASTY_API_KEY="${COASTY_API_KEY}"
BASE_URL="https://coasty.ai/v1"
TASK='Open Chrome, navigate to https://coasty.ai, take a screenshot, close Chrome, and return the screenshot as a base64 string.'
run_id=$(curl -s -X POST "${BASE_URL}/runs" \
-H "Authorization: Bearer ${COASTY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "cloud-vm-123",
"task": "'"${TASK}"'",
"cua_version": "v3",
"max_steps": 50,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}' | jq -r '.run_id')
echo "Run ID: ${run_id}"
echo "Waiting for run to finish..."
while true; do
status=$(curl -s -X GET "${BASE_URL}/runs/${run_id}" \
-H "Authorization: Bearer ${COASTY_API_KEY}" | jq -r '.state')
echo "Status: ${status}"
if [[ "${status}" == "succeeded" || "${status}" == "failed" || "${status}" == "cancelled" || "${status}" == "timed_out" ]]; then
break
fi
sleep 2
done
echo "Run finished with status: ${status}"Response shape and fields
- ●run_id: unique identifier for the run.
- ●state: one of queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
- ●error_code and error_message: present if the run failed.
- ●events: a paginated array of actions and intermediate states if you use GET /v1/runs/{id}/events.
POST /v1/runs starts an autonomous agent and returns a run_id; poll GET /v1/runs/{id} or stream events until the run ends.
Where this beats brittle automation
The agent sees the screen and acts like a human, so it works even if the UI changes or you cannot rely on stable selectors. You can target any cloud VM with a real desktop, browser, or terminal. This removes the need to maintain a mapping of UI elements or mock APIs for every task. You simply describe the goal, and the agent figures out the steps.
Use /v1/runs to build autonomous agents that finish tasks on real desktops without brittle selectors. Get an API key at https://coasty.ai/developers and start building your own computer use agent.