Building an Autonomous Agent That Finishes a Task with /v1/runs
Most automation tools fail when an element moves, an ID changes, or a page loads asynchronously. They rely on brittle selectors and wait for fixed timeouts. The Coasty computer use API flips that model. You describe what you want the agent to do, POST /v1/runs, and the server provisions a real desktop, drives it like a human, and streams events until the task succeeds, fails, or needs human approval. You pay $0.05 per agent step, and you get a full event history via Server-Sent Events.
How /v1/runs works
The /v1/runs endpoint starts a task run on a provisioned machine. You send a JSON payload with at least machine_id and task. The server returns a run id and an initial status (queued). You then poll /v1/runs/{id} or stream events from /v1/runs/{id}/events. As the agent moves the mouse, clicks, and types, events stream back. When the agent reaches a terminal state (succeeded, failed, cancelled, timed_out), you get the final status and a summary. Your agent can also request human approval via the on_awaiting_human parameter, which can pause, fail, or cancel the run. The run steps are billed at $0.05 each. Use the cua_version field to specify 'v3' for basic autonomy or 'v4' for an autonomous mode with a pass/fail verifier. You can append custom instructions, set a max_steps limit, or provide a deadline_seconds to bound the run. A webhook_url lets you receive notifications of state changes outside the stream.
curl https://coasty.ai/v1/runs \
-X POST \
-H 'Authorization: Bearer $COASTY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"machine_id": "machine_abc123",
"task": "Open Chrome, navigate to https://example.com, and click the first link",
"cua_version": "v3",
"max_steps": 50,
"deadline_seconds": 300,
"on_awaiting_human": "pause",
"webhook_url": "https://your-server.com/webhook/coasty"
}'Key fields and options
- ●machine_id: the cloud VM the agent will drive.
- ●task: a natural language description of the end-to-end task.
- ●cua_version: 'v3' for basic autonomy, 'v4' for autonomous mode with a pass/fail verifier.
- ●max_steps: upper bound on the number of agent steps, each billed $0.05.
- ●deadline_seconds: maximum runtime for the run.
- ●on_awaiting_human: what to do when the agent needs human input (pause, fail, cancel).
- ●webhook_url: HTTPS endpoint to receive state-change notifications outside the SSE stream.
- ●system_prompt: optional system prompt to guide the agent's behavior (passed as part of the request).
- ●instructions: optional instructions appended to the base prompt for the agent.
POST /v1/runs with machine_id and task, then GET /v1/runs/{id}/events to stream the agent's actions until a terminal state.
Where this beats brittle automation
Traditional automation tools map IDs, classes, or text to elements and assume they stay stable. If a layout shifts or an ID changes, the tool breaks. With Coasty, the agent sees the real screen, interprets instructions, and moves the mouse, clicks, and types like a human. It handles dynamic content, missing IDs, or complex multi-step workflows without brittle selectors. You can also integrate Coasty with an MCP server from Cursor, Claude Desktop, or other MCP clients to orchestrate agents from your own tools. The server-side billing and state management let you focus on the task logic, not the low-level interactions.
You now know how to start an autonomous agent with POST /v1/runs, stream events, and handle human approval. The next step is to build a workflow that chains multiple runs, asserts outcomes, and retries on failure. Get your API key and start driving real desktops at https://coasty.ai/developers.