Build an Autonomous Agent That Finishes a Task with /v1/runs
You need an agent that can open a browser, log in, fill a form, and click a button without hard selectors or brittle APIs. The /v1/runs endpoint in the Coasty computer use API lets you submit a task description and a machine_id. Coasty spawns an agent on that machine, captures the screen, plans actions, and executes them until the task succeeds, fails, or hits a guard. You get a single run ID and a state machine to track progress.
How /v1/runs works
The flow starts with a POST to /v1/runs. You provide a machine_id that must already exist in your fleet. The request body includes task and cua_version (default 'v3', 'v4' adds autonomous pass/fail verification). Optional fields are instructions (appended to the base prompt), system_prompt, max_steps, deadline_seconds, on_awaiting_human (pause/fail/cancel), and webhook_url. Coasty returns a run_id, status (queued, running, awaiting_human, succeeded, failed, cancelled, timed_out), and a few metadata fields. You can poll GET /v1/runs/{id} or stream events with GET /v1/runs/{id}/events. Billing is $0.05 per agent step.
#!/bin/bash
# Create a run that completes a task on a cloud machine
COASTY_API_KEY="${COASTY_API_KEY}"
BASE_URL="https://coasty.ai/v1"
# Example: Task to log into a demo site and click a button
TASK='Open https://example.com/login, enter username and password, and click the submit button.'
# Use an existing machine_id from your fleet
MACHINE_ID="mch_1234567890abcdef"
# Optional: instructions appended to the system prompt
INSTRUCTIONS='Back up only critical states. Abort if login fails.'
# Optional: expected pass/fail verifier (v4)
CUA_VERSION="v4"
# Optional: max steps and deadline
MAX_STEPS=50
timeout_seconds=300
# Optional: webhook for async callbacks
WEBHOOK_URL="https://your-app.com/webhook/coasty"
# Optional: what to do when agent asks for human approval
ON_AWAITING_HUMAN="pause"
# Build the JSON payload
PAYLOAD=$(cat <<EOF
{
"machine_id": "$MACHINE_ID",
"task": "$TASK",
"cua_version": "$CUA_VERSION",
"instructions": "$INSTRUCTIONS",
"max_steps": $MAX_STEPS,
"deadline_seconds": $timeout_seconds,
"on_awaiting_human": "$ON_AWAITING_HUMAN",
"webhook_url": "$WEBHOOK_URL"
}
EOF
)
# Create the run
RUN_ID=$(curl -s -X POST "$BASE_URL/runs" \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d "$PAYLOAD" | jq -r '.run_id')
echo "Run created: $RUN_ID"
# Poll status
while true; do
STATUS=$(curl -s -X GET "$BASE_URL/runs/$RUN_ID" \
-H "Authorization: Bearer $COASTY_API_KEY" | jq -r '.status')
echo "Current status: $STATUS"
if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ] || [ "$STATUS" = "timed_out" ]; then
break
fi
sleep 2
done
# Exit with non-zero if failed
echo "Final status: $STATUS"
exit 0Real-world use cases for /v1/runs
- ●CI/CD pipelines: run smoke tests on a real desktop or browser without headless drivers.
- ●Data entry bots: fill forms in legacy apps that expose no APIs.
- ●Browser workflows: navigate multi-step flows that require cookies or CAPTCHA handling.
- ●Incident response: open dashboards, inspect logs, and restart services on a remote machine.
- ●Team sprint demos: launch a demo environment, record a short video, and tear it down.
The one line to remember: POST /v1/runs with task, machine_id, cua_version, and any guards you need, then poll GET /v1/runs/{id} until status is not running.
Where this beats brittle automation
Hard selectors break when UI changes. APIs are incomplete or undocumented. The Coasty computer use agent sees the screen, understands natural language instructions, and clicks, types, and drags like a human. It handles layout shifts, new buttons, and minor variations. You describe what you want in plain language, not a brittle XPath or CSS selector. This is ideal for legacy apps, browser-based workflows, and any environment where you cannot guarantee a stable selector or API endpoint.
Next steps
- ●Provision a machine with POST /v1/machines and use its machine_id in a run.
- ●Stream events with GET /v1/runs/{id}/events for real-time logs and telemetry.
- ●Create workflows with POST /v1/workflows to compose multiple runs and conditionals.
- ●Integrate with MCP servers to drive Coasty from Cursor, Claude Desktop, or other clients.
- ●Add webhook callbacks with HMAC signature (header Coasty-Signature: t=unix,v1=hex).
You now have a concrete, production-ready flow for building an autonomous agent that finishes a task with /v1/runs. Start with a simple task on a pre-provisioned machine, then layer on workflows, events, and MCP integrations. Get your API key and start automating at https://coasty.ai/developers.