Stateful Sessions vs Stateless Predict in the Computer Use API
You want an agent that can fill a multi-step form, navigate a web app, and remember what it did a few clicks ago. One-shot prediction (POST /v1/predict) gives you a single screenshot and instruction, then returns actions. It does not retain state between calls. For long-running workflows, this forces you to send the entire history each time, which burns credits and adds latency. Stateful sessions (POST /v1/sessions, then POST /v1/sessions/{id}/predict) store the trajectory on the server, cutting per-step cost and letting the model see recent actions as context.
How stateless predict works
Stateless predict treats each call as an isolated task. You send a base64 screenshot of the current screen, an instruction, and the cua_version. The model returns actions and a status. When status is done, the run is finished. The endpoint is simple but stateless. You pay $0.05 per predict. You must include the full instruction and any context you need the model to know. The response is a JSON object with actions and a status field. No session ID is returned, so you cannot resume or inspect history.
How stateful sessions work
Stateful sessions give you trajectory memory. First, create a session with POST /v1/sessions. The request body requires machine_id, cua_version, and optionally instructions. The response includes an id. Then, POST /v1/sessions/{id}/predict with the same screenshot, instruction, and cua_version, but no machine_id. The model sees the session history and can act on recent state. The per-step price is $0.04. You can cancel (POST /v1/runs/{id}/cancel) or resume (POST /v1/runs/{id}/resume) a session. GET /v1/runs/{id}/events streams events as Server-Sent Events, useful for real-time UI updates.
#!/bin/bash
# Create a stateless session (one-shot predict)
COASTY_API_KEY="${COASTY_API_KEY}"
BASE_URL="https://coasty.ai/v1"
# Example screenshot data (base64 encoded PNG placeholder)
SCREENSHOT_BASE64="$({ base64 /dev/zero 2>/dev/null || base64 -i /dev/zero; })"
export INSTRUCTION='Click the login button'
export CUAVERSION='v3'
curl -s "$BASE_URL/predict" \
-H "X-API-Key: $COASTY_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"screenshot": "'"$SCREENSHOT_BASE64"'",
"instruction": "'$INSTRUCTION'",
"cua_version": "'$CUAVERSION'"
}' | jq '.'#!/usr/bin/env python3
# Stateful session example
import base64
import json
import os
import requests
COASTY_API_KEY = os.getenv('COASTY_API_KEY')
BASE_URL = 'https://coasty.ai/v1'
# Replace with a real base64 screenshot (PNG) of your target window
SCREENSHOT_BASE64 = open('screenshot.png', 'rb').read().decode('utf-8')
# Create a stateful session
session_resp = requests.post(
f'{BASE_URL}/sessions',
headers={'X-API-Key': COASTY_API_KEY, 'Content-Type': 'application/json'},
json={
'machine_id': 'your-machine-id',
'cua_version': 'v3'
}
)
session_resp.raise_for_status()
session_id = session_resp.json()['id']
print('Created session:', session_id)
# Run a predict call within the session
predict_resp = requests.post(
f'{BASE_URL}/sessions/{session_id}/predict',
headers={'X-API-Key': COASTY_API_KEY, 'Content-Type': 'application/json'},
json={
'screenshot': SCREENSHOT_BASE64,
'instruction': 'Click the login button',
'cua_version': 'v3'
}
)
predict_resp.raise_for_status()
result = predict_resp.json()
print('Predict result:', json.dumps(result, indent=2))Cost and billing differences
- ●Stateless predict: $0.05 per request
- ●Stateful session predict: $0.04 per request inside a session
- ●Task runs (POST /v1/runs): $0.05 per agent step
- ●Workflows (POST /v1/workflows): $0.05 per task step
- ●Grounding (POST /v1/ground): $0.03 per call
- ●Parse (POST /v1/parse): Free
- ●Vision endpoints (POST /v1/predict, /v1/sessions/{id}/predict) use the cua_version field to select the model (v3 or v4).
Use stateful sessions ($0.04) for long-running workflows, and one-shot predict ($0.05) for quick, isolated tasks.
Where this beats brittle automation
Traditional desktop automation relies on brittle selectors such as XPath or CSS IDs that break when screens change or UIs update. With computer use, the agent takes a screenshot, uses vision to locate elements relative to the current layout, and clicks or types. A stateful session lets the model see previous actions and context, so it can handle multi-step flows without you manually stitching together fragile selectors. This approach aligns with the OSWorld benchmark (85.6% on our in-house model, 82.81% independently verified on the official leaderboard).
Stateful sessions give your computer use agents trajectory memory and lower per-step cost. Use POST /v1/sessions + POST /v1/sessions/{id}/predict for multi-step workflows, and POST /v1/predict for quick one-shot tasks. Get your API key at https://coasty.ai/developers and start building agents that see the screen and act like humans.