Drive a run from your own code

curl -s -X POST "https://splox.io/api/v1/api-tokens" \
  -H "Cookie: session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "run-script", "duration_minutes": 240}'

{
  "token": "<shown once — copy it now>",
  "name": "run-script",
  "expires_at": "2026-09-02T17:25:09Z",
  "expires_in": 14400,
  "scope": "api",
  "endpoint": "https://splox.io/api/v1/chat/completions",
  "rate_limit": "10 requests per second",
  "max_concurrent_requests": 10
}

export SPLOX_HOST=https://splox.io
export SPLOX_API_KEY=<that token>

curl -s "$SPLOX_HOST/api/v2/harnesses" -H "Authorization: Bearer $SPLOX_API_KEY"

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

#!/usr/bin/env python3
"""Start a run on Splox, follow its events, and print what it produced."""

import json
import os
import urllib.request
import uuid

HOST = os.environ["SPLOX_HOST"]
KEY = os.environ["SPLOX_API_KEY"]
CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"


def public_id(prefix, raw):
    """v1 speaks uuids, v2 speaks m_… and h_…: same 128 bits, base32."""
    n = int(uuid.UUID(raw))
    return prefix + "_" + "".join(CROCKFORD[(n >> shift) & 31] for shift in range(125, -1, -5))


def call(method, path, body=None, headers=None):
    data = json.dumps(body).encode() if body is not None else None
    request = urllib.request.Request(
        HOST + path,
        data=data,
        method=method,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
            "User-Agent": "splox-docs-example",
            **(headers or {}),
        },
    )
    with urllib.request.urlopen(request) as response:
        return json.load(response)


# 1. Which machine, and which harness it runs. v1 is the only listing there is.
machine = call("GET", "/api/v1/machines")["machines"][0]
print(f"machine {machine['name']}: {machine['live']['state']}")

# 2. Start the run. machine_id is required, and it has to be the m_… form.
run = call(
    "POST",
    "/api/v2/runs",
    {
        "harness_id": public_id("h", machine["harness_id"]),
        "machine_id": public_id("m", machine["id"]),
        "input": {
            "role": "user",
            "content": [{"type": "text", "text": "Count the data rows in /home/daytona/reports/loan.csv and reply with just the number."}],
        },
        "metadata": {"source": "docs-tutorial"},
    },
    {"Idempotency-Key": str(uuid.uuid4())},
)
print(f"{run['id']} {run['status']} on {run['harness_commit'][:7]}, chat {run['chat_id']}")

# 3. Follow the journal until the run reaches a terminal status.
stream = urllib.request.Request(
    f"{HOST}/api/v2/runs/{run['id']}/events",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Accept": "text/event-stream",
        "User-Agent": "splox-docs-example",
    },
)
with urllib.request.urlopen(stream) as events:
    for line in events:
        line = line.decode("utf-8").rstrip("\n")
        if not line.startswith("data: "):
            continue
        event = json.loads(line[len("data: "):])
        data = event["data"]
        detail = data.get("hook") or data.get("role") or data.get("to") or data.get("name") or ""
        print(f"{event['sequence']:3}  {event['type']:20} {detail}")
        if event["type"] == "run.status_changed" and data["to"] in ("succeeded", "failed", "cancelled"):
            break

# 4. Read what it produced.
for output in call("GET", f"/api/v2/runs/{run['id']}/outputs")["data"]:
    print(f"\n{output['name']}: {output['value']}")

usage = call("GET", f"/api/v2/runs/{run['id']}/usage")
print(f"{usage['total_tokens']} tokens, {usage['tool_calls']} tool calls, ${usage['amount']}")

python3 run.py

machine My Agent: running
run_01M1H69AS2FPJAVAGY535MWCVA queued on 2677a1a, chat chat_01M1H69ARCFRAV88TRJ756EKP1
  1  run.created
  2  run.status_changed   running
  3  message.created      user
  4  hook.called          guard.on_input
  5  hook.called          context.build
  6  hook.called          model.choose
  7  hook.called          stop.done
  8  message.created      assistant
  9  hook.called          tools.before
 10  message.created      tool
 11  hook.called          context.build
 12  hook.called          model.choose
 13  hook.called          errors.on
 14  run.status_changed   running
 15  hook.called          context.build
 16  hook.called          model.choose
 17  hook.called          stop.done
 18  message.created      assistant
 19  output.created       final_message
 20  run.status_changed   succeeded

final_message: 12

18606 tokens, 1 tool calls, $0.032582

{
  "type": "https://api.splox.com/problems/validation_failed",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "A run happens on a machine: name one, or continue a chat that is already on one.",
  "code": "validation_failed",
  "errors": [{"name": "/machine_id", "location": "body", "reason": "machine_id is required", "code": "required"}]
}

run = call("POST", "/api/v2/runs", {
    "harness_id": public_id("h", machine["harness_id"]),
    "machine_id": public_id("m", machine["id"]),
    "chat_id": run["chat_id"],
    "input": {"role": "user", "content": [{"type": "text", "text": "And the header row — what are its columns?"}]},
}, {"Idempotency-Key": str(uuid.uuid4())})