Run

Run

Proxy for inspecting a specific flow execution by ID. No network call is made at construction; methods are lazy.

Methods

async trace(opts?: { timeout?: number; signal?: AbortSignal }) -> Trace

Fetch the complete execution trace with the latest attempt per step.

Parameters:

• timeout (number, optional): Request timeout in milliseconds. Default: undefined
• signal (AbortSignal, optional): Abort signal for cancellation. Default: undefined

Returns: Trace with flowRun (RunSummary) and steps (array of StepTrace)

Throws:

• FlowNotFoundError: Execution ID not found
• APITimeoutError: Request timed out
• APIConnectionError: Network error

Example:

const trace = await flow.run(result.executionId).trace();
console.log(`Run: ${trace.flowRun.id}`);
console.log(`Duration: ${trace.flowRun.durationMs}ms`);
 
// Aggregate cost across steps (costUsd is a decimal string)
const totalCost = trace.steps.reduce(
  (sum, s) => sum + (s.costUsd ? parseFloat(s.costUsd) : 0),
  0
);
console.log(`Total cost: $${totalCost.toFixed(6)}`);

async stepTrace(stepId, opts?: StepTraceOptions) -> StepTrace | StepAttempts

Fetch per-step trace, optionally across multiple attempts.

Parameters:

• stepId (string): The step identifier to fetch
• attempt (string or number, optional): "latest" (default), "all", or attempt number N. Default: "latest"
• loopIndex (number, optional): Loop iteration index for steps inside a loop. Default: undefined
• timeout (number, optional): Request timeout in milliseconds. Default: undefined
• signal (AbortSignal, optional): Abort signal for cancellation. Default: undefined

Returns:

• StepTrace when attempt="latest" (default) or attempt=N
• StepAttempts when attempt="all"

Throws:

• FlowNotFoundError: Execution or step not found
• APITimeoutError: Request timed out

Example:

// Latest attempt only
const step = await flow.run(result.executionId).stepTrace("my_step");
console.log(`Step ${step.stepId}: ${step.status}`);
 
// All attempts
const history = await flow.run(result.executionId).stepTrace("my_step", { attempt: "all" });
for (const attempt of history.attempts) {
  console.log(`  Attempt ${attempt.attempt}: ${attempt.status}`);
}

liveTrace() -> AsyncIterable<StreamEvent>

Stream live trace events, replaying from database then live-tailing until the run terminates.

Yields: StreamEvent union — typed events like RunStarted, StepStarted, StepCompleted, FlowCompleted, etc. (not full Trace snapshots)

Example:

for await (const event of flow.run(result.executionId).liveTrace()) {
  if (event.type === "step_completed") {
    console.log(`Step ${event.stepId}: ${event.durationMs}ms`);
  } else if (event.type === "flow_completed") {
    console.log(`Done: ${JSON.stringify(event.result)}`);
  }
}

Trace (Type)

Complete execution trace with run summary and per-step details. Cost/duration totals are aggregated client-side from steps — the Trace object itself has no totalCostUsd or totalDurationMs field.

Attributes:

• flowRun (RunSummary): Run-level metadata
• steps (StepTrace[]): Array of step traces (latest attempt each)

Example:

const trace = await flow.run(executionId).trace();
 
// Run summary
console.log(`Flow: ${trace.flowRun.flowId}`);
console.log(`Status: ${trace.flowRun.status}`);
console.log(`Duration: ${trace.flowRun.durationMs}ms`);
console.log(`Steps: ${trace.flowRun.stepCount}`);
 
// Aggregate totals
const totalCost = trace.steps.reduce(
  (sum, s) => sum + (s.costUsd ? parseFloat(s.costUsd) : 0),
  0
);
const totalDuration = trace.steps.reduce(
  (sum, s) => sum + (s.durationMs || 0),
  0
);
console.log(`Total: $${totalCost.toFixed(6)}, ${totalDuration}ms`);

RunSummary (Type)

High-level metadata about a flow execution.

Attributes:

• id (string): Unique execution ID
• flowId (string): Flow ID this execution ran against
• status (string): Execution status (e.g., "completed", "failed")
• triggerType (string | undefined): How the flow was triggered (e.g., "api", "job")
• startedAt (string | undefined): ISO timestamp when execution started
• completedAt (string | undefined): ISO timestamp when execution completed
• durationMs (number | undefined): Total execution time in milliseconds
• stepCount (number | undefined): Number of steps in the flow

StepTrace (Type)

Execution metrics for a single step (one attempt).

Attributes:

• stepId — Unique step identifier (no separate name field on StepTrace)
• attempt — Attempt number (1 = first try, >1 if server retried this step)
• loopIndex — Iteration index if the step is inside a loop (optional)
• status — One of: "running", "completed", "failed", "skipped"
• startedAt — ISO timestamp when the step started (optional)
• completedAt — ISO timestamp when the step completed (optional)
• durationMs — Step execution time in milliseconds (optional)
• modelUsed — LLM model identifier if the step ran an LLM block (optional)
• tokens — Token usage object with prompt, completion, total counts (optional)
• costUsd — Estimated cost as a decimal string (e.g., "0.001234"); parse with parseFloat() (optional)
• inputContext — Captured input snapshot (optional; only with trace=true or for failed steps)
• outputContext — Captured output snapshot (optional)
• errorContext — Error details if the step failed (optional)
• inputSizeBytes — Size of input snapshot (optional)
• outputSizeBytes — Size of output snapshot (optional)
• truncated — Whether the snapshot was truncated due to size

Example:

for (const step of trace.steps) {
  console.log(`Step ${step.stepId}:`);
  console.log(`  Attempt: ${step.attempt}`);
  console.log(`  Status: ${step.status}`);
  console.log(`  Duration: ${step.durationMs}ms`);
  if (step.modelUsed) {
    console.log(`  Model: ${step.modelUsed}`);
  }
  if (step.costUsd) {
    console.log(`  Cost: $${parseFloat(step.costUsd).toFixed(6)}`);
  }
  if (step.tokens) {
    console.log(`  Tokens: ${step.tokens.prompt} prompt + ${step.tokens.completion} completion`);
  }
}

TokenBreakdown (Type)

Token usage for a single LLM call. Flat three-field model — no cache fields at the SDK level (cache accounting is rolled into prompt server-side).

Attributes:

• prompt (number): Input tokens sent to the model
• completion (number): Output tokens returned by the model
• total (number): Sum of prompt and completion

Example:

if (step.tokens) {
  const t = step.tokens;
  console.log(`Tokens: ${t.prompt} prompt, ${t.completion} completion, ${t.total} total`);
}

StepAttempts (Type)

Collection of all attempts for a single step (returned when attempt="all").

Attributes:

• stepId (string): The step being inspected
• attempts (StepTrace[]): Array of StepTrace objects, one per attempt, ordered by attempt number

Example:

const history = await flow.run(executionId).stepTrace("my_step", { attempt: "all" });
console.log(`Step ${history.stepId} had ${history.attempts.length} attempts:`);
for (const attempt of history.attempts) {
  console.log(`  Attempt ${attempt.attempt}: ${attempt.status} (${attempt.durationMs}ms)`);
  if (attempt.errorContext) {
    console.log(`    Error: ${JSON.stringify(attempt.errorContext)}`);
  }
}