Build an Autonomous Agent That Finishes a Task With /v1/runs
You want an agent that opens a browser, logs into a service, fills out a form, and submits it. Traditional selectors get broken by UI updates, and CLI tools cannot click buttons that only appear visually. The /v1/runs endpoint gives you a stateful, server-driven agent that sees screens and acts like a human. You only send a task and a machine, and the API returns events and a final status.
How it works
You POST to /v1/runs with a machine_id, a task string, and optional parameters. The server spins up a cloud VM, launches an agent, and streams events back to your webhook_url. Each step the agent takes costs $0.05. You can poll for status with GET /v1/runs/{id} or stream events from GET /v1/runs/{id}/events. The agent proceeds until it reaches a terminal state like succeeded, failed, or cancelled.
curl -X POST https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "vm-12345",
"task": "Log into https://example.com/login, fill the email field with [email protected], the password field, and click the submit button.",
"cua_version": "v4",
"max_steps": 200,
"deadline_seconds": 300,
"on_awaiting_human": "pause",
"webhook_url": "https://your-server.com/callback"
}'Request fields and pricing
- ●machine_id: string, required. The ID of a provisioned cloud VM.
- ●task: string, required. Human-readable instructions for the agent.
- ●cua_version: string, optional. Default is "v3". Use "v4" for an autonomous agent with a pass/fail verifier.
- ●instructions: string, optional. Additional context appended to the task prompt.
- ●system_prompt: string, optional. Custom system instructions.
- ●max_steps: integer, optional. Maximum agent steps before the run cancels itself.
- ●deadline_seconds: integer, optional. Total time limit for the run.
- ●on_awaiting_human: string, optional. "pause", "fail", or "cancel" when the agent encounters a human prompt.
- ●webhook_url: string, optional. HTTPS endpoint to receive events.
- ●Billing: $0.05 per agent step.
In your webhook callback, read the event type from the payload and act on the agent state.
Where this beats brittle automation
Robotic process automation tools rely on XPath, CSS selectors, or hardcoded IDs. When the UI shifts, those selectors break and you must rewrite your scripts. A computer use agent reads the visual state of the screen and clicks, types, and scrolls like a human. It adapts to layout changes, dynamic content, and multi-step flows without selector gymnastics.
Next steps
- ●Provision a machine with POST /v1/machines and keep its ID.
- ●Create a webhook endpoint to handle queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out events.
- ●Handle on_awaiting_human by pausing the workflow or failing the run based on your policy.
You now have a pattern for shipping an autonomous computer use agent that finishes tasks on real desktops and browsers. Get your API key at https://coasty.ai/developers and start building with /v1/runs.