Skip to content
Get Started

barca history

After verifying that the process or container has stopped, explicitly reconcile an uncertain row with barca history --reconcile RUN_ID --json. This records only that row as interrupted and prints it in the normal history envelope (runs, total: 1, truncated: false); --fields and human output also work. It refuses a proven live owner, a terminal row, an unknown id, and combining --reconcile with --limit or --all. It preserves recorded step counts, successful materializations and artifacts, and leaves unknown end time and duration as null. It does not stop a process. Ordinary history reads still keep an uncertain owner running; reconciliation is your assertion that it stopped. The change is local to the selected environment’s metadata database.

barca history [RUN_ID] [--status S] [--target NAME] [--triggered-by T] [--not-triggered-by T] [--search TEXT] [--since WHEN] [--until WHEN] [--activity] [-l N | --all] [--json|--pretty]
barca history --reconcile RUN_ID

Show recent runs from .barca/metadata.db: run id, command, target, status, step counts and timing. TARGET is the run’s job by function name, all for a run without targets, cut at 24 characters with …. The human table defaults to the 10 most recent; JSON returns every run unless --limit is explicit.

$ barca history
RUN_ID CMD TARGET STATUS STEPS CACHED TIME STARTED
------------------------------------------------------------------------------------------------------
14f1e316840c run notify success 1 2 0.1s 2026-10-21 02:39:25 UTC
14f01f296a75 get country_report,weekly_s… success 0 2 0.0s 2026-10-21 02:39:25 UTC
14f3870e173f get all success 2 0 0.1s 2026-10-21 02:39:25 UTC

Times are UTC. --fields takes run_id, command, files, target, job, status, steps_total, steps_executed, steps_cached, attempts, started_at, finished_at, elapsed_seconds, triggered_by, scheduled_at, schedule_id, client_run_id, failure, failed_node, error, principal, trigger_reason, cancellation. triggered_by says what started the run: manual (a command typed on a machine), api (an HTTP request to barca serve), schedule (a cron tick, with the tick in scheduled_at, RFC 3339 in UTC, and the scheduled node in schedule_id) or client; it is null for runs recorded before barca recorded it. job is the run’s job in full: all, or its resolved node ids sorted and comma-separated (null for runs recorded before 0.29.0); target is the target as typed.

barca history --fields run_id,triggered_by,scheduled_at # what started each run
barca history -l 25 # last 25; human default 10, JSON default every run
barca history --json # {"runs": [...], "total": N, "truncated": bool, "hint"?: "..."}
barca history --fields run_id,status # JSON with only these keys per run

History JSON returns every run unless --limit N is explicit; the human table defaults to 10. When more runs exist than are shown, the JSON has "truncated": true, the total, and a hint; the table prints the same hint as one line on stderr. See Bounded output. Each run’s files is an array of the .py files it was given.

Terminal status and successful/failed step rows commit together. Required database-write failures report an infrastructure error and preserve previous progress/history and run state, which normally remains unfinished. Captured output is written separately after that transaction.

Mid-run database writes commit completed-step rows and their progress count together. Failed batches are retained and retried without waiting for another step; replay does not count a completed step twice. Progress can be absent while the database cannot commit. The final write still records completed results not saved during execution.

Filters combine with AND, and --limit, total and truncated count the runs they keep: --status (comma-separated: success, failed, cancelled, error, running, interrupted; not_successful is every one but success and running), --target NAME (the run’s target or job is that node; runs of every node are left out), --triggered-by (comma-separated: manual, api, schedule, client), --not-triggered-by (the same values, left out: schedule hides the cron ticks and keeps the runs recorded before barca stored what started a run), --search TEXT (the run id, target or job contains the text, whatever its case), --since (30m, 24h, 7d, 2w, an RFC 3339 time or a UTC date) and --until (started before a time, written the same way; with --since, a window). The database keeps the runs, each filter from an index, so a filter costs the runs it keeps and not the runs recorded. A failed run’s row ends with its first failed step and the first line of its error; JSON runs carry it as failure: {node, error} and as the flat failed_node and error (null otherwise), so --fields run_id,failed_node,error needs no nesting.

barca history --status failed --since 24h
barca history --target clean --triggered-by schedule --json
barca history --status not_successful --not-triggered-by schedule
barca history --search daily_report --since 7d
barca history 836fdca186c8 # one run in detail
barca history 836fdca186c8 --json # {run, steps: [...], hint?}

Runs in progress and the last day’s activity

Section titled “Runs in progress and the last day’s activity”

