Build an Autonomous Agent That Finishes a Task with /v1/runs
Writing robust selectors for every click, input, and hover is brittle. You want an agent that looks at the screen, understands what to do, and clicks accordingly. The /v1/runs endpoint lets you submit a task and let the server drive a machine through steps. You only need to provide the machine ID, task description, and optional parameters. The agent runs autonomously until it succeeds, fails, or hits a configured limit. You can inspect the run state and watch events in real time.
How /v1/runs works
POST /v1/runs creates a task run and starts an agent on the specified machine. Required fields are machine_id and task. Both are strings. The body can include cua_version (default "v3", "v4" enables a pass/fail verifier), instructions (appended to the base prompt), system_prompt (optional), max_steps (max agent steps, default 10), deadline_seconds (default 600), on_awaiting_human (only for v4, options pause, fail, cancel), and webhook_url (optional). The server returns an id and the initial state (queued, running, etc). You then poll GET /v1/runs/{id} to see state changes. For live updates, GET /v1/runs/{id}/events streams Server-Sent Events; reconnect with Last-Event-ID.
#!/usr/bin/env bash
set -euo pipefail
export COASTY_API_KEY
RUN_URL="https://coasty.ai/v1/runs"
run_data() {
jq -n \
--arg machine_id "my-vm-123" \
--arg task "Navigate to https://example.com and take a screenshot of the page title." \
--arg cua_version "v3" \
--argjson max_steps 20 \
--argjson deadline_seconds 600 \
'{
machine_id: $machine_id,
task: $task,
cua_version: $cua_version,
max_steps: $max_steps,
deadline_seconds: $deadline_seconds
}'
}
# POST /v1/runs
run_id=$(curl -s -X POST "$RUN_URL" \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d "$(run_data)" \
| jq -r '.id')
echo "Created run: $run_id"
# Poll GET /v1/runs/{id}
while true; do
state=$(curl -s -X GET "$RUN_URL/$run_id" \
-H "Authorization: Bearer $COASTY_API_KEY" \
| jq -r '.state')
echo "Run state: $state"
if [[ "$state" == "succeeded" || "$state" == "failed" || "$state" == "cancelled" || "$state" == "timed_out" ]]; then
break
fi
sleep 2
done
echo "Run finished with state: $state"
# Optional: GET /v1/runs/{id}/events
# curl -s -N "$RUN_URL/$run_id/events" \
# -H "Authorization: Bearer $COASTY_API_KEY" \
# --header "Accept: text/event-stream"Key run parameters
- ●machine_id: The identifier of the cloud VM where the agent runs.
- ●task: The natural language instruction for the agent.
- ●cua_version: "v3" for the guided agent, "v4" for an autonomous agent with pass/fail verifier.
- ●instructions: Extra text added to the base prompt.
- ●system_prompt: Optional override of the system-level prompt.
- ●max_steps: Maximum number of agent steps (default 10).
- ●deadline_seconds: Timeout in seconds (default 600).
- ●on_awaiting_human: Only valid with v4, options pause, fail, cancel.
- ●webhook_url: Optional endpoint to receive run status changes.
- ●States: queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
POST /v1/runs creates the run, GET /v1/runs/{id} polls state, and GET /v1/runs/{id}/events streams real-time events.
Where this beats brittle automation
Traditional automation relies on stable selectors, IDs, classes, and XPath expressions. When designs change or layouts shift, those selectors break, causing flaky tests or user flows. The /v1/runs endpoint lets you describe intent in natural language. The agent sees the screen, reasons about it, and acts like a human. It can handle dynamic content, UI evolution, and subtle layout differences without you updating selectors. You pay $0.05 per agent step billed to your prepaid wallet. The endpoint also integrates with Coasty workflows, machine provisioning, and MCP clients, so you can chain runs and build multi-step workflows.
Next steps
Now that you can create and monitor runs, try provisioning a cloud machine with POST /v1/machines, then chain runs with POST /v1/workflows or ad-hoc inline workflows. Use GET /v1/runs/{id}/events to build dashboards or webhooks. Explore the MCP server to control Coasty from Cursor, Claude Desktop, or other MCP clients. Get your API key and start building autonomous agents at https://coasty.ai/developers.