You want an agent that opens a browser, logs in, clicks around, and finishes a task without you writing fragile selectors or API mocks. The /v1/runs endpoint lets you push a task and let the Coasty server drive a live desktop, browser, or terminal to completion. You start a Task Run, stream its events, and handle states like awaiting_human. This guide shows you how to write a real request using the exact fields and pricing from the Coasty Computer Use API.
How /v1/runs works
POST /v1/runs starts an asynchronous Task Run on a provisioned machine. The request body includes machine_id, task, cua_version, optional instructions, system_prompt, max_steps, deadline_seconds, on_awaiting_human, and webhook_url. The server spawns an agent on that machine and bills you $0.05 per agent step. You can query the run status with GET /v1/runs and GET /v1/runs/{id}. The run emits events via GET /v1/runs/{id}/events (Server-Sent Events). States include queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out. Use on_awaiting_human to decide whether to pause, fail, or cancel when the agent needs human input.
#!/bin/bash
# Start a Task Run with /v1/runs
# Requires COASTY_API_KEY env var
API_KEY="${COASTY_API_KEY}"
BASE="https://coasty.ai/v1"
RUN_ID=$(curl -sS "https://api.openai.com/v1/engines/gpt-4o-mini/completions" \
-H "Authorization: Bearer ${COASTY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o-mini","prompt":"Generate a random 16-char hex machine_id"}' \
| jq -r '.choices[0].message.content')
# POST /v1/runs
RESPONSE=$(curl -sS "${BASE}/runs" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{
\"machine_id\": \"${RUN_ID}\",
\"task\": \"Open Firefox, go to https://coasty.ai, and click the 'developers' link in the header.\",
\"cua_version\": \"v3\",
\"instructions\": \"Use natural language to navigate.\",
\"system_prompt\": \"You are a helpful computer use agent on a desktop.\",
\"max_steps\": 20,
\"deadline_seconds\": 120,
\"on_awaiting_human\": \"pause\",
\"webhook_url\": \"https://your-server.coasty-events\"
}")
RUN_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "Task Run started: ${RUN_ID}"
echo "Poll status with: curl -sS '${BASE}/runs' -H 'X-API-Key: ${API_KEY}' | jq -r '.[] | select(.id=="${RUN_ID}").status'"
echo "Stream events with: curl -sS '${BASE}/runs/${RUN_ID}/events' -H 'X-API-Key: ${API_KEY}' --no-buffer"
Key fields and behaviors
- machine_id: selects the provisioned machine.
- task: natural-language goal for the agent.
- cua_version: v3 or v4 (v4 adds a pass/fail verifier).
- instructions: appends extra context to the base prompt.
- system_prompt: sets the agent's role and tone.
- max_steps: limits steps to prevent runaway loops.
- deadline_seconds: stops the run if it takes too long.
- on_awaiting_human: pause, fail, or cancel when human input is needed.
- webhook_url: optional HTTPS endpoint for event delivery.
- Statuses: queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
- Events: Server-Sent Events from /v1/runs/{id}/events; include Last-Event-ID for reconnection.
- Billing: $0.05 per agent step. Query runs with GET /v1/runs and GET /v1/runs/{id}.
- Cancel / resume: POST /v1/runs/{id}/cancel and POST /v1/runs/{id}/resume.
POST /v1/runs starts an asynchronous Task Run. You stream events from /v1/runs/{id}/events and handle states like awaiting_human.
Where this beats brittle automation
Selector-based automation relies on stable class names and IDs, which change on every version bump. The Coasty computer use API drives the real desktop, browser, and terminal. The agent sees the screen and clicks or types like a human, so UI changes do not break your flows. You also avoid mocking APIs for every endpoint. A single natural-language task can open a browser, fill forms, and click links without brittle selectors. Use cua_version v4 for a pass/fail verifier that checks if the task succeeded. If you need more control, use stateful sessions with /v1/sessions and predict steps, but for end-to-end workflows, /v1/runs is the simplest path.
What to build next
- Combine /v1/runs with /v1/workflows to sequence multi-step workflows.
- Use /v1/machines to provision machines for long-running agents.
- Connect via the MCP server to run agents from Cursor or Claude Desktop.
- Use /v1/sessions and /v1/predict for fine-grained stateful steps.
- Integrate webhooks to trigger downstream services on run completion.
A single POST /v1/runs call can start an agent that navigates a real browser and finishes your task. Use the Coasty computer use API today and get your key at https://coasty.ai/developers.
Want to see this in action?
View Case Studies