Flow Run Trace API

Base URL: https://api.noukai.xyz/api/v1

When you execute a flow via /execute or /jobs, Noukai can persist each block's input and output payloads alongside the metadata it already tracks (status, duration, tokens, cost). The Flow Run Trace API exposes those records so you can:

• Audit historical runs and inspect what each block actually saw and produced.
• Drive a debugger UI that walks block-by-block through a completed run.
• Live-tail an in-progress run over Server-Sent Events.

Endpoints

Authentication

Authorization: Bearer nk_live_...

Same auth as the rest of the API — API keys or JWT tokens. The caller must have access to the project that owns the flow; otherwise 403.

List Runs

GET /flow-runs?flow_id={flowId}

Returns the most recent runs for a flow, newest first.

Query Parameters

Response (200)

{
  "runs": [
    {
      "id": "fr_01HX...",
      "flowId": "fl_01HX...",
      "status": "completed",
      "triggerType": "api",
      "startedAt": "2026-05-15T10:23:04.120Z",
      "completedAt": "2026-05-15T10:23:08.941Z",
      "durationMs": 4821,
      "stepCount": 4
    }
  ],
  "nextCursor": null
}

Whole-Run Trace

GET /flow-runs/{flowRunId}/trace

Returns the flow run summary plus the latest attempt of every step. Retries collapse to just the most recent attempt; the only signal in this response that a step retried is attempt > 1. To see prior attempts, call the single-step endpoint with attempt=all.

Path Parameters

Response (200)

{
  "flowRun": {
    "id": "fr_01HX...",
    "flowId": "fl_01HX...",
    "status": "completed",
    "triggerType": "api",
    "startedAt": "2026-05-15T10:23:04.120Z",
    "completedAt": "2026-05-15T10:23:08.941Z",
    "durationMs": 4821,
    "stepCount": 4
  },
  "steps": [
    {
      "stepId": "summarize_essay",
      "attempt": 1,
      "status": "completed",
      "startedAt": "2026-05-15T10:23:04.120Z",
      "completedAt": "2026-05-15T10:23:05.960Z",
      "durationMs": 1840,
      "modelUsed": "openai/gpt-4o-mini",
      "tokens": { "prompt": 412, "completion": 88, "total": 500 },
      "costUsd": "0.00041",
      "inputContext": {
        "__pipeline_input__": { "essay_text": "The industrial revolution..." },
        "config": { "max_length": 200 }
      },
      "outputContext": {
        "summary": "The essay argues that industrialization..."
      },
      "errorContext": null,
      "inputSizeBytes": 1284,
      "outputSizeBytes": 412,
      "truncated": false
    }
  ]
}

Step Trace Object

Single-Step Trace

GET /flow-runs/{flowRunId}/steps/{stepId}/trace

Fetch one step's trace, with control over which attempt(s) are returned.

Path Parameters

Query Parameters

Response — attempt=latest or a numeric value (200)

Returns a single Step Trace Object:

{
  "stepId": "summarize_essay",
  "attempt": 1,
  "status": "completed",
  "startedAt": "2026-05-15T10:23:04.120Z",
  "completedAt": "2026-05-15T10:23:05.960Z",
  "durationMs": 1840,
  "modelUsed": "openai/gpt-4o-mini",
  "tokens": { "prompt": 412, "completion": 88, "total": 500 },
  "costUsd": "0.00041",
  "inputContext": { "...": "..." },
  "outputContext": { "...": "..." },
  "errorContext": null,
  "inputSizeBytes": 1284,
  "outputSizeBytes": 412,
  "truncated": false
}

Response — attempt=all (200)

{
  "stepId": "summarize_essay",
  "attempts": [
    { "stepId": "summarize_essay", "attempt": 1, "status": "failed",    "...": "..." },
    { "stepId": "summarize_essay", "attempt": 2, "status": "completed", "...": "..." }
  ]
}

Each element of attempts is a Step Trace Object, ordered by attempt ascending. A step that did not retry returns a single-element list — not a 404. 404 is returned only when the step never ran at all.

Live-Tail Stream (SSE)

GET /flow-runs/{flowRunId}/trace/stream

Subscribe to a flow run's trace as Server-Sent Events. The connection always opens with a replay of every event that has happened so far (reconstructed from the persisted trace), then transitions to a live tail of new events as the worker emits them. After replay, the stream stays open until the run finishes or the client disconnects.

Content-Type: text/event-stream
Cache-Control: no-cache

Use this when:

• The run was just started and you want a UI to react event-by-event.
• The run started a moment ago and you want to catch up without polling.
• The run is already finished — replay alone gives you the full event log in one stream.

Connection lifecycle

1. Server emits flow_started.
2. For each step that has progressed: step_started, optionally step_input, then step_output or step_error, then step_completed. (Events are omitted when the data for them is not yet — or never — available, e.g. step_input is skipped under metadata_only capture.)
3. If the flow run is already terminal at replay time, the server emits flow_completed and closes the stream.
4. Otherwise the server holds the connection open and forwards events from the live channel as the run progresses, ending with flow_completed.

Idle keepalive: the server emits an SSE comment frame (: ping\n\n) every 15 seconds with no activity to keep proxies from closing the connection. Clients should ignore frames starting with :.

Treat any disconnect as terminal. A clean termination is flow_completed followed by the server closing the connection. If the connection drops without flow_completed (network, timeout, server crash), do not assume the run is still progressing — re-open the stream to receive the full replay and learn the run's current state. The replay is idempotent: any events already shown will arrive again with the same (stepId, attempt, eventName) and your client-side dedup keeps the UI consistent.

Authentication failures return an HTTP error (401 / 403) before the stream opens — they are not delivered as SSE events.

Event Vocabulary

Every event carries a string event: header and a JSON data: payload. The same vocabulary is used by Noukai's test runner — a UI written against these events handles both production runs and editor test runs.

flow_started

event: flow_started
data: { "flowRunId": "fr_01HX...", "flowId": "fl_01HX...", "startedAt": "2026-05-15T10:23:04.120Z" }

step_started

event: step_started
data: { "stepId": "summarize_essay", "attempt": 1, "startedAt": "2026-05-15T10:23:04.120Z", "blockName": "Summarize" }

step_input

Emitted only when capture mode is full or redacted. Omitted under metadata_only and off.

event: step_input
data: { "stepId": "...", "attempt": 1, "inputContext": { "...": "..." }, "inputSizeBytes": 1284, "truncated": false }

step_output

Emitted only when the step completed successfully and capture mode is full / redacted. Omitted under metadata_only and off.

event: step_output
data: { "stepId": "...", "attempt": 1, "outputContext": { "...": "..." }, "outputSizeBytes": 412, "truncated": false }

step_error

Emitted instead of step_output when the step failed.

event: step_error
data: { "stepId": "...", "attempt": 1, "errorContext": { "code": "MODEL_TIMEOUT", "message": "Upstream model timed out", "retryable": true } }

step_completed

Final event for a step. Fires after step_output (on success), after step_error (on failure), or alone when the step was skipped.

event: step_completed
data: {
  "stepId": "summarize_essay",
  "attempt": 1,
  "status": "completed",
  "durationMs": 1840,
  "tokens": { "prompt": 412, "completion": 88, "total": 500 },
  "costUsd": "0.00041",
  "modelUsed": "openai/gpt-4o-mini"
}

flow_completed

Last event in the stream. The server closes the connection after sending it.

event: flow_completed
data: { "flowRunId": "fr_01HX...", "status": "completed", "durationMs": 4821, "error": null }

Capture Modes

Each flow (or, by default, each organization) has a traceCaptureMode setting that controls how much detail is persisted per step. The setting also controls which SSE events are emitted.

Step metadata is always recorded regardless of mode — capture mode only controls payload persistence. The trace endpoints therefore continue to return run summaries and step lists even under off; only the payload fields and sizes change.

Size cap. full and redacted modes cap each payload at 256 KB. Oversized payloads are stored truncated with truncated: true and a __truncated__: true marker injected at the JSON root of inputContext / outputContext.

Retention. Trace payloads are retained for 30 days by default; metadata (status, duration, tokens, cost) is kept indefinitely.

Capture mode resolution order: flow.traceCaptureMode → organization.defaultTraceCaptureMode → "metadata_only". Switching modes only affects runs that start after the change.

Per-Attempt Semantics

A step that retries produces one flow_step_runs record per attempt, and one trace record per attempt.

• The whole-run trace returns the latest attempt of every step.
• The single-step trace defaults to the latest attempt and lets you opt in to all attempts (?attempt=all) or a specific one (?attempt=2).
• The SSE live-tail stream emits a full event sequence per attempt. UI state machines should be keyed on (stepId, attempt) so an in-flight attempt and a completed earlier attempt of the same step don't overwrite each other in your local store. (This is the same key the server uses internally for its own dedup, plus the event name.)

Error Responses

cURL Examples

List the 20 most recent runs of a flow:

curl -X GET "https://api.noukai.xyz/api/v1/flow-runs?flow_id=fl_01HX...&limit=20" \
  -H "Authorization: Bearer $NOUKAI_API_KEY"

Fetch the trace for a single run:

curl -X GET "https://api.noukai.xyz/api/v1/flow-runs/fr_01HX.../trace" \
  -H "Authorization: Bearer $NOUKAI_API_KEY"

Inspect every retry attempt for one step:

curl -X GET "https://api.noukai.xyz/api/v1/flow-runs/fr_01HX.../steps/summarize_essay/trace?attempt=all" \
  -H "Authorization: Bearer $NOUKAI_API_KEY"

Live-tail an in-progress run (curl prints each event as it arrives):

curl -N -X GET "https://api.noukai.xyz/api/v1/flow-runs/fr_01HX.../trace/stream" \
  -H "Authorization: Bearer $NOUKAI_API_KEY"

Minimal Node SSE consumer:

const res = await fetch(
  `https://api.noukai.xyz/api/v1/flow-runs/${flowRunId}/trace/stream`,
  { headers: { Authorization: `Bearer ${process.env.NOUKAI_API_KEY}` } },
);
 
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buf = "";
 
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
 
  // Split on the SSE frame terminator
  let i: number;
  while ((i = buf.indexOf("\n\n")) !== -1) {
    const frame = buf.slice(0, i);
    buf = buf.slice(i + 2);
    if (frame.startsWith(":")) continue; // keepalive ping
    const event = /^event: (.+)$/m.exec(frame)?.[1];
    const data  = /^data: (.+)$/m.exec(frame)?.[1];
    if (event && data) handle(event, JSON.parse(data));
  }
}