You want an agent that can handle realistic desktop workflows, login, navigate apps, click buttons, and fill forms, not just HTTP API calls. The /v1/runs endpoint gives you that. You send a task, a machine ID, and optional constraints. The Coasty server runs an agent on a real desktop and streams events. The agent stops when it succeeds, fails, or hits a human approval, timeout, or budget limit. You get events for every step and final status.
How /v1/runs works
The core request POSTs to /v1/runs with these fields. You must provide machine_id and task. cua_version defaults to v3. You can append custom instructions to the base prompt with instructions. Set max_steps to cap iterations. Set deadline_seconds to enforce a hard timeout. You can pause when the agent waits for human approval with on_awaiting_human (pause, fail, or cancel). Provide a webhook_url to receive updates asynchronously. The server returns a run object with id, state, and metadata. You track progress with GET /v1/runs/{id} and events with GET /v1/runs/{id}/events (Server-Sent Events).
curl https://coasty.ai/v1/runs \ -H 'X-API-Key: $COASTY_API_KEY' \ -H 'Content-Type: application/json' \ -d '{
"machine_id": "machine_abc123",
"task": "Log in to Google and navigate to the "Settings" page",
"cua_version": "v3",
"instructions": "Use the browser to find the Settings link and click it.",
"max_steps": 100,
"deadline_seconds": 300,
"on_awaiting_human": "pause",
"webhook_url": "https://yourapp.com/webhooks/coasty"
}'Track and manage runs
After starting a run, you poll GET /v1/runs/{id} to read the latest state. States include queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out. The server streams events with GET /v1/runs/{id}/events. Use the Last-Event-ID header to reconnect after a disconnect. You can cancel an ongoing run with POST /v1/runs/{id}/cancel. You can resume a run that was paused for human approval with POST /v1/runs/{id}/resume. All task steps are billed $0.05 per agent step.
Key parameters you need
- machine_id: Cloud VM provisioned via POST /v1/machines
- task: Natural language description of what the agent must do
- cua_version: v3 for guided mode, v4 for autonomous with pass/fail verifier
- instructions: Custom steps appended to the base prompt
- max_steps: Hard cap on agent iterations to prevent runaway execution
- deadline_seconds: Maximum wall-clock time for the run
- on_awaiting_human: Action when the agent needs human input (pause/fail/cancel)
- webhook_url: URL for async updates and final results
- billing: $0.05 per agent step in Task Runs
POST /v1/runs is the single entry point for an autonomous agent that drives a real desktop until the task is done.
Where this beats brittle automation
Traditional automation relies on fixed selectors, DOM IDs, or HTTP endpoints that break when UI changes. Computer use agents see the screen like a human and act on it. They handle dynamic elements, overlays, and multi-step workflows. The agent uses vision and structured actions to click, type, and scroll. This lets you build agents that work across browsers, terminals, and desktop apps without brittle selectors. The server handles stateful trajectory memory, so the agent remembers context across steps. You get an autonomous workflow that adapts to the environment.
You now have a clear path to run autonomous agents on real desktops with /v1/runs. Start by provisioning a machine, send a task, and track events. Build workflows that log in, navigate apps, and complete multi-step tasks. Ready to build? Get your API key at https://coasty.ai/developers.
Want to see this in action?
View Case Studies