SPHYNX
esc
  • Loading
Open console

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)

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.

202
{
  "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"

Each message has an id (the sequence number), an event (the type) and the event as JSON in data.

The first two messages
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.

tool_call
{
  "seq": 4,
  "type": "tool_call",
  "at": "2026-11-21T10:00:04Z",
  "data": {
    "id": "call_1",
    "tool": "navigate",
    "input": { "url": "https://example.com/products" }
  }
}
tool_result
{
  "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"
  }
}
TypeData
statusstatus. The first event of every run, with queued, and the last
messagetext: what the agent says it is doing
tool_callid, tool and input
tool_resultid, 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
resultresult: the answer
errorcode 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
curl -s "$SPHYNX_URL/v1/runs/$RUN" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "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
curl -s "$SPHYNX_URL/v1/runs/$RUN/events?after=11" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Accept: application/json"
200
{
  "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.

Body
{
  "task": "Open the first product and return its stock status",
  "session_id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
  "start_url": "https://example.com/products",
  "max_steps": 15
}
  • start_url is loaded before the first step. It shows up in the events as a tool_call and tool_result pair with id start and is not counted in steps.
  • max_steps caps the tool calls. It is 30 by default and at most 100.
  • model picks the model: claude-opus-5-5, claude-fable-5-2, claude-sonnet-5-5 or claude-haiku-5-5. Without it the server's default is used.
  • To keep a session that the run created, set keep_session to true.
  • 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_seconds still 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
curl -s -X POST "$SPHYNX_URL/v1/runs/$RUN/cancel" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"

What can go wrong

These fail the request:

HTTPCodeWhen
400invalid_requestA missing task, an unknown field, both session and session_id, or a result_schema that is refused
404session_not_foundNo such session_id for this key
404run_not_foundNo such run for this key, on read, cancel or events
409run_in_progressThe session already has an active run
410session_closedThe session in session_id has ended
422model_not_allowedmodel is not on the server's list
429concurrency_limitThe run needs a new session and the key has too many. Retry-After is set
503agent_unavailableThe 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.

CodeWhen
max_steps_exceededThe agent needed more than max_steps tool calls
session_closedThe session ended before the task was done
model_errorThe model call failed
result_invalidThe result did not match result_schema, or the run ended without one
internalOur fault
A failed run · status, result and error
{
  "status": "failed",
  "result": null,
  "error": {
    "code": "max_steps_exceeded",
    "message": "the run used all of its steps without finishing"
  }
}

Next

  • Runs: every field of the run object and the endpoints.
  • Live view: watch the session while the agent works.
  • MCP: give the same tools to your own agent.