Most computer use agents start fresh on every screenshot. You send a base64 screenshot, an instruction, and get actions. If the task needs three passes at the same page, you repeat the screenshot and instruction each time. That works but adds cost and complexity. Stateful sessions give you a single session ID that holds the full trajectory. Each predict call adds to that history instead of replacing it.
How stateless predict works
Stateless predict is a POST to /v1/predict. You send a base64 screenshot, an instruction, and the cua_version. The API returns actions and a status. When status is done you stop. Each call is independent and does not store anything for later calls. This model is ideal for one‑shot tasks like "click this button once and stop".
curl https://coasty.ai/v1/predict \ -H "X-API-Key: $COASTY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "screenshot": "$(base64 -w 0 screenshot.png)", "instruction": "Click the submit button", "cua_version": "v3" }'How stateful sessions work
Stateful sessions use two endpoints. First POST /v1/sessions creates a session and returns an id. Then POST /v1/sessions/{id}/predict sends the next screenshot and instruction. The server stores the full trajectory (screenshots, instructions, actions, and execution state) keyed by the id. Each predict call appends to that history. This lets the agent remember previous steps, mouse positions, and waiting states across multiple calls. You still pay per predict but you avoid resending the whole history each time.
import os, base64, requests, json
api_key = os.getenv("COASTY_API_KEY")
url = "https://coasty.ai/v1"
# 1. Create a stateful session
session_resp = requests.post(
f"{url}/sessions",
headers={"X-API-Key": api_key, "Content-Type": "application/json"},
json={"cua_version": "v4"}
)
session_id = session_resp.json()["id"]
print(f"session_id={session_id}")
# 2. First predict call within the session
with open("screen1.png", "rb") as f:
screenshot = base64.b64encode(f.read()).decode()
predict_resp = requests.post(
f"{url}/sessions/{session_id}/predict",
headers={"X-API-Key": api_key, "Content-Type": "application/json"},
json={
"screenshot": screenshot,
"instruction": "Click the login link",
"cua_version": "v4"
}
)
print(json.dumps(predict_resp.json(), indent=2))
# 3. Second predict call adds to the trajectory
with open("screen2.png", "rb") as f:
screenshot = base64.b64encode(f.read()).decode()
predict_resp = requests.post(
f"{url}/sessions/{session_id}/predict",
headers={"X-API-Key": api_key, "Content-Type": "application/json"},
json={
"screenshot": screenshot,
"instruction": "Enter email and submit",
"cua_version": "v4"
}
)
print(json.dumps(predict_resp.json(), indent=2))Cost comparison
- Stateless predict costs $0.05 per request and stores no history.
- Stateful sessions cost $0.04 per predict call and $0.10 to create the session.
- Task runs bill $0.05 per agent step and are useful for end‑to‑end workflows.
Use sessions for multi‑step interactions. Reuse the same id on each predict call to keep the full trajectory in memory.
Where this beats brittle automation
Many automation tools rely on brittle selectors. A button moves, an ID changes, or the layout shifts, and the selector breaks. A computer use agent sees the screen like a human and clicks based on visual context. Stateful sessions let that agent remember the previous action and the current state. It can wait, retry, and navigate through multi‑step flows without re‑describing everything each time. This makes workflows more robust and easier to maintain.
Start with stateless predict for simple tasks. Switch to stateful sessions when you need the agent to remember steps across multiple interactions. You can also use task runs to drive an agent through an entire workflow and pause for human approval. Get a key at https://coasty.ai/developers to begin building with the computer use API.
Want to see this in action?
View Case Studies