Stateful Sessions vs Stateless Predict: A Developer’s Guide to the Computer Use API
You are building a computer use agent that clicks, types, and navigates. The simplest path is a loop that sends a screenshot and an instruction to POST /v1/predict, then acts on the returned actions. But for long-running tasks, stateful sessions with POST /v1/sessions give you trajectory memory so the model remembers context across steps. Both endpoints use the same model, but they have different billing models and use cases.
How it works
The stateless endpoint POST /v1/predict ($0.05) takes a base64 screenshot, an instruction, and cua_version and returns an actions array and a status. You capture the screen, predict, act, then repeat until status is done. The stateful endpoint POST /v1/sessions ($0.10) creates a session, then POST /v1/sessions/{id}/predict ($0.04) per step. The session stores a trajectory memory, so the model sees previous captures and actions. Billing is $0.05 per agent step in both cases, but the predict call price differs: $0.05 per request for stateless, $0.04 per session predict call.
#!/usr/bin/env python3
import os
import base64
import requests
API_KEY = os.getenv("COASTY_API_KEY")
BASE = "https://coasty.ai/v1"
# Load a screenshot as base64
with open("screenshot.png", "rb") as f:
screenshot_b64 = base64.b64encode(f.read()).decode("utf-8")
# Stateless predict
resp = requests.post(
f"{BASE}/predict",
headers={"X-API-Key": API_KEY},
json={
"screenshot": screenshot_b64,
"instruction": "Click the Login button.",
"cua_version": "v3"
}
)
resp.raise_for_status()
data = resp.json()
print("Status:", data.get("status"))
print("Actions:", data.get("actions"))
# Stateful session example (create session first)
session_resp = requests.post(
f"{BASE}/sessions",
headers={"X-API-Key": API_KEY},
json={"cua_version": "v3"}
)
session_resp.raise_for_status()
session_id = session_resp.json()["id"]
print("Session ID:", session_id)
# Session predict
predict_resp = requests.post(
f"{BASE}/sessions/{session_id}/predict",
headers={"X-API-Key": API_KEY},
json={
"screenshot": screenshot_b64,
"instruction": "Click the Login button.",
"cua_version": "v3"
}
)
predict_resp.raise_for_status()
session_data = predict_resp.json()
print("Session status:", session_data.get("status"))
print("Session actions:", session_data.get("actions"))Stateless predict: when to use it
- ●Single-shot or short tasks where you do not need memory across steps.
- ●Simpler code: one endpoint, no session management.
- ●Price per request: $0.05, which may be cheaper if you rarely repeat captures.
- ●No trajectory memory, so the model must re-interpret the same visual context each loop.
Stateful sessions: when to use it
- ●Long-running workflows that need continuity (login, multi-step forms, navigation).
- ●Trajectory memory in POST /v1/sessions/{id}/predict lets the model see previous captures and actions.
- ●Session creation costs $0.10; each subsequent predict call is $0.04, which can be cheaper for many steps.
- ●Useful when you want to resume a session later or integrate with workflows and task runs.
For long-running tasks, prefer stateful sessions with trajectory memory. For simple one-off actions, stateless predict is enough.
Where this beats brittle automation
Traditional tools rely on selectors like XPath or CSS that break when UI changes. A computer use agent sees the screen, understands high-level intent, and acts like a human. Stateful sessions let the agent remember that it clicked a login button, entered credentials, and moved to a dashboard, so it does not repeat mistakes or lose context. This approach works across browsers, desktop apps, and terminals without brittle selectors.
Pick stateless predict for quick, single-step actions. Choose stateful sessions for workflows that need trajectory memory and continuity. Ready to build your own computer use agent? Get a key at https://coasty.ai/developers and start building.