Runs - Splox

A run is one execution of a harness: a message goes in, the agent works on its machine, and what comes out is a transcript, some outputs, a tree of whatever it spawned, and a bill. This page starts one and follows it to the end.

What a run needs

Two ids and an input. The harness is the code the agent is — the tree that runs is the tip of its main branch, and the run records the exact commit it got.

curl -s "$SPLOX_BASE_URL/v2/harnesses" \
  -H "Authorization: Bearer $SPLOX_API_KEY"

{"data":[{"id":"h_5V125BR7R4AA189NRYAB3DQC6D","name":"My Agent"}],"page":{"has_more":false,"next_cursor":null}}

The machine is the computer it runs on. A run happens somewhere: the filesystem it writes to, the shell it opens and the browser it drives all belong to a machine, and that machine keeps them between runs. Machines are listed on /v1, which speaks raw UUIDs:

curl -s "$SPLOX_BASE_URL/v1/machines" \
  -H "Authorization: Bearer $SPLOX_API_KEY"

{
  "machines": [
    {
      "id": "01a060ee-ffb4-736c-9863-db1fee5c13df",
      "kind": "sandbox",
      "harness_id": "bb088abc-1f04-5282-84d7-1e52c6dbb0cd",
      "harness_ref": "main",
      "name": "My Agent",
      "last_active_at": "2026-09-02T07:25:39Z",
      "created_at": "2026-09-02T07:04:30Z",
      "live": {"state": "running", "cpu": 2, "memory_gb": 4, "disk_gb": 30, "auto_stop_minutes": 30}
    }
  ]
}

v2 wants that id in public form, which is a pure encoding of the same UUID:

from splox import encode_id
encode_id("m", "01a060ee-ffb4-736c-9863-db1fee5c13df")  # 'm_01M1GEXZXMEDP9GRYV3ZQ5R4YZ'

The machine must already run the harness you name. Point a run at a machine belonging to another harness and it is refused: 422 validation_failed, “The machine runs a different agent.”, with /machine_id: the machine runs another harness.

Create a run

curl -s "$SPLOX_BASE_URL/v2/runs" \
  -H "Authorization: Bearer $SPLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "harness_id": "h_5V125BR7R4AA189NRYAB3DQC6D",
    "machine_id": "m_01M1GEXZXMEDP9GRYV3ZQ5R4YZ",
    "input": {"role": "user", "content": [{"type": "text", "text": "Run `uname -sm` in your sandbox and reply with exactly what it printed."}]},
    "metadata": {"source": "docs"}
  }'

{
  "id": "run_01M1GFRNR5F4N8S2JZV85T30A4",
  "harness_id": "h_5V125BR7R4AA189NRYAB3DQC6D",
  "harness_commit": "371758ecf28e8240192e4731080a7436fb492a09",
  "chat_id": "chat_01M1GFRNQHF6W9Q9RMP1QMZQR8",
  "parent_chat_id": null,
  "status": "queued",
  "created_at": "2026-09-02T07:19:05.214339044Z",
  "updated_at": "2026-09-02T07:19:05.214339044Z",
  "started_at": null,
  "completed_at": null,
  "failure": null,
  "metadata": {"source": "docs"}
}

201, with Location: /v2/runs/run_01M1GFRNR5F4N8S2JZV85T30A4. The run is queued, not finished — the call returns as soon as the work is accepted.

string

required

The harness to execute. It runs the tip of main, and the answer tells you which commit that was.

string

required

The machine to execute on. Required unless you continue a chat that is already on one.

object

required

{"role": "user", "content": [...]}. Content parts are {"type":"text","text":...}, {"type":"json","value":...} or {"type":"file","url":...,"media_type":...,"name":...}.

string

Continue an existing chat instead of starting a new one. The run inherits that chat’s machine and memory.

object

Yours to use — up to 50 keys of string, number, boolean or null. Keys starting with splox. are reserved.

Send the same key and body again and nothing new happens: the original run comes back with Idempotency-Replayed: true. Send the same key with a different body and you get 409 idempotency_key_conflict.

Follow it

Two ways: subscribe to the event stream, which is what the app does, or poll the run. Streaming is its own page — Streaming — and polling is one request:

curl -s "$SPLOX_BASE_URL/v2/runs/run_01M1GFRNR5F4N8S2JZV85T30A4" \
  -H "Authorization: Bearer $SPLOX_API_KEY"

{
  "id": "run_01M1GFRNR5F4N8S2JZV85T30A4",
  "harness_id": "h_5V125BR7R4AA189NRYAB3DQC6D",
  "harness_commit": "371758ecf28e8240192e4731080a7436fb492a09",
  "chat_id": "chat_01M1GFRNQHF6W9Q9RMP1QMZQR8",
  "parent_chat_id": null,
  "status": "succeeded",
  "created_at": "2026-09-02T07:19:05.219385Z",
  "updated_at": "2026-09-02T07:19:16.72456Z",
  "started_at": "2026-09-02T07:19:05.214339Z",
  "completed_at": "2026-09-02T07:19:16.72456Z",
  "failure": null,
  "metadata": {"source": "docs"}
}

