---
title: Query past runs
description: Answer questions about recorded runs with read-only SQL.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

Use the `reeval history` and `reeval query` commands when you want to know how an evaluation did across recorded runs. The examples are two recorded runs of a Vercel AI SDK evaluation. For more information about recording a run, see [Recording](/evaluations/runs/recording).

## Browse history

The `reeval history` command lists the recorded runs, oldest to newest. Each evaluation gets one strip. List the recorded runs:

```bash
npx reeval history
```

Each mark in a strip is one run. The fraction is the runs the evaluation passed over the runs that counted:

```text
  ✓✓    2/2  evals/ai-sdk.eval.ts › streams model text with Vercel AI SDK
  ✓✓    2/2  evals/ai-sdk.eval.ts › retries a failed generation from the model

✓ pass  ✗ fail  ! infra error  ↓ skipped  ○ not gated  · not run  ¦ eval or stack changed
```

To narrow the list, pass part of an evaluation's name as a filter, such as `npx reeval history stream`. The `--limit` flag sets how many runs the strips cover. The `--all` flag adds the runs in the `.reeval/runs` directory that you have not recorded.

## Run a view

The `reeval query` command reads the `.reeval/history.db` file, a SQLite database. reeval reads only the new, changed, and removed records into the database on every query. Each view returns data for one common question. Run a view by its name:

```bash
npx reeval query lift
```

Pass `--json` to print the rows as JSON. To list every view and table with its columns, run `npx reeval query` with no argument. The `--schema` flag prints the same list. For more information about each view's columns, see [Query views](/reference/query-views).

## Write SQL

The `reeval query` command takes one `SELECT` statement in quotes. Count each evaluation's outcomes across runs from the `eval_trend` view:

```bash
npx reeval query "SELECT eval_key, outcome, COUNT(*) AS n
  FROM eval_trend GROUP BY eval_key, outcome"
```

The table clips a long text cell with `…`:

```text
eval_key                                                      outcome  n
evals/ai-sdk.eval.ts › retries a failed generation from…      pass     2
evals/ai-sdk.eval.ts › streams model text with Vercel AI SDK  pass     2
```

The database is read-only. The `reeval query` command runs one statement at a time. To rebuild the database from the records, pass `--rebuild`. For more information about reading the same views from a coding agent, see [History MCP server](/reference/history-mcp-server).

## Read one run

The `--run` flag binds a run id to the `:run` parameter in the statement. Pass `last` to bind the newest run. Read the last run's evaluations:

```bash
npx reeval query "SELECT name, outcome FROM evals
  WHERE run_id = :run" --run last
```

The statement prints one row for each evaluation in that run:

```text
name                                        outcome
retries a failed generation from the model  pass
streams model text with Vercel AI SDK       pass
```

With a view or table name instead of a statement, such as `npx reeval query evals --run last`, the `--run` flag keeps that run's rows only.

For a runnable project, see [`with-query`](https://github.com/invertase/reeval/tree/main/examples/with-query). For more information about every flag, see [`reeval history`](/reference/cli#reeval-history) and [`reeval query`](/reference/cli#reeval-query). For more information about following an evaluation's trend from a recording profile onward, see [Track results](/evaluations/recipes/track-past-runs).