For AI agents: the complete documentation index is available at /runlab/llms.txt, the full documentation bundle is available at /runlab/llms-full.txt, and this page is available as Markdown at /runlab/how-to/query-runs.md.

Query Runs

Use run list for a short glance at recent Runs, query run to select or aggregate Runs, and run get for one complete persisted Run record. Querying never starts a Run, refreshes State, repairs a record, or changes the database.

Discover the contract first

Do not guess relation or column names. The schema is bundled with the same binary that executes the query:

runlab schema list
runlab schema get runs

The public SQL surface contains runs and run_deletions. runs exposes accepted caller metadata, Initial Image identity, lifecycle, primary Program timestamps and durations, retained stdout/stderr byte counts, process result, timeout/cancellation facts, and the Final Image digest. It deliberately omits complete Run input, captured stream content, errors, and complete Final Environment descriptors; read those with runlab run get RUN_ID. run_deletions preserves the identity, deletion time, and operation identity after a Run Record is removed.

initial_image_name is the Catalog name used when RunLab accepted the Run. It is NULL when the caller selected the Image by digest or when an older record predates this accepted fact. initial_image_digest is the immutable content identity. labels is a JSON object whose keys and values are caller-defined strings.

accepted_at and terminal_at are exact RFC 3339 text facts. Do not range-filter them by lexical comparison: equivalent offsets and fractional-second boundaries do not sort reliably as text. Use terminal_unix_seconds for range selection and keep terminal_at in the result for review. terminal_unix_seconds is millisecond-rounded by SQLite and is not an exact replacement for terminal_at.

Select Runs with ordinary SQL

Find recent SWE-bench Runs made with the Pi Image:

runlab query run --stdin <<'SQL'
SELECT run_id, accepted_at, description, primary_exit_code
FROM runs
WHERE initial_image_name = 'pi'
  AND json_extract(labels, '$.suite') = 'swe-bench'
ORDER BY accepted_at DESC
LIMIT 10;
SQL

Select terminal Runs older than one day without comparing timestamp text:

runlab query run --stdin <<'SQL'
SELECT run_id, terminal_at
FROM runs
WHERE lifecycle = 'terminal'
  AND terminal_unix_seconds < unixepoch('now', '-1 day', 'subsec')
ORDER BY terminal_unix_seconds ASC, run_id ASC;
SQL

Count outcomes without returning every Run:

runlab query run \
  "SELECT primary_process_kind, primary_exit_code, COUNT(*) AS runs FROM runs GROUP BY primary_process_kind, primary_exit_code"

Compare execution and platform boundary time without loading complete Run Records:

runlab query run --stdin <<'SQL'
SELECT
  run_id,
  accepted_to_primary_start_ms,
  primary_duration_ms,
  primary_end_to_terminal_ms,
  primary_stdout_bytes,
  primary_final_image_digest
FROM runs
WHERE lifecycle = 'terminal'
ORDER BY accepted_at DESC
LIMIT 20;
SQL

Use --file QUERY.sql for a checked-in or generated query. Inline SQL, --file, and --stdin are mutually exclusive.

Treat bounds as part of the result

Every query is bounded by row count, cell bytes, total serialized row bytes, and time. The JSON result states complete: false with incomplete_reason: "row_limit" or "output_budget" when output was cut off, and reports cells_truncated when individual values were shortened. Increase the corresponding bound only when the workflow needs more data; aggregate or narrow before returning large row sets.

Only one read-only statement against public Relations is allowed. Private storage tables, schema tables, attached databases, writes, and extension loading are not part of the interface.