Runs & Events API Reference

Runs & Events API Reference

OnceOnly exposes two related debugging surfaces:

• Runs - structured timelines for a specific run_id, stored in PostgreSQL
• Events - recent namespace-level events, stored in Redis

Use runs when you want step-by-step execution history. Use recent events when you want a quick feed of recent duplicate, limit, AI, or governance activity.

---

Create Run Event

Endpoint: POST /v1/events

Create a structured run event entry.

Request

curl -X POST https://api.onceonly.tech/v1/events \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "run_support_001",
    "type": "tool_call",
    "status": "start",
    "step": "step_1",
    "tool": "send_email",
    "agent_id": "support_bot",
    "data": {
      "customer_id": "cus_123"
    }
  }'

Response

{
  "ok": true,
  "event_id": 123,
  "run_id": "run_support_001"
}

Supported Fields

The current request model accepts:

• run_id
• type
• ts
• status
• duration_ms
• step
• tool
• req_id
• lease_id
• agent_id
• message
• data

---

List Runs

Endpoint: GET /v1/runs

List the latest runs for the authenticated namespace.

Query Parameters

Parameter	Type	Description
limit	integer	1-500, default 50
offset	integer	Pagination offset
q	string	Optional prefix filter for run_id

Request

curl -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  "https://api.onceonly.tech/v1/runs?limit=20&q=run_support_"

Response

{
  "total": 2,
  "items": [
    {
      "run_id": "run_support_001",
      "last_ts": 1711871400,
      "last_type": "run_finished",
      "last_status": "completed",
      "events_count": 6
    },
    {
      "run_id": "run_support_002",
      "last_ts": 1711871200,
      "last_type": "run_started",
      "last_status": "started",
      "events_count": 2
    }
  ]
}

---

Get Run Timeline

Endpoint: GET /v1/runs/{run_id}

Fetch the ordered timeline for one run.

Query Parameters

Parameter	Type	Description
limit	integer	1-2000, default 200
offset	integer	Pagination offset

Request

curl -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  "https://api.onceonly.tech/v1/runs/run_support_001?limit=200"

Response

{
  "run_id": "run_support_001",
  "total": 5,
  "events": [
    {
      "id": 101,
      "run_id": "run_support_001",
      "ts": 1711871300,
      "type": "run_started",
      "status": "in_progress",
      "lease_id": "lease_abc123xyz",
      "data": {
        "key": "support_chat_001"
      }
    },
    {
      "id": 102,
      "run_id": "run_support_001",
      "ts": 1711871300,
      "type": "agent_step",
      "status": "start",
      "step": "step_1",
      "tool": "send_email",
      "agent_id": "support_bot"
    },
    {
      "id": 103,
      "run_id": "run_support_001",
      "ts": 1711871301,
      "type": "tool_call",
      "status": "start",
      "step": "step_1",
      "tool": "send_email",
      "agent_id": "support_bot"
    },
    {
      "id": 104,
      "run_id": "run_support_001",
      "ts": 1711871302,
      "type": "tool_result",
      "status": "ok",
      "duration_ms": 182,
      "step": "step_1",
      "tool": "send_email",
      "agent_id": "support_bot",
      "data": {
        "decision": "executed"
      }
    },
    {
      "id": 105,
      "run_id": "run_support_001",
      "ts": 1711871303,
      "type": "run_finished",
      "status": "completed",
      "lease_id": "lease_abc123xyz"
    }
  ]
}

HTML Debug View

If the request prefers text/html, the same endpoint returns a simple HTML timeline view instead of JSON. That is useful when opening a run directly in the browser.

---

Get Recent Namespace Events

Endpoint: GET /v1/events

This is the recent Redis-backed event feed for the current namespace.

In the current backend, this feed is retained for 7 days and capped at 200 items per namespace.

Query Parameters

Parameter	Type	Description
limit	integer	1-200, default 50
offset	integer	Pagination offset

Request

curl -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  "https://api.onceonly.tech/v1/events?limit=20"

Response

[
  {
    "ts": 1711871300,
    "type": "ai_completed",
    "key": "support_chat_001",
    "lease_id": "lease_abc123xyz"
  },
  {
    "ts": 1711871200,
    "type": "policy_blocked",
    "meta": {
      "agent_id": "support_bot",
      "tool": "delete_user",
      "reason": "tool_not_in_allowed_list",
      "risk_level": "medium",
      "policy_version": "a1b2c3d4e5f6"
    }
  }
]

What Appears Here

The recent events feed can include items such as:

• duplicate
• over_limit
• ai_acquired
• ai_completed
• ai_failed
• policy_blocked

This feed is recent and lightweight. For structured debugging of a specific run, prefer /v1/runs/{run_id}.

---

See also: AI Run API | Audit & Metrics API