Build an Autonomous Agent That Finishes a Task with /v1/runs
Most automation is brittle. You hardcode selectors, wait for fixed delays, and crash when the UI changes. The Coasty computer use API flips that model. Instead of writing selectors, you give the agent a goal and let it see the screen, reason, and act like a human. The /v1/runs endpoint is the entry point: it provisions a cloud machine, starts an agent, and drives it to completion. You set the task, the behavior, and the constraints. The server handles the path, you handle the webhook.
How /v1/runs works
POST /v1/runs creates a task run that the server drives autonomously. You provide a machine_id so the agent has a real desktop, browser, or terminal. The task is a freeform goal (e.g., 'Create a new Notion note and save it'). You can optionally append instructions to the base prompt, supply a custom system_prompt, set max_steps (default is not explicitly defined but you control concurrency), and deadline_seconds to prevent infinite loops. on_awaiting_human lets you decide what happens when the agent needs human input: pause, fail, or cancel. You can also supply a webhook_url so your backend receives progress events in real time. The run state moves through queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out. You can poll GET /v1/runs/{id} or stream events with GET /v1/runs/{id}/events (Server-Sent Events). If you need to stop early, POST /v1/runs/{id}/cancel. If you want to resume, POST /v1/runs/{id}/resume. Billing is $0.05 per agent step and 1 credit = $0.01 USD. All requests use the base URL https://coasty.ai/v1 and an Authorization header with your API key.
#!/usr/bin/env bash
# Create an autonomous agent run that installs a Python package.
export COASTY_API_KEY="${COASTY_API_KEY}"
# Example machine_id from your dashboard.
machine_id="m12345"
curl -sS https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "'"$machine_id"'",
"task": "Install the requests library using pip in a fresh Python 3.11 environment, then run python -c \"import requests; print(requests.__version__)\" and verify the output matches 2.x"
}' | jq .Key parameters you control
- ●machine_id: the cloud VM where the agent runs
- ●task: the freeform goal you want the agent to achieve
- ●instructions: optional text appended to the base prompt
- ●system_prompt: optional system-level instructions
- ●max_steps: maximum agent actions before the run halts
- ●deadline_seconds: optional timeout, after which the run times out
- ●on_awaiting_human: pause, fail, or cancel when the agent needs human input
- ●webhook_url: endpoint that receives Server-Sent Events as the run progresses
- ●cua_version: defaults to v3, v4 enables autonomous pass/fail verification
Remember: the server drives the agent step by step. You control the goal, the constraints, and the outcome. Billable actions are $0.05 per agent step.
Where this beats brittle automation
Selector-based automation assumes a DOM or UI layout that never changes. Coasty agents see the screen, parse natural text, and click based on what is visible. They handle layout shifts, missing classes, and dynamic content the same way a human does. Because agents run on real cloud VMs with full OS and browser access, you can automate desktop apps, terminals, and complex workflows without mocking. You pay only for the steps the agent actually takes. You can also integrate with workflows using task, assert, if, loop, parallel, and human_approval steps to compose multi-step pipelines. If an agent gets stuck, you can cancel or resume a run. The MCP server lets you drive Coasty from Cursor, Claude Desktop, or any MCP-compatible client. No more fragile selectors. No more brittle waits. Just goals and outcomes.
You now have a complete picture of how the /v1/runs endpoint turns a goal into a running agent on a real machine. Use GET /v1/runs to list runs, GET /v1/runs/{id} to inspect status, GET /v1/runs/{id}/events to stream progress, POST /v1/runs/{id}/cancel to stop early, and POST /v1/runs/{id}/resume to continue. Build multi-step workflows, integrate with your CI/CD, and scale autonomous task completion. Get your API key at https://coasty.ai/developers and start building agents that finish tasks.