Build an Autonomous Agent That Finishes a Task With /v1/runs
You want an agent that opens an app, fills in a form, clicks a button, and then reports back. Traditional tools rely on brittle selectors, static APIs, or fragile element IDs. The /v1/runs endpoint gives you a task driver that sees the screen, acts like a human, and completes the work for you.
How /v1/runs works
POST /v1/runs starts a task run on a cloud machine. The server launches a real desktop or browser and drives it until the task finishes. The request body accepts machine_id, task, cua_version (default v3, v4 adds an automatic pass/fail verifier), instructions (appended to the base prompt), system_prompt, max_steps, deadline_seconds, on_awaiting_human, and webhook_url. The response returns a run ID that you can query and stream for progress. Each agent step costs $0.05. The run moves through queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out states. You can cancel or resume a run using POST /v1/runs/{id}/cancel and POST /v1/runs/{id}/resume. Events are streamed via GET /v1/runs/{id}/events using Server-Sent Events with Last-Event-ID for reconnection.
curl -X POST https://coasty.ai/v1/runs \
-H 'X-API-Key: $COASTY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"machine_id": "m-abc123",
"task": "Open Chrome, go to https://example.com, and take a screenshot",
"cua_version": "v3",
"max_steps": 50,
"deadline_seconds": 300,
"on_awaiting_human": "pause"
}'Key parameters and behaviors
- ●machine_id: the cloud VM the agent will drive (provision with POST /v1/machines).
- ●task: the natural language instruction the agent follows.
- ●cua_version: use "v3" for guided control or "v4" for autonomous mode with an automatic pass/fail verifier.
- ●instructions: additional context appended to the base prompt for the agent.
- ●system_prompt: optional overrides for agent behavior (for example, strict error handling).
- ●max_steps: the maximum number of agent steps before the run stops (billing $0.05 per step).
- ●deadline_seconds: the timeout for the entire run, including waiting for human approvals.
- ●on_awaiting_human: choose "pause" to stop the run, "fail" to mark it failed, or "cancel" to abort.
- ●webhook_url: a URL the server calls when the run reaches a terminal state (succeeded, failed, cancelled, timed_out).
- ●Events: GET /v1/runs/{id}/events streams progress as Server-Sent Events; reconnect with Last-Event-ID.
Each agent step is billed $0.05, which makes the /v1/runs endpoint a pay-per-task model rather than an hourly compute subscription.
Where this beats brittle automation
Traditional tools use fixed selectors or element IDs that break when the UI changes. The Coasty computer use agent sees the actual screen, understands context, and adapts its actions. It can handle dynamic layouts, missing IDs, or unexpected states. This makes it ideal for workflows that require navigating complex apps, filling forms with dynamic fields, or handling error dialogs. The agent works in real browsers, terminals, and desktop environments, not just within an API sandbox.
Start with a simple task run using /v1/runs. Add human approvals for sensitive actions, use the events stream for real-time feedback, and explore workflows for multi-step processes. Get a key at https://coasty.ai/developers and build your first autonomous task runner.