Status	Means
`queued`	accepted, not started
`running`	the agent is working
`waiting`	stopped on a question for a person — see Interactions
`cancelling`	a cancel was asked for and has not landed yet
`succeeded`, `failed`, `cancelled`	terminal; nothing more will happen

A failed run carries a failure object with a stable code, a message written for a person, and whether retrying could help:

"failure": {
  "code": "usage_window_exceeded",
  "message": "You have used your 5-hour limit. It frees up at 12:19 UTC on 2 Sep 2026.",
  "retryable": false
}

Read the transcript

Messages are the conversation the model actually had, oldest first:

curl -s "$SPLOX_BASE_URL/v2/runs/run_01M1GFRNR5F4N8S2JZV85T30A4/messages" \
  -H "Authorization: Bearer $SPLOX_API_KEY"

{
  "data": [
    {
      "id": "msg_01M1GFRW76F68T8K49222Z36KB",
      "run_id": "run_01M1GFRNR5F4N8S2JZV85T30A4",
      "role": "user",
      "content": [{"type": "text", "text": "Run `uname -sm` in your sandbox and reply with exactly what it printed."}],
      "created_at": "2026-09-02T07:19:11.842033Z"
    },
    {
      "id": "msg_01M1GFRYERFW2S0PQAW2E9H458",
      "role": "assistant",
      "content": [{"type": "json", "value": {"type": "tool_call", "tool_call": {
        "id": "call_996ef4f75bc744729e78f92f", "name": "compute_exec", "args": {"command": "uname -sm"}}}}],
      "created_at": "2026-09-02T07:19:14.128155Z"
    },
    {
      "id": "msg_01M1GFRYS0F6JRJH1DD8Q6WQ2F",
      "role": "tool",
      "content": [{"type": "json", "value": {"type": "tool_result", "tool_result": {
        "tool_call_id": "call_996ef4f75bc744729e78f92f",
        "output": "{\"cause\":\"ok\",\"command\":\"uname -sm\",\"exit_code\":0,\"stdout\":\"Linux x86_64\\n\",\"success\":true}",
        "metadata": {"source_url": "system:compute"}}}}],
      "created_at": "2026-09-02T07:19:14.458192Z"
    },
    {
      "id": "msg_01M1GFS0YJE3T9195YGXCTB4B0",
      "role": "assistant",
      "content": [
        {"type": "json", "value": {"type": "reasoning", "reasoning": {"text": "The command printed \"Linux x86_64\"...", "origin": {"provider": "openai", "api": "chat_completions", "model": "kimi-k3"}}}},
        {"type": "text", "text": "Linux x86_64"}
      ],
      "created_at": "2026-09-02T07:19:16.688525Z"
    }
  ],
  "page": {"has_more": false, "next_cursor": null}
}

Roles are user, assistant, tool and system. Everything that is not plain prose arrives as a json part with its own type inside — tool_call, tool_result, reasoning — so a client that only knows about text can render the text parts and ignore the rest without losing them.

Read the outputs

Outputs are what the run produced, as opposed to how it got there. The final answer is one of them:

curl -s "$SPLOX_BASE_URL/v2/runs/run_01M1GFRNR5F4N8S2JZV85T30A4/outputs" \
  -H "Authorization: Bearer $SPLOX_API_KEY"

{
  "data": [
    {
      "id": "out_01M1GFS0Z4FWNBXSY3WVBFSWE0",
      "run_id": "run_01M1GFRNR5F4N8S2JZV85T30A4",
      "type": "result",
      "name": "final_message",
      "value": "Linux x86_64",
      "created_at": "2026-09-02T07:19:16.707764Z"
    }
  ],
  "page": {"has_more": false, "next_cursor": null}
}

type is result or artifact; value is arbitrary JSON. If you want one thing from a run, this is the endpoint to read.

The tree

An agent hands work to sub-agents, and each of those is a run of its own. The tree is a consistent snapshot of the whole family:

curl -s "$SPLOX_BASE_URL/v2/runs/run_01M1GFRNR5F4N8S2JZV85T30A4/tree" \
  -H "Authorization: Bearer $SPLOX_API_KEY"

{
  "root_run_id": "run_01M1GFRNR5F4N8S2JZV85T30A4",
  "runs": [
    {"run": {"id": "run_01M1GFRNR5F4N8S2JZV85T30A4", "chat_id": "chat_01M1GFRNQHF6W9Q9RMP1QMZQR8", "status": "succeeded", "...": "..."}, "depth": 0, "child_run_ids": []},
    {"run": {"id": "run_01M1GFWT5ZEBP9V9M289WMNBEF", "chat_id": "chat_01M1GFRNQHF6W9Q9RMP1QMZQR8", "status": "succeeded", "...": "..."}, "depth": 0, "child_run_ids": []}
  ],
  "generated_at": "2026-09-02T07:19:18.303981382Z"
}

Depth is counted in chats, not runs: every run of this run’s own chat is depth 0 — the two above are two turns of the same conversation — and a chat spawned by it is depth 1. child_run_ids are the runs of the chats this one started.

