Build an Autonomous Agent That Finishes a Task with /v1/runs
Most desktop automation relies on brittle selectors or manual API integration. You end up maintaining XPath, class names, and fragile state checks. The /v1/runs endpoint changes that by letting you describe a task in natural language and letting the server drive an actual computer to completion. The agent sees the screen, interprets visual cues, and clicks, types, and navigates just like a human. This tutorial shows how to launch an autonomous agent with a single POST request and handle its lifecycle.
How /v1/runs works
To start an autonomous task run, you POST to /v1/runs with a JSON body. The endpoint provisions a cloud machine, launches the agent, and begins executing your task. The request fields that matter are machine_id (a cloud VM you provision separately), task (the objective in natural language), cua_version (v3 or v4), max_steps, deadline_seconds, and on_awaiting_human. The agent runs on the real desktop, browser, or terminal, not just on API calls. You poll the run status with GET /v1/runs/{id} or stream events with GET /v1/runs/{id}/events. When the run succeeds, the agent has finished the task. If it fails, timed out, or needs human approval, you can cancel or resume with the appropriate endpoints.
#!/usr/bin/env bash
set -e
COASTY_API_KEY="${COASTY_API_KEY:?COASTY_API_KEY is required}"
BASE_URL="https://coasty.ai/v1"
# 1. Create a task run (autonomous agent) using /v1/runs
RUN_RESPONSE=$(curl -s -X POST "$BASE_URL/runs" \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "your-provisioned-machine-id",
"task": "open https://example.com and print the page title",
"cua_version": "v3",
"max_steps": 50,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}')
RUN_ID=$(echo "$RUN_RESPONSE" | jq -r '.id')
echo "Run ID: $RUN_ID"
# 2. Poll status until done or failure
while true; do
STATUS=$(curl -s -w "\n%{http_code}" "$BASE_URL/runs/$RUN_ID" \
-H "Authorization: Bearer $COASTY_API_KEY" | jq -r '.state')
HTTP_CODE=$(curl -s -w "\n%{http_code}" "$BASE_URL/runs/$RUN_ID" \
-H "Authorization: Bearer $COASTY_API_KEY" | tail -n1)
if [ "$STATUS" = "succeeded" ]; then
echo "Task succeeded"
break
elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "timed_out" ]; then
echo "Task failed or timed out"
break
else
echo "Status: $STATUS"
sleep 5
fi
doneKey request fields
- ●machine_id: the cloud VM where the agent runs.
- ●task: the concrete objective in natural language.
- ●cua_version: v3 (guided) or v4 (autonomous with pass/fail verifier).
- ●max_steps: maximum agent steps before the run fails.
- ●deadline_seconds: how long the run can live.
- ●on_awaiting_human: pause the run, fail it, or cancel when the agent needs human approval.
Use GET /v1/runs/{id}/events to stream progress and reconnect with Last-Event-ID.
Where this beats brittle automation
Traditional automation needs you to hardcode selectors, maintain mappings for every UI change, and build fragile state machines. The /v1/runs endpoint lets you describe what you want to accomplish without worrying about the underlying UI. The agent sees the screen, interprets visual cues, and clicks, types, and navigates like a human. This means you can adapt to layout shifts, dynamic content, and unexpected elements without rewriting selectors. You only pay $0.05 per agent step, making it cost-effective for exploratory and multi-step workflows.
You now have a working pattern for launching and managing autonomous agents with /v1/runs. Use the events stream to integrate with your monitoring dashboards, and combine runs with workflows for multi-step pipelines. Get your API key and start building at https://coasty.ai/developers.