Build an Autonomous Agent That Finishes a Task with /v1/runs
You want an agent that can navigate a desktop, fill forms, click buttons, and finish a task end-to-end without you scripting every click. The /v1/runs endpoint lets you hand over control to a server-driven agent that watches the screen, plans actions, and reports back. This is perfect for tasks that need visual reasoning or are too brittle for pure selectors.
How /v1/runs works
Submit a POST request to https://coasty.ai/v1/runs with these fields. The payload is a JSON object. The endpoint returns an immediate run_id. You then poll GET /v1/runs/{id} or stream events with GET /v1/runs/{id}/events until the run finishes. The agent uses a cua_version of v3 by default or v4 for autonomous mode with a pass/fail verifier.
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "m-12345",
"task": "Open Chrome, go to https://example.com, and print the page title.",
"cua_version": "v3",
"max_steps": 20,
"deadline_seconds": 300,
"on_awaiting_human": "pause",
"webhook_url": "https://your-app.com/hooks/coasty"
}' | jq .Request fields explained
- ●machine_id: an existing cloud VM ID from /v1/machines
- ●task: natural language instruction for the agent
- ●cua_version: v3 for guided mode or v4 for autonomous with pass/fail verifier
- ●max_steps: maximum agent steps before timing out (default depends on model)
- ●deadline_seconds: seconds after which the run times out
- ●on_awaiting_human: pause, fail, or cancel when the agent needs human interaction
- ●webhook_url: receives final state and events via POST
- ●system_prompt: optional higher-level system instructions
- ●instructions: optional string appended to the base prompt for the agent
1 credit = $0.01. The agent is billed $0.05 per step during Task Runs. You control cost with max_steps and deadline_seconds.
Checking run status
Use GET /v1/runs/{id} to inspect the current state of the run. States include queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out. Use GET /v1/runs/{id}/events to stream updates in real time via Server-Sent Events. Include the Last-Event-ID header to reconnect after a disconnect.
Where this beats brittle automation
Traditional automation relies on stable selectors and hardcoded network calls. If a UI changes, the script breaks. A computer use agent watches the screen, understands context, and plans actions like a human. It can handle dynamic layouts, popups, and multi-step workflows without manual selector updates. This is especially powerful for web apps, desktop software, and any interface that changes over time.
You now have a pattern to build autonomous agents that finish tasks with /v1/runs. Try it out by provisioning a machine, starting a run, and monitoring events. Ready to build your own agents? Get an API key at https://coasty.ai/developers.