The bill

curl -s "$SPLOX_BASE_URL/v2/runs/run_01M1GFRNR5F4N8S2JZV85T30A4/usage" \
  -H "Authorization: Bearer $SPLOX_API_KEY"

{
  "run_id": "run_01M1GFRNR5F4N8S2JZV85T30A4",
  "input_tokens": 3215,
  "output_tokens": 96,
  "cache_read_tokens": 22848,
  "cache_write_tokens": 0,
  "total_tokens": 26159,
  "tool_calls": 1,
  "duration_ms": 7783,
  "amount": "0.027065",
  "currency": "USD",
  "final": true,
  "updated_at": "2026-09-02T07:31:57.650167495Z"
}

input_tokens counts only the prompt tokens that were not served from cache, which is why it looks small beside cache_read_tokens: an agent turn re-sends a long prefix and the provider serves most of it from cache. total_tokens is the honest figure. Usage covers the same set of runs the tree does, so two turns of one chat report the same numbers, and final is false while anything in that set is still running.

Cancel

curl -s -X POST "$SPLOX_BASE_URL/v2/runs/run_01M1GFWNRZFQDR0EHKF2ZQYW9F/cancel" \
  -H "Authorization: Bearer $SPLOX_API_KEY"

{"id":"run_01M1GFWNRZFQDR0EHKF2ZQYW9F","status":"cancelled","started_at":"2026-09-02T07:21:16.317043Z","completed_at":"2026-09-02T07:21:16.463898Z","...":"..."}

Cancelling is idempotent and always answers 200 with the run as it now stands. A run already in a terminal state comes back unchanged — cancelling a finished run is not an error. A run that is mid-turn normally passes through cancelling before it reaches cancelled.

List runs

curl -s "$SPLOX_BASE_URL/v2/runs?limit=2" \
  -H "Authorization: Bearer $SPLOX_API_KEY"

Newest first, by (created_at, id). Filters: status (comma-separated, e.g. status=running,waiting, or repeated status= parameters), harness_id, created_after, created_before, plus cursor and limit. Follow page.next_cursor while page.has_more is true.

A second turn in the same chat

Pass chat_id and the run joins the conversation rather than starting one — same machine, same memory, and the agent can refer back to what it already did:

curl -s "$SPLOX_BASE_URL/v2/runs" \
  -H "Authorization: Bearer $SPLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "harness_id": "h_5V125BR7R4AA189NRYAB3DQC6D",
    "machine_id": "m_01M1GEXZXMEDP9GRYV3ZQ5R4YZ",
    "chat_id": "chat_01M1GFRNQHF6W9Q9RMP1QMZQR8",
    "input": {"role": "user", "content": [{"type": "text", "text": "What architecture did you just report? One word."}]}
  }'

The new run reports the same chat_id, and its single output is the answer to a question that only makes sense in context:

{"data":[{"id":"out_01M1GFWZ5PEPE95WTX2Y9VZWYG","run_id":"run_01M1GFWT5ZEBP9V9M289WMNBEF","type":"result","name":"final_message","value":"x86_64","created_at":"2026-09-02T07:21:25.941363Z"}],"page":{"has_more":false,"next_cursor":null}}

The same run in the SDKs

run = client.runs.create(
    {"role": "user", "content": [{"type": "text", "text": "Run `uname -sm` and reply with what it printed."}]},
    harness_id="h_5V125BR7R4AA189NRYAB3DQC6D",
)
run = run.wait()
print(run.status)                                  # succeeded
print([o.value for o in run.outputs().data])       # ['Linux x86_64']
print(run.usage().total_tokens, run.usage().amount)

const run = await client.runs.create({
  harnessId: "h_5V125BR7R4AA189NRYAB3DQC6D",
  input: "Run `uname -sm` and reply with what it printed.",
});
await run.wait();
const outputs = await run.outputs();
console.log(outputs.data.map((o) => o.value));      // [ 'Linux x86_64' ]

run, err := client.Runs.Create(ctx, splox.CreateRunParams{
    HarnessID: "h_5V125BR7R4AA189NRYAB3DQC6D",
    Input:     "Run `uname -sm` and reply with what it printed.",
})
run, err = run.Wait(ctx, splox.WaitOpts{Timeout: 5 * time.Minute})
outs, err := client.Runs.OutputsPage(ctx, run.ID, splox.PageOpts{})

The published SDKs (Python and Node 0.5.4, Go v2.0.0) do not send machine_id, so runs.create against the current API answers 422 validation_failed with /machine_id: machine_id is required. Until they ship it, create runs over HTTP as above; every other call in all three SDKs works against the live API.

​What a run needs

​Create a run

​Follow it

​Read the transcript

​Read the outputs

​The tree

​The bill

​Cancel

​List runs

​A second turn in the same chat

​The same run in the SDKs

What a run needs

Create a run

Follow it

Read the transcript

Read the outputs

The tree

The bill

Cancel

List runs

A second turn in the same chat

The same run in the SDKs