You want an agent that does not just call APIs but actually clicks, types, and navigates. The /v1/runs endpoint is the simplest way to spin up a computer use agent that runs to completion. It takes a task description, a machine, and a few options, then drives a real desktop or browser until the state is done, failed, or cancelled. You pay $0.05 per agent step. No more brittle selectors. The server does the heavy lifting.
How it works
A task run is a single request that starts an agent on a machine. You provide machine_id, task, and cua_version (default v3, v4 adds a pass/fail verifier). Optional fields let you control behavior, such as max_steps, deadline_seconds, instructions, system_prompt, and on_awaiting_human. The agent captures the screen, predicts actions using a vision model, and executes them. As the run progresses, events stream to you. The run finishes in one of these states queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
curl https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "aws-eu-west-1-123456789012",
"task": "Open Chrome, go to https://example.com, and take a screenshot of the homepage.",
"cua_version": "v3",
"max_steps": 100,
"deadline_seconds": 300
}'The request payload
- machine_id: A cloud VM you provision via POST /v1/machines
- task: The English instruction that the agent receives
- cua_version: v3 (default) or v4 (autonomous with a pass/fail verifier)
- max_steps: Upper bound on the number of agent steps to prevent runaway runs
- deadline_seconds: Hard timeout for the run; the agent stops if this expires
- instructions: Optional text appended to the base prompt for fine-tuning behavior
- system_prompt: Optional override for the system prompt sent to the vision model
- on_awaiting_human: Action when the agent encounters a human approval step
A task run starts in the queued state. Use GET /v1/runs to list runs and GET /v1/runs/{id} to inspect a specific run.
Where this beats brittle automation
Traditional automation depends on stable selectors, XPath, CSS, and DOM IDs that break when the UI changes. A computer use agent sees the screen like a human and predicts actions based on instruction and context. It can handle dynamic elements, pop-ups, and layout shifts. You describe what you want, and the agent figures out how to click, type, and navigate. This works for real desktops, browsers, and terminals, not just mocked APIs.
Managing a run
- GET /v1/runs lists all runs for your key
- GET /v1/runs/{id} returns the current state and metadata for a specific run
- POST /v1/runs/{id}/cancel stops a run that is queued or running
- POST /v1/runs/{id}/resume restarts a run that was paused or cancelled (if supported)
- GET /v1/runs/{id}/events streams Server-Sent Events for live progress
Start with a single task run from /v1/runs to get a working computer use agent on a machine. Explore workflows with /v1/workflows if you need multi-step pipelines. Get a key at https://coasty.ai/developers and start building agents that drive real desktops and browsers to completion.
Want to see this in action?
View Case Studies