For AI agents: the complete documentation index is at llms.txt. Remove the trailing slash from a page URL and append .md to read its Markdown version. For the docs home, use index.md.

Inspecting Runs

Every run is a row, so you inspect runs with the same queries you use for the rest of your data. This page shows how to read a run's state from its row, find runs that need attention, keep a history of each run's attempts, and trace each attempt with OpenTelemetry.

Read a run's state

The columns the mixin adds tell you where a run is:

The run isWhen
Schedulednext_step is set and wake_at is in the future.
Duenext_step is set and wake_at has passed.
Runningclaimed_until is in the future.
Retryingnext_step is set and attempts is above zero. last_error holds the latest error.
Waiting for an eventwaiting_for is set. wake_at is the deadline, if there is one.
Waiting for its childrenchildren_left is above zero.
Finishednext_step and waiting_for are both NULL, and last_error is NULL.
Failednext_step and waiting_for are both NULL, and last_error is set.

A run that waits for an event with a deadline also has next_step set, to its timeout step, so check waiting_for before next_step.

These columns describe the engine's view of the run. For your app's view, such as "awaiting approval" or "shipped", keep a status column of your own and set it in your steps. It reads better in your UI, and it can tell apart outcomes that look the same to the engine, such as a run that was cancelled and one that finished.

Find runs that need attention

Query the mixin's columns with Workflow.by or with your own sessions.

Runs that gave up after their last retry:

failed = await Invoice.by(
    Invoice.next_step.is_(None),
    Invoice.waiting_for.is_(None),
    Invoice.last_error.is_not(None),
).all()

Runs that are failing right now and will retry:

retrying = await Invoice.by(Invoice.attempts > 0, Invoice.next_step.is_not(None)).all()

Runs that have been due for more than ten minutes without a worker taking them:

from datetime import timedelta

from sqlalchemy import func, or_

stuck = await Invoice.by(
    Invoice.next_step.is_not(None),
    Invoice.wake_at < func.now() - timedelta(minutes=10),
    or_(Invoice.claimed_until.is_(None), Invoice.claimed_until < func.now()),
).all()

A due run that no worker takes usually means its step is in a lane that no running worker serves, its group is at its limit, or no worker is running at all.

To retry failed runs once you have fixed the cause, use run.

Keep an attempt history

The row shows where a run is now. To see how it got there, map an attempt history table onto your base:

from reflex_workflow import AttemptLog


class WorkflowAttempt(Base, AttemptLog):
    __tablename__ = "workflow_attempt"

Generate a migration, and the engine writes a row for each attempt whose result it commits, in every workflow. Read a run's history, most recent first, with history:

for attempt in await invoice.history():
    print(
        attempt.step, attempt.attempt, attempt.outcome, attempt.error, attempt.took_ms
    )

history returns the 50 most recent attempts by default; pass limit to change that. Each row has these columns:

ColumnHolds
workflowThe workflow's table name.
runThe run's primary key, as a JSON list.
stepThe step that ran.
attemptWhich attempt of that step it was, starting at 1.
outcomeok, retry if the step failed and will be retried, or failed if it failed for the last time.
errorThe error, for an attempt that failed.
took_msHow long the step took, in milliseconds.
finished_atWhen the attempt finished.

The engine writes each history row in the same transaction as the step's result, so the history records exactly the outcomes that changed the run. It isn't a log of every execution: an attempt whose result was discarded, because the run had moved on or its worker stopped before committing, leaves no row, even if its step ran and called other services.

The engine never reads this table, so you can prune it on any schedule, for example with a scheduled workflow that deletes old rows. An app can map one history table, and if you don't map one, the engine writes no history and history returns an empty list.

Trace step attempts

With reflex-otel installed and instrumented, every attempt of a step is an OpenTelemetry span. There is nothing to configure in reflex-workflow: ReflexInstrumentor().instrument() turns the spans on, and without it the engine doesn't import opentelemetry at all.

Each span is named <table>.<step>, such as invoice.charge, and starts a new trace, because a step runs on whichever worker claims it, possibly long after it was scheduled. Instead of nesting under the code that scheduled the step, the span links to it: the event handler or request that called start, run, or deliver, or the step that returned it. Your tracing backend can follow those links from a button click to every step it led to.

A span carries these attributes:

AttributeHolds
reflex.workflow.tableThe workflow's table name.
reflex.workflow.stepThe step that ran.
reflex.workflow.attemptWhich attempt of that step it was, starting at 1.
reflex.workflow.laneThe step's lane, if it has one.
reflex.workflow.outcomeok, retry, or failed, as in the attempt history, or fenced if the result was discarded because the run had moved on.
error.typeThe exception's type, for an attempt that raised.

An attempt that raised also records the exception on its span, and a retry or failed outcome marks the span as an error. Unlike the attempt history, spans also cover attempts whose result was discarded. Step arguments and row columns are never recorded, beyond what an exception's message quotes.