With --status running, each listed run that is in progress says what it is working on now (experimental): a now: executing 3: orders, clean, report · 12 waiting · 240/900 keys line under its row, and in JSON now (running, queued, keys, groups, line), the object the web UI’s run panel shows. The server counts the nodes its workers are executing. A separate CLI process publishes no worker assignments, so its unfinished targets appear in the waiting count.

barca history --activity prints, instead of the runs, how many started in each of the last 24 hours (experimental), by status and by what started them, with each hour’s median time and what most of its unsuccessful runs say went wrong, counted over every recorded run of the window whatever --limit would list. JSON is {"activity": {since, until, triggered_by, not_triggered_by, statuses, search, hours, total, excluded, summary}}; hours are hours of UTC. It takes --status, --triggered-by, --not-triggered-by and --search: --not-triggered-by schedule leaves a schedule’s runs out and says in excluded how many that was.

barca history --status running
barca history --status running --json --fields run_id,now
barca history --activity
barca history --activity --not-triggered-by schedule --json

The full key list and the limits are in status, “Runs in progress and the last day’s activity”.

barca history RUN_ID prints the run’s fields, the steps it recorded (status, attempts, time, peak memory, run hash, artifact path, format and size), and for each failed step its error, traceback, when the worker died how it ended (worker exit: SIGKILL (possibly the OOM killer)), and the last 20 lines it printed (output_tail in JSON, without the traceback). Each step’s JSON has max_rss_bytes, the worker process’s peak resident memory while the step ran (on Linux the step’s own; elsewhere only when the step raised the worker’s peak), and cpu_seconds. Bytes DuckDB spilled to disk are not recorded: DuckDB keeps no total of them. A hint on stderr names barca logs RUN_ID --step STEP --stream stderr. Cached steps are counted in steps_cached, not listed: a run records no row for them. With a server configured, both forms answer from the server; a run only this machine has is an error whose remediation is barca history RUN_ID --local.

The run also says why it executed what it did. In JSON, run.plan_reasons is the record (never_run, new_keys, failed (the last attempt at these inputs failed), code_changed / inputs_changed / env_changed with the component that changed (helper pipelines/common.py:bucket_ltv), a refresh, a missing artifact, a task or a sensor), and explanation is the same in words: why groups the steps by the reason they ran, attempts counts retries apart from each step’s first attempt (29 steps, no retries), targets lists the run’s targets, target_outcomes says what became of each, and a run in progress has progress with an ETA at the rate so far. The table prints it: the attempts on the first line, and after the steps: line a why: line, then each reason with the nodes and steps that ran for it (the first eight of a reason). A group whose nodes each ran one step is counted in nodes, with an example. The reasons are recorded as the run decides each phase, so a run in progress shows the phases decided so far. A run started on a server also shows who asked for it (as token:<name>, principal), the reason: its request gave, and, when cancelled, why (cancelled: ..., cancellation). GET /runs/{run_id} carries the same explanation, which the web UI renders. Details: CLI contract.

why: 5,492 steps ran: 5,000 new partition keys, 31 code changed, 3 input changed
new partition keys
5,000 steps of 1 node: invoices_by_account
code changed
29 nodes: helper billing.py:_n
2 nodes: code
input changed
3 nodes: billing.py:dunning_05
$ barca history 836fdca186c8
run 836fdca186c8 get clean failed 0.1s 1 step, no retries
started 2026-10-22 22:57:27.000 UTC finished 2026-10-22 22:57:27.000 UTC
triggered by api
files pipeline.py
steps: 1 executed (1 failed), 1 cached (cached steps are not listed)
why: 1 step ran: 1 never run
never run
1 node: clean
STEP STATUS ATTEMPTS TIME RUN_HASH ARTIFACT
pipeline.py:clean failed 1 - d64e1b00647e -
pipeline.py:clean failed: ZeroDivisionError: division by zero
Traceback (most recent call last):
File "/srv/pipelines/pipeline.py", line 11, in clean
return [{"id": o["id"], "per_unit": 10 / o["qty"]} for o in orders]
~~~^~~~~~~~~~
ZeroDivisionError: division by zero
hint: barca logs 836fdca186c8 --step clean --stream stderr

A run’s status is running, success, failed, cancelled or interrupted. A run records each step as it finishes, so a running run already counts them in steps_executed, and barca status from another terminal shows them as cached. A run whose process was killed is interrupted (no finished_at); the next barca get reuses the steps it had recorded. A run killed in a container is interrupted too, once a container starts again on the same .barca volume (from 0.20.0; earlier versions left it running). For runs started with 0.20.0 or later, a run stays running whenever barca cannot establish that its process is gone. Earlier runs retain their legacy process-id and host-name checks. See Where Things Live: While a run is going, and after one is killed, and the shared-state limitations.


All commands · Output format · Errors and exit codes