SPHYNX
esc
  • Loading
Open console

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, failed or cancelled.

  • 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

    null until the run succeeds. A string, or a value that matches result_schema when one was given.

  • errorobject or null

    null, or code and message when the run failed. The codes are under Errors.

  • usageobject

    Tokens summed over the model calls of the run. input_tokens includes cached tokens.

    • input_tokensint
    • output_tokensint
  • created_attimestamp

    When the run was created.

  • started_attimestamp or null

    When the agent started. null while the run is queued.

  • ended_attimestamp or null

    When the run ended. null until then.

The run object
{
  "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/runs

Returns 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_session is true.

  • start_urlstring, ≤2048

    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_stepsint, 1–100default30

    The run fails with max_steps_exceeded past this.

  • result_schemaJSON Schema object

    Ask for a structured result that 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-5 and claude-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.

  • $ref works as a JSON pointer into the schema itself: #/$defs/Item, or # for a recursive type.
  • $id, $anchor, $dynamicRef and $dynamicAnchor are refused with 400 invalid_request. So is a $ref loop that never descends into the result. details.field is result_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"]
    }
  }'
202
{
  "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
curl -s "$SPHYNX_URL/v1/runs/$RUN" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200 · a run that succeeded
{
  "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/runs

Returns your runs, newest first.

Query

  • statusstring

    Only runs with this status: queued, running, succeeded, failed or cancelled.

  • session_idstring

    Only runs on this session.

  • limitint, 1–100default20

    How many runs to return.

  • cursorstring

    The next_cursor of the previous page.

Response

  • datalist
  • next_cursorstring or null

    Pass it as cursor to get the next page. null on the last page.

curl
curl -s "$SPHYNX_URL/v1/runs?status=running&limit=20" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "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}/cancel

Returns 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
curl -s -X POST "$SPHYNX_URL/v1/runs/$RUN/cancel" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"

List events

GET/v1/runs/{id}/events

With 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, pass next_cursor.

  • limitint, 1–2000

    At most this many events. Without it, every kept event is returned.

Response

  • datalist

    Events. Each has the fields below; data depends on type, 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, result or error.

    • attimestamp

      When it happened.

    • dataobject

      The payload for that type.

  • next_cursorstring or null

    null unless limit cut the list. Then the last seq returned: pass it as after to 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
curl -s "$SPHYNX_URL/v1/runs/$RUN/events?after=6" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Accept: application/json"
200
{
  "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}/events

With 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 seq you saw.

Headers

  • Last-Event-IDstring

    The last seq you saw. Used when after is absent.

curl -N "$SPHYNX_URL/v1/runs/$RUN/events" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Accept: text/event-stream"
200 · text/event-stream
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: code and message.

  • result

    The run produced its result.

    • resultstring or object

      The same value as result on the run.

  • error

    The run failed.

    • codestring
    • messagestring
status
{
  "seq": 1,
  "type": "status",
  "at": "2026-11-21T10:00:00Z",
  "data": { "status": "queued" }
}
message
{
  "seq": 6,
  "type": "message",
  "at": "2026-11-21T10:00:08Z",
  "data": { "text": "The login form is open. Signing in." }
}
tool_call
{
  "seq": 7,
  "type": "tool_call",
  "at": "2026-11-21T10:00:09Z",
  "data": {
    "id": "call_3",
    "tool": "click",
    "input": { "text": "Sign in" }
  }
}
error
{
  "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.

HTTPCodeWhen
400invalid_requestMalformed JSON, unknown field, bad value, both session_id and session, a result_schema that is refused
401unauthorizedMissing or invalid API key
404session_not_foundNo such session_id for this key
404run_not_foundNo such run for this key
409run_in_progressThe session already has an active run
410session_closedThe session in session_id has ended
422unsafe_urlstart_url is not http/https, or is a private, loopback or link-local address
422model_not_allowedmodel is not on the server's list
500internalOur fault. Send us the request_id
503agent_unavailableThe 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.

CodeWhen
max_steps_exceededThe agent needed more than max_steps tool calls
session_closedThe session ended during the run
model_errorThe model call failed
result_invalidThe result did not match result_schema, or the run ended without one
internalOur fault