Building an Autonomous Agent That Finishes a Task with /v1/runs
You just want an agent that opens an app, clicks around, and completes a task. You do not want to model UI selectors, maintain CSS selectors, or write fragile XPath. Coasty lets you submit a task to /v1/runs and the server drives a cloud desktop until success, failure, or cancellation. This endpoint is the simplest way to get started with a computer use agent that works like a human.
How /v1/runs works
POST /v1/runs accepts a task string and optional configuration. The server spins up a machine (POST /v1/machines), launches a desktop, and runs a Coasty agent using a computer use API. The agent steps through the machine, reading screens with vision and acting with clicks, keystrokes, and typing. Each agent step costs $0.05. The endpoint returns a run_id and initial status (queued). You can monitor the run with GET /v1/runs/{id} or stream events with GET /v1/runs/{id}/events. States include queued, running, awaiting_human, succeeded, failed, cancelled, timed_out. You can cancel or resume a run with POST /v1/runs/{id}/cancel and POST /v1/runs/{id}/resume.
#!/usr/bin/env bash
# 1. Set your API key from the environment
export COASTY_API_KEY="${COASTY_API_KEY}"
# 2. Create a task that the agent will complete
task="navigate to https://coasty.ai and click the 'Sign Up' button"
# 3. Submit a task run via /v1/runs
run_id=$(curl -s -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": null,
"task": "'"$task"'",
"cua_version": "v3",
"max_steps": 100,
"deadline_seconds": 600,
"on_awaiting_human": "pause"
}' | jq -r '.run_id')
# 4. Poll status until completion or failure
while true; do
status=$(curl -s -X GET https://coasty.ai/v1/runs/$run_id \
-H "X-API-Key: $COASTY_API_KEY" | jq -r '.status')
echo "Run $run_id status: $status"
if [[ "$status" == "succeeded" || "$status" == "failed" || "$status" == "cancelled" || "$status" == "timed_out" ]]; then
break
fi
sleep 2
done
echo "Task run $run_id finished with status: $status"
Key configuration options
- ●machine_id: null lets the server provision a new machine. You can reuse an ID if you have provisioned one.
- ●task: natural language description of what the agent should do. The agent uses a computer use API to reason about the screen.
- ●cua_version: either v3 (guided) or v4 (autonomous with a pass/fail verifier). Use v4 when you want the agent to self-validate.
- ●max_steps: maximum number of agent steps to take. Each step costs $0.05.
- ●deadline_seconds: time limit for the run. If exceeded, the run times out.
- ●on_awaiting_human: set to pause to stop on human interactions, fail to fail immediately, or cancel to halt the run.
Each agent step is billed $0.05 and the server drives a real desktop for you.
Where this beats brittle automation
With traditional automation you model selectors and maintain them when the UI changes. With a computer use API the agent sees the screen, reasons about the context, and acts like a human. This means you can automate new apps, complex flows, and even web interactions without writing brittle selectors. The /v1/runs endpoint abstracts away the machine, vision, and action loops so you can focus on the task description.
Submit a task to /v1/runs and let the server drive an agent to completion. Build workflows, integrate with webhooks, and use the MCP server to drive Coasty from Cursor or Claude Desktop. Get your API key at https://coasty.ai/developers and start automating real desktop tasks today.