Building an Autonomous Agent That Finishes a Task with /v1/runs
You want an agent that can take a natural language task, open a browser, navigate to a site, fill out a form, and click submit without brittle selectors or hardcoded APIs. The /v1/runs endpoint is the simplest way to spin up a stateful task run that drives a real desktop, browser, or terminal to completion. You send a task and a machine ID, and the server sends back a run ID. You can poll the run or stream events to see the agent act like a human. The agent stops when it succeeds, fails, or reaches a deadline. This endpoint is ideal for ad-hoc tasks, one-off automations, or as the core of larger workflows.
How /v1/runs works
POST /v1/runs creates a task run. You must provide a machine_id to target a cloud VM with a desktop environment. You send a task string describing what to do. You can also pass instructions to append to the base prompt, a system_prompt to customize the agent, max_steps to limit iterations, deadline_seconds to enforce a timeout, and on_awaiting_human to decide what to do when the agent needs human input. The run returns an id and a status (queued or running). You then GET /v1/runs/{id} to check status, GET /v1/runs/{id}/events to stream progress, or POST /v1/runs/{id}/cancel or /resume to control the run. Billing is $0.05 per agent step.
#!/usr/bin/env bash
# BUILD AN AUTONOMOUS AGENT WITH /v1/runs
# Replace <your-machine-id> with a real machine ID from your Coasty account
COASTY_API_KEY="${COASTY_API_KEY}"
RUN_URL="https://coasty.ai/v1/runs"
# Create a task run
RESPONSE=$(curl -s -X POST "$RUN_URL" \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "<your-machine-id>",
"task": "Navigate to https://example.com, click the first link, and tell me the title of the page.",
"instructions": "Do not install anything. Use the browser provided."
}')
echo $RESPONSE
# Extract the run ID
RUN_ID=$(echo $RESPONSE | jq -r '.id')
echo "Run ID: $RUN_ID"
# Poll the run until it completes
while true; do
STATUS=$(curl -s -X GET "https://coasty.ai/v1/runs/$RUN_ID" \
-H "X-API-Key: $COASTY_API_KEY")
RUN_STATUS=$(echo $STATUS | jq -r '.status')
echo "Status: $RUN_STATUS"
if [[ "$RUN_STATUS" == "succeeded" ]] || \
[[ "$RUN_STATUS" == "failed" ]] || \
[[ "$RUN_STATUS" == "cancelled" ]] || \
[[ "$RUN_STATUS" == "timed_out" ]]; then
echo "Final status: $RUN_STATUS"
echo "Full response: $STATUS"
break
fi
sleep 2
doneKey parameters you will use
- ●machine_id: required, the cloud VM that hosts the desktop environment.
- ●task: required, a natural language description of what the agent should do.
- ●instructions: optional, extra context appended to the base prompt.
- ●system_prompt: optional, custom instructions for the agent.
- ●max_steps: optional, the maximum number of agent steps allowed.
- ●deadline_seconds: optional, a timeout for the run.
- ●on_awaiting_human: optional, 'pause', 'fail', or 'cancel' when human input is needed.
- ●webhook_url: optional, a URL to POST status updates to.
- ●Billed at $0.05 per agent step.
Use /v1/runs for ad-hoc tasks, then GET /v1/runs/{id}/events to stream progress and react to success or failure in real time.
Where this beats brittle automation
Selector-based automation relies on stable CSS classes, IDs, or XPath that can break when a UI changes. An autonomous computer use agent sees the screen like a human, interpreting text, buttons, and layout. It can handle nested menus, dynamic labels, and unexpected UI states. You do not need to maintain a fragile selector database. The agent uses vision and natural language reasoning to find the right element, click it, and complete the task. This is ideal for web scraping, form filling, UI testing, and any workflow that involves changing interfaces or complex user journeys.
Next steps
Now that you have a task runner, try building a workflow that chains multiple /v1/runs together using the /v1/workflows DSL. You can add retry logic, human approval steps, and parallel execution. You can also integrate with your existing CI/CD pipelines or schedule recurring tasks. To get started, generate a key at https://coasty.ai/developers, provision a machine, and send your first task to /v1/runs.