API reference
Runs
Give an agent a task in plain language and follow every step it takes.
A run gives a task to an agent that drives a session until the task is done. The agent uses the same operations as the HTTP drive endpoints and the MCP tools. Every step is recorded as an event, and you can watch the events arrive next to the session's live view.
The run object
Start, get, list and cancel return this object.
Fields
- idstring
The run ID.
- statusstring
queued,running,succeeded,failedorcancelled. - taskstring
The task the run was started with.
- session_idstring
The session the agent drives.
- live_view_urlstring
Only on create. Get a new one with Create a connect token.
- modelstring
The model the agent runs on.
- stepsint
Browser tool calls made so far. The call that hands in the result is not counted.
- max_stepsint
The step limit the run was started with.
- resultstring, object or null
nulluntil the run succeeds. A string, or a value that matchesresult_schemawhen one was given. - errorobject or null
null, orcodeandmessagewhen the runfailed. The codes are under Errors. - usageobject
Tokens summed over the model calls of the run.
input_tokensincludes cached tokens.- input_tokensint
- output_tokensint
- created_attimestamp
When the run was created.
- started_attimestamp or null
When the agent started.
nullwhile the run isqueued. - ended_attimestamp or null
When the run ended.
nulluntil then.
{
"id": "run_5d1c0e7a9b3f4a6c8e2d1f0b7a9c3e5d",
"status": "running",
"task": "Get the top 3 titles on news.ycombinator.com",
"session_id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"model": "claude-opus-5-5",
"steps": 4,
"max_steps": 30,
"result": null,
"error": null,
"usage": { "input_tokens": 18234, "output_tokens": 912 },
"created_at": "2026-11-21T10:00:00Z",
"started_at": "2026-11-21T10:00:02Z",
"ended_at": null
}Start a run
POST/v1/runsReturns 202 with the run. The agent works in the background: follow it with Get a run or the event stream.
Body
- taskstring, ≤8000required
What to do, in plain language.
- session_idstring
Drive an existing session. Cannot be combined with
session. - sessionobjectdefault{}
Create a session for this run. Takes the fields of Create a session. The session is closed when the run ends unless
keep_sessionistrue. - start_urlstring, ≤2048
Loaded before the first step. It shows up in the events as a
tool_callandtool_resultpair with idstartand is not counted insteps. - max_stepsint, 1–100default30
The run fails with
max_steps_exceededpast this. - result_schemaJSON Schema object
Ask for a structured
resultthat matches this schema. The rules are under Result schema. - keep_sessionbooldefaultfalse
Keep the session open after the run. Only meaningful when the run created the session.
- modelstringdefaultserver default
One of
claude-opus-5-5,claude-fable-5-2,claude-sonnet-5-5andclaude-haiku-5-5.
The response is the run object, with live_view_url. With neither session_id nor session the run creates a session with the defaults.
A run holds the session's drive lock one step at a time, so drive calls from elsewhere interleave with it and may get session_in_use. A session has one run at a time: starting a second run on a session with an active run fails with 409 run_in_progress.
While a run is running it resets its session's idle clock about every 10 s, so the session does not idle out during a slow model call. timeout_seconds still ends the session, and the run with it: the run fails with session_closed.
Once a run holds 20 screenshots, one more is refused if it, or any screenshot the run already holds, is over 3000 px on a side. The refusal goes back to the agent as a tool error and the run goes on.
Result schema
result_schema is a JSON Schema. The run's result is then a value that matches it instead of a string.
$refworks as a JSON pointer into the schema itself:#/$defs/Item, or#for a recursive type.$id,$anchor,$dynamicRefand$dynamicAnchorare refused with 400invalid_request. So is a$refloop that never descends into the result.details.fieldisresult_schema.- A result that does not match fails the run with
result_invalid.
curl -s -X POST "$SPHYNX_URL/v1/runs" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Get the top 3 titles on news.ycombinator.com",
"session": {
"os": "mac",
"proxy": {"type": "residential", "country": "us"}
},
"result_schema": {
"type": "object",
"properties": {
"titles": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["titles"]
}
}'const res = await fetch(`${process.env.SPHYNX_URL}/v1/runs`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
task: "Get the top 3 titles on news.ycombinator.com",
session: { os: "mac", proxy: { type: "residential", country: "us" } },
result_schema: {
type: "object",
properties: { titles: { type: "array", items: { type: "string" } } },
required: ["titles"],
},
}),
});
const run = await res.json();import os
import requests
res = requests.post(
f"{os.environ['SPHYNX_URL']}/v1/runs",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
json={
"task": "Get the top 3 titles on news.ycombinator.com",
"session": {"os": "mac", "proxy": {"type": "residential", "country": "us"}},
"result_schema": {
"type": "object",
"properties": {"titles": {"type": "array", "items": {"type": "string"}}},
"required": ["titles"],
},
},
timeout=60,
)
run = res.json(){
"id": "run_5d1c0e7a9b3f4a6c8e2d1f0b7a9c3e5d",
"status": "queued",
"task": "Get the top 3 titles on news.ycombinator.com",
"session_id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"live_view_url": "https://api.example/.../view?token=...",
"model": "claude-opus-5-5",
"steps": 0,
"max_steps": 30,
"result": null,
"error": null,
"usage": { "input_tokens": 0, "output_tokens": 0 },
"created_at": "2026-11-21T10:00:00Z",
"started_at": null,
"ended_at": null
}Get a run
GET/v1/runs/{id}Returns the run object. When status is succeeded, the answer is in result.
Path
- idstringrequired
The run ID.
curl -s "$SPHYNX_URL/v1/runs/$RUN" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"id": "run_5d1c0e7a9b3f4a6c8e2d1f0b7a9c3e5d",
"status": "succeeded",
"task": "Get the top 3 titles on news.ycombinator.com",
"session_id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"model": "claude-opus-5-5",
"steps": 2,
"max_steps": 30,
"result": {
"titles": [
"First story",
"Second story",
"Third story"
]
},
"error": null,
"usage": { "input_tokens": 9120, "output_tokens": 388 },
"created_at": "2026-11-21T10:00:00Z",
"started_at": "2026-11-21T10:00:02Z",
"ended_at": "2026-11-21T10:00:14Z"
}List runs
GET/v1/runsReturns your runs, newest first.
Query
- statusstring
Only runs with this status:
queued,running,succeeded,failedorcancelled. - session_idstring
Only runs on this session.
- limitint, 1–100default20
How many runs to return.
- cursorstring
The
next_cursorof the previous page.
Response
- datalist
- next_cursorstring or null
Pass it as
cursorto get the next page.nullon the last page.
curl -s "$SPHYNX_URL/v1/runs?status=running&limit=20" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"data": [
{
"id": "run_5d1c0e7a9b3f4a6c8e2d1f0b7a9c3e5d",
"status": "running",
"task": "Get the top 3 titles on news.ycombinator.com",
"session_id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"model": "claude-opus-5-5",
"steps": 4,
"max_steps": 30,
"result": null,
"error": null,
"usage": {
"input_tokens": 18234,
"output_tokens": 912
},
"created_at": "2026-11-21T10:00:00Z",
"started_at": "2026-11-21T10:00:02Z",
"ended_at": null
}
],
"next_cursor": null
}Cancel a run
POST/v1/runs/{id}/cancelReturns 202 with the run object as it is now: it may still be running for a moment. Safe to repeat, and on a run that has ended it changes nothing. cancelled is a status, not an error: error stays null.
Cancel takes effect between steps: a model call in flight is aborted, a browser step in flight finishes first. The run then ends with status cancelled.
Path
- idstringrequired
The run ID.
curl -s -X POST "$SPHYNX_URL/v1/runs/$RUN/cancel" \
-H "Authorization: Bearer $SPHYNX_API_KEY"List events
GET/v1/runs/{id}/eventsWith Accept: application/json it returns the run's events as a list, in order of seq.
Path
- idstringrequired
The run ID.
Query
- afterint, ≥0
Only events with a higher
seq. For the next page, passnext_cursor. - limitint, 1–2000
At most this many events. Without it, every kept event is returned.
Response
- datalist
Events. Each has the fields below;
datadepends ontype, see Event types.- seqint
The sequence number of the event within the run. Starts at 1 and has no gaps.
- typestring
status,message,tool_call,tool_result,resultorerror. - attimestamp
When it happened.
- dataobject
The payload for that type.
- next_cursorstring or null
nullunlesslimitcut the list. Then the lastseqreturned: pass it asafterto continue.
Runs and events are kept in memory: they are lost when the server restarts, a run keeps at most its last 2000 events, and a key keeps its last 100 ended runs. Older runs answer run_not_found.
curl -s "$SPHYNX_URL/v1/runs/$RUN/events?after=6" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Accept: application/json"{
"data": [
{
"seq": 7,
"type": "tool_call",
"at": "2026-11-21T10:00:09Z",
"data": {
"id": "call_3",
"tool": "click",
"input": { "text": "Sign in" }
}
},
{
"seq": 8,
"type": "tool_result",
"at": "2026-11-21T10:00:10Z",
"data": {
"id": "call_3",
"tool": "click",
"ok": true,
"duration_ms": 2140,
"summary": "clicked",
"url": "https://example.com/dashboard",
"title": "Dashboard"
}
}
],
"next_cursor": null
}Stream events
GET/v1/runs/{id}/eventsWith Accept: text/event-stream the same endpoint streams. It first sends every existing event after after, or after the Last-Event-ID header, then new events as they happen. It closes after the terminal status event.
Each message has three lines: id is the event's seq, event is its type, and data is the event as JSON. A comment line is sent every 15 s to keep the connection open.
Query
- afterint, ≥0
Start after this sequence number. To resume a dropped stream, pass the last
seqyou saw.
Headers
- Last-Event-IDstring
The last
seqyou saw. Used whenafteris absent.
curl -N "$SPHYNX_URL/v1/runs/$RUN/events" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Accept: text/event-stream"const res = await fetch(`${process.env.SPHYNX_URL}/v1/runs/${runId}/events`, {
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
Accept: "text/event-stream",
},
});
if (!res.body) throw new Error("the response has no body");
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffer += value;
const messages = buffer.split("\n\n");
buffer = messages.pop() ?? "";
for (const message of messages) {
const data = message.split("\n").find((line) => line.startsWith("data:"));
if (data) console.log(JSON.parse(data.slice(5)));
}
}import json
import os
import requests
res = requests.get(
f"{os.environ['SPHYNX_URL']}/v1/runs/{run_id}/events",
headers={
"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}",
"Accept": "text/event-stream",
},
stream=True,
timeout=(10, 60),
)
for line in res.iter_lines(decode_unicode=True):
if line.startswith("data:"):
print(json.loads(line[5:]))id: 7
event: tool_call
data: {"seq":7,"type":"tool_call","at":"...","data":{...}}
id: 8
event: tool_result
data: {"seq":8,"type":"tool_result","at":"...","data":{...}}Event types
The data of an event depends on its type.
Types
- status
The run changed status. The first event of every run, with
queued, and the last.- statusstring
The new status.
- message
What the agent says it is doing.
- textstring
- tool_call
The agent called a tool.
- idstring
Pairs the call with its
tool_result. - toolstring
The tool name, for example
click. - inputobject
The arguments of the call.
- tool_result
The tool finished. Page content and images are not included.
- idstring
- toolstring
- okbool
- duration_msint
- summarystring
A short text describing what happened.
- urlstring
The address of the last page a tool reported.
- titlestring
The title of that page.
- errorobject
Only when the call failed:
codeandmessage.
- result
The run produced its result.
- resultstring or object
The same value as
resulton the run.
- error
The run failed.
- codestring
- messagestring
{
"seq": 1,
"type": "status",
"at": "2026-11-21T10:00:00Z",
"data": { "status": "queued" }
}{
"seq": 6,
"type": "message",
"at": "2026-11-21T10:00:08Z",
"data": { "text": "The login form is open. Signing in." }
}{
"seq": 7,
"type": "tool_call",
"at": "2026-11-21T10:00:09Z",
"data": {
"id": "call_3",
"tool": "click",
"input": { "text": "Sign in" }
}
}{
"seq": 41,
"type": "error",
"at": "2026-11-21T10:02:30Z",
"data": {
"code": "max_steps_exceeded",
"message":
"the run used all of its steps without finishing"
}
}Errors
Request errors use the same shape as everywhere else: see Errors. When a run creates its own session, the session create errors apply too, those of the session's start_url included.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Malformed JSON, unknown field, bad value, both session_id and session, a result_schema that is refused |
| 401 | unauthorized | Missing or invalid API key |
| 404 | session_not_found | No such session_id for this key |
| 404 | run_not_found | No such run for this key |
| 409 | run_in_progress | The session already has an active run |
| 410 | session_closed | The session in session_id has ended |
| 422 | unsafe_url | start_url is not http/https, or is a private, loopback or link-local address |
| 422 | model_not_allowed | model is not on the server's list |
| 500 | internal | Our fault. Send us the request_id |
| 503 | agent_unavailable | The server has no model credentials configured |
A run that starts and then fails has status failed. The reason is in error.code on the run and in the error event.
| Code | When |
|---|---|
max_steps_exceeded | The agent needed more than max_steps tool calls |
session_closed | The session ended during the run |
model_error | The model call failed |
result_invalid | The result did not match result_schema, or the run ended without one |
internal | Our fault |