Guides
Agent runs
Give a task in plain language to an agent that drives a session until the task is done.
At the end an agent has done a task in a browser for you and returned the answer as JSON in the shape you asked for. You need an API key.
A run 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 browser in the session's live view while it happens.
Start a run
POST/v1/runs takes a task. With session it creates a session for the run and closes it when the run ends. result_schema is a JSON Schema for the answer you want back.
RUN=$(curl -s -X POST "$SPHYNX_URL/v1/runs" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Open https://example.com/products and return the cheapest product",
"session": {"os": "mac"},
"result_schema": {
"type": "object",
"properties": {"name": {"type": "string"}, "price": {"type": "string"}},
"required": ["name", "price"]
}
}' | jq -r .id)const base = process.env.SPHYNX_URL;
const headers = {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
};
const started = await fetch(`${base}/v1/runs`, {
method: "POST",
headers,
body: JSON.stringify({
task: "Open https://example.com/products and return the cheapest product",
session: { os: "mac" },
result_schema: {
type: "object",
properties: { name: { type: "string" }, price: { type: "string" } },
required: ["name", "price"],
},
}),
});
const run = await started.json();import os
import requests
base = os.environ["SPHYNX_URL"]
headers = {"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"}
run = requests.post(
f"{base}/v1/runs",
headers=headers,
json={
"task": "Open https://example.com/products and return the cheapest product",
"session": {"os": "mac"},
"result_schema": {
"type": "object",
"properties": {"name": {"type": "string"}, "price": {"type": "string"}},
"required": ["name", "price"],
},
},
timeout=60,
).json()https://example.com/products stands in for a page of your own, here a table of three products with their prices.
The call returns 202 with the run. It starts as queued. live_view_url is on this response only.
{
"id": "run_5d1c0e7a9b3f4a6c8e2d1f0b7a9c3e5d",
"status": "queued",
"task": "Open https://example.com/products and return the cheapest product",
"session_id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"live_view_url": "https://api.example/v1/sessions/sess_9f2c.../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
}Watch it work
GET/v1/runs/{id}/events with Accept: text/event-stream streams the run: first every event so far, then new ones as they happen. The stream closes after the last status event.
The stream needs the Authorization header, which a browser's EventSource cannot send. Read it with fetch and a stream reader.
curl -N "$SPHYNX_URL/v1/runs/$RUN/events" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Accept: text/event-stream"const stream = await fetch(`${base}/v1/runs/${run.id}/events`, {
headers: { ...headers, Accept: "text/event-stream" },
});
if (!stream.body) throw new Error("no event stream");
const reader = stream.body.pipeThrough(new TextDecoderStream()).getReader();
let buffered = "";
for (;;) {
const { value, done } = await reader.read();
if (done) break; // the stream closes after the last status event
buffered += value;
const messages = buffered.split("\n\n");
buffered = messages.pop() ?? "";
for (const message of messages) {
const data = message.split("\n").find((line) => line.startsWith("data:"));
if (!data) continue; // a keep-alive comment
const event = JSON.parse(data.slice("data:".length));
console.log(event.seq, event.type, event.data);
}
}import json
with requests.get(
f"{base}/v1/runs/{run['id']}/events",
headers={**headers, "Accept": "text/event-stream"},
stream=True,
timeout=(10, 60), # a keep-alive comment arrives every 15 s
) as stream:
for line in stream.iter_lines():
if line.startswith(b"data:"):
event = json.loads(line[len(b"data:"):])
print(event["seq"], event["type"], event["data"])Each message has an id (the sequence number), an event (the type) and the event as JSON in data.
id: 1
event: status
data: {"seq":1,"type":"status","at":"2026-11-21T10:00:00Z","data":{"status":"queued"}}
id: 2
event: status
data: {"seq":2,"type":"status","at":"2026-11-21T10:00:02Z","data":{"status":"running"}}A step is a tool_call event followed by a tool_result event with the same id.
{
"seq": 4,
"type": "tool_call",
"at": "2026-11-21T10:00:04Z",
"data": {
"id": "call_1",
"tool": "navigate",
"input": { "url": "https://example.com/products" }
}
}{
"seq": 5,
"type": "tool_result",
"at": "2026-11-21T10:00:05Z",
"data": {
"id": "call_1",
"tool": "navigate",
"ok": true,
"duration_ms": 812,
"summary": "HTTP 200",
"url": "https://example.com/products",
"title": "Products"
}
}| Type | Data |
|---|---|
status | status. The first event of every run, with queued, and the last |
message | text: what the agent says it is doing |
tool_call | id, tool and input |
tool_result | id, tool, ok, duration_ms, summary, url, title, and error (code and message) when the step failed. url and title are the last page a tool reported. Page content and images are not included |
result | result: the answer |
error | code and message |
To see the browser as well, open the run's live_view_url in a tab. See Live view.
Read the result
When the last status event says succeeded, read the run with GET/v1/runs/{id}. result matches your result_schema. Without a schema it is a string.
curl -s "$SPHYNX_URL/v1/runs/$RUN" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"id": "run_5d1c0e7a9b3f4a6c8e2d1f0b7a9c3e5d",
"status": "succeeded",
"task": "Open https://example.com/products and return the cheapest product",
"session_id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"model": "claude-opus-5-5",
"steps": 3,
"max_steps": 30,
"result": { "name": "Sprocket", "price": "$8.75" },
"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": "2026-11-21T10:00:11Z"
}steps is the number of browser tool calls the agent made. The call that hands in the result is not counted. A run that did not succeed has result: null, and a failed one has the reason in error.
In a result_schema, $ref works as a JSON pointer into the schema itself, such as #/$defs/Item. $id, $anchor, $dynamicRef and $dynamicAnchor are refused with 400 invalid_request.
You can skip the stream and poll this call until status is succeeded, failed or cancelled.
Pick up where you left off
If the stream drops, reconnect with a Last-Event-ID header set to the last sequence number you saw, or with ?after=<seq>. You get every event after it.
With Accept: application/json the same endpoint returns events as a list: every kept event after after, or at most limit of them (1 to 2000). next_cursor is null unless limit cut the list. Pass it as after to continue.
curl -s "$SPHYNX_URL/v1/runs/$RUN/events?after=11" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Accept: application/json"{
"data": [
{
"seq": 12,
"type": "result",
"at": "2026-11-21T10:00:11Z",
"data": { "result": { "name": "Sprocket", "price": "$8.75" } }
},
{
"seq": 13,
"type": "status",
"at": "2026-11-21T10:00:11Z",
"data": { "status": "succeeded" }
}
],
"next_cursor": null
}Use a session you already have
Pass session_id in place of session to run the task in an existing session, for example one you have already logged in. The run leaves that session open when it ends.
{
"task": "Open the first product and return its stock status",
"session_id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"start_url": "https://example.com/products",
"max_steps": 15
}start_urlis loaded before the first step. It shows up in the events as atool_callandtool_resultpair with idstartand is not counted insteps.max_stepscaps the tool calls. It is 30 by default and at most 100.modelpicks the model:claude-opus-5-5,claude-fable-5-2,claude-sonnet-5-5orclaude-haiku-5-5. Without it the server's default is used.- To keep a session that the run created, set
keep_sessiontotrue. - A session runs one run at a time. Your own drive calls on it interleave with the run's steps and may get
session_in_use. Retry them. - While a run is running it resets the session's idle clock about every 10 s, so the session does not idle out during a slow model call.
timeout_secondsstill ends the session, and the run with it.
Cancel a run
POST/v1/runs/{id}/cancel returns 202 with the run and is safe to repeat. 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, which is a status and not an error.
curl -s -X POST "$SPHYNX_URL/v1/runs/$RUN/cancel" \
-H "Authorization: Bearer $SPHYNX_API_KEY"What can go wrong
These fail the request:
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | A missing task, an unknown field, both session and session_id, or a result_schema that is refused |
| 404 | session_not_found | No such session_id for this key |
| 404 | run_not_found | No such run for this key, on read, cancel or events |
| 409 | run_in_progress | The session already has an active run |
| 410 | session_closed | The session in session_id has ended |
| 422 | model_not_allowed | model is not on the server's list |
| 429 | concurrency_limit | The run needs a new session and the key has too many. Retry-After is set |
| 503 | agent_unavailable | The server has no model credentials configured |
A run that starts can still fail. Its status is failed, and the code 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 before the task was done |
model_error | The model call failed |
result_invalid | The result did not match result_schema, or the run ended without one |
internal | Our fault |
{
"status": "failed",
"result": null,
"error": {
"code": "max_steps_exceeded",
"message": "the run used all of its steps without finishing"
}
}