Stateful Sessions vs Stateless Predict in the Computer Use API
When you automate a desktop or browser with a computer use agent, the first screen capture and instruction are just one step. Real workflows often need to scroll, fill forms across multiple pages, or wait for dynamic content to appear. Stateless predict sends a fresh screenshot and instruction each time. Stateful sessions keep a trajectory in memory so the model can see what it has already done. This post explains the real endpoints, request bodies, and pricing for both approaches and shows a working Python example.
Stateless predict: one-shot capture and act
- ●Endpoint: POST /v1/predict
- ●Request fields: base64 screenshot, instruction, cua_version (default v3)
- ●Response fields: actions list, status (done, running)
- ●Billed $0.05 per predict call
- ●No memory of previous steps, you must loop capture and predict yourself
Stateful sessions: persistent trajectory
- ●First call: POST /v1/sessions creates a session with a JSON object body
- ●Session fields: machine_id (required), cua_version (default v3), optional instructions
- ●Response: session id and initial status
- ●Later calls: POST /v1/sessions/{id}/predict with screenshot, instruction, cua_version
- ●Model sees full trajectory history and can act on it
- ●Billed $0.04 per stateful predict, plus $0.10 for the initial session creation
import base64
import os
import requests
COASTY_API_KEY = os.environ.get("COASTY_API_KEY")
# Stateless predict example
# 1. Encode a screenshot to base64 (you replace with your real capture)
screenshot_b64 = base64.b64encode(open("screenshot.png", "rb").read()).decode("utf-8")
url_predict = "https://coasty.ai/v1/predict"
headers = {
"X-API-Key": COASTY_API_KEY,
"Content-Type": "application/json"
}
body = {
"screenshot": screenshot_b64,
"instruction": "Click the first button named Submit",
"cua_version": "v3"
}
resp = requests.post(url_predict, json=body, headers=headers)
resp.raise_for_status()
result = resp.json()
print("actions:", result["actions"])
print("status:", result["status"])
# Stateful sessions example
# 1. Create a session
url_sessions = "https://coasty.ai/v1/sessions"
body_session = {
"machine_id": "your-cloud-machine-id",
"cua_version": "v3"
}
resp_session = requests.post(url_sessions, json=body_session, headers=headers)
resp_session.raise_for_status()
session = resp_session.json()
session_id = session["id"]
print("session_id:", session_id)
# 2. Use the session in a loop
while True:
screenshot_b64 = base64.b64encode(open("screenshot.png", "rb").read()).decode("utf-8")
url_step = f"https://coasty.ai/v1/sessions/{session_id}/predict"
body_step = {
"screenshot": screenshot_b64,
"instruction": "Scroll down to load more results",
"cua_version": "v3"
}
resp_step = requests.post(url_step, json=body_step, headers=headers)
resp_step.raise_for_status()
step = resp_step.json()
print("actions:", step["actions"])
if step["status"] == "done":
break
# Stateful predict costs $0.04 per call. Session creation costs $0.10.Use stateful sessions when your workflow crosses multiple steps, waits, or needs context. Use stateless predict when you run a one-shot task in isolation.
Where this beats brittle automation
Stateless predict works fine for a single click or a tiny script. But real apps change layouts, drop elements, or require form filling across pages. Stateful sessions let the model see the full trajectory history, so it can handle layout shifts, missing elements, or missing context without you wiring brittle selectors or re-scanning the whole DOM. This is the core advantage of a computer use agent: it observes the screen and acts like a human. Sessions make that observation continuous and persistent, not a fresh snapshot every time.
Choose stateful sessions for multi-step workflows that need memory across captures. Choose stateless predict for isolated, one-shot tasks. Both endpoints live under the Coasty computer use API at https://coasty.ai/docs. Get your API key and start building at https://coasty.ai/developers.