Build an Autonomous Agent That Finishes a Task with POST /v1/runs
You need to automate a multi-step workflow, create a user, open a browser, fill a form, and verify the result. Traditional automation tools struggle with dynamic websites, missing elements, and flaky selectors. The /v1/runs endpoint lets you spin up a real computer use agent that sees the screen, clicks, types, and completes the entire task from start to finish. No brittle selectors, just a human-like agent driven by a single API call.
How it works
POST /v1/runs provisions a cloud machine and launches an agent with a given task and instructions. The request payload includes machine_id, task, cua_version, and optional fields such as instructions, system_prompt, max_steps, deadline_seconds, on_awaiting_human, and webhook_url. The server returns a run_id. You poll GET /v1/runs/{id} to track state: queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out. Each agent step costs $0.05. When the agent finishes, the final state indicates success or failure. You can cancel or resume the run via POST /v1/runs/{id}/cancel and POST /v1/runs/{id}/resume.
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "machine_abc123",
"task": "Create a new user account on https://example.com/signup",
"cua_version": "v4",
"instructions": "Use a realistic email and password based on the current date.",
"max_steps": 100,
"deadline_seconds": 600,
"on_awaiting_human": "pause",
"webhook_url": "https://your-server.coasty-webhook"
}'Track your run
- ●GET /v1/runs returns a list of runs and their IDs.
- ●GET /v1/runs/{id} returns the current state and any error details.
- ●GET /v1/runs/{id}/events streams Server-Sent Events that log steps, clicks, and messages.
- ●Reconnect with the Last-Event-ID header to resume reading the stream.
- ●State transitions: queued → running → awaiting_human → succeeded/failed/cancelled/timed_out.
Remember: each agent step is billed $0.05. Use max_steps and deadline_seconds to keep your workflow predictable and within budget.
Cancel or resume a run
- ●POST /v1/runs/{id}/cancel halts the agent immediately.
- ●POST /v1/runs/{id}/resume continues from the last known state.
- ●Cancel is useful when you reach a human approval step set to pause, hit a rate limit, or detect an unrecoverable error.
Where this beats brittle automation
API-only automation relies on stable endpoints and exhaustive selectors. When UI changes, new classes, hidden fields, or layout shifts, scripts break. The /v1/runs endpoint drives a real desktop agent that sees exactly what the user sees. It clicks buttons by inspecting the screen, types into input fields, scrolls where needed, and follows the visual flow. This makes your workflows resilient to UI changes, layout shifts, and non-standard workflows that are hard to encode in static selectors.
Start building autonomous desktop agents with the /v1/runs endpoint. Create a task, set your machine_id, pick your cua_version, and let the agent complete the work for you. Get your API key at https://coasty.ai/developers and see how the computer use API can replace fragile automation scripts.