Writing automated scripts for real desktops is tedious. You need to wait for windows to appear, handle dynamic IDs, and keep track of multiple steps. The /v1/runs endpoint gives you an autonomous computer use agent that connects to a cloud machine and performs tasks for you. It runs until it succeeds, fails, or times out. You just send a machine ID, a task, and optional guardrails. The server handles the loop, the screen capture, and the actions.
How the /v1/runs endpoint works
POST /v1/runs accepts a machine_id, a task string, and optional configuration. The server starts an agent on the specified machine. It captures the screen, interprets the instruction, and performs actions until the status is done. The server streams events via Server-Sent Events while the run is active. You can check status, cancel, or resume a run later. The agent is billed $0.05 per step. You can also pass a cua_version of v4 for an autonomous mode with an optional pass/fail verifier. The response includes the run ID, the current state, and any events. Use GET /v1/runs to list runs or GET /v1/runs/{id} to inspect a specific run. Use POST /v1/runs/{id}/cancel to stop it and POST /v1/runs/{id}/resume to restart it. The /v1/runs/{id}/events endpoint streams real-time updates.
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://coasty.ai, and click the pricing button",
"cua_version": "v3",
"max_steps": 200,
"deadline_seconds": 600,
"on_awaiting_human": "pause"
}'Key fields and configuration options
- machine_id: required. The ID of a machine provisioned via POST /v1/machines.
- task: required. A natural language instruction that the agent understands.
- cua_version: optional. Default is v3. Set to v4 for autonomous mode with a pass/fail verifier.
- instructions: optional. Appended to the base system prompt to guide the agent.
- system_prompt: optional. Custom system instructions for the agent.
- max_steps: optional. Maximum agent steps before the run times out internally.
- deadline_seconds: optional. Hard deadline for the entire run.
- on_awaiting_human: optional. Behavior when the agent needs human input. Options are pause, fail, or cancel.
- webhook_url: optional. URL to notify on run state changes.
- Billed $0.05 per agent step.
The run ID you receive after POST /v1/runs is your anchor for monitoring, canceling, and resuming the agent.
Why computer use beats brittle automation
Traditional automation relies on static selectors, XPath, or API calls. If a UI changes, the script breaks. A computer use agent sees the screen like a human. It understands context, handles dynamic elements, and can adapt its actions. The /v1/runs endpoint delegates the entire loop to a server. You do not need to implement capture, interpretation, or action synthesis. You just define the task and guardrails. This reduces maintenance and lets you focus on higher-level workflows and business logic. The agent also supports workflows via POST /v1/workflows, which let you compose multiple steps, conditions, and variables into a single DSL.
What to build next
Try a real task on a cloud machine. Schedule periodic jobs, perform data entry, or integrate with legacy applications that lack APIs. Use POST /v1/machines to provision a fresh environment for each run. Explore workflows to compose multiple agent steps into a single job. You can also drive Coasty from Cursor, Claude Desktop, or other tools via the MCP server. Start by getting your API key and a machine ID from the developer portal.
The /v1/runs endpoint gives you an autonomous agent that finishes tasks on real desktops. It handles the loop, the screen capture, and the actions for $0.05 per step. Get your API key at https://coasty.ai/developers and start building agents that work like humans, not scripts.
Want to see this in action?
View Case Studies