Save and export datasets

Use this guide after a workflow has recorded evidence. The examples use dataset drafts, version 1, from that chapter. Run commands from your repository root. No model calls or running Studio server are needed.

1. Find the examples

bunx laufwerk@0.0.1-alpha.14 datasets list --json
bunx laufwerk@0.0.1-alpha.14 datasets examples drafts --version 1 --json

Lists return items and nextCursor. Copy an exampleId from the examples list:

bunx laufwerk@0.0.1-alpha.14 evidence show EXAMPLE_ID --descendants --json
bunx laufwerk@0.0.1-alpha.14 evidence logs EXAMPLE_ID --descendants --json

Replace EXAMPLE_ID with that ID. The detail contains the example, child stages and a page of records. Each feedback record's subject identifies the artifact reviewed. An example can still be running while its workflow waits for a person.

In Studio, open Datasets, choose a dataset/version, then an example. Inspect its stages, records and revisions; follow its run link for execution history.

2. Freeze a snapshot

bunx laufwerk@0.0.1-alpha.14 datasets snapshot drafts --version 1 --name baseline-v1 --json

Keep the returned snapshotId. A snapshot freezes the matching examples' input, result, lifecycle and related evidence. It also includes descendant stages and record references needed to explain the selected work. Later feedback does not change an existing snapshot.

The selection covers the full matching set, not just a page. Select one dataset version explicitly. Let the relevant work finish first if your comparison needs complete outcomes; snapshotting does not wait for unfinished runs.

Studio's Save snapshot action offers the same operation for the selected dataset and returns an Open saved snapshot link.

3. Export JSON

bunx laufwerk@0.0.1-alpha.14 datasets export SNAPSHOT_ID --output ./analysis/drafts-v1 --include-logs

Replace SNAPSHOT_ID. The command writes manifest.json inside the destination and refuses to overwrite an existing manifest. Choose a new directory for another export. Omit --include-logs when records and provenance are sufficient.

What the manifest contains

Field	Meaning
`formatVersion`	Export format version, currently `1`
`snapshotId`, `name`, `createdAt`	Saved snapshot identity and creation time
`selection`	Dataset/version and selection filters
`selectedExampleIds`	Examples directly selected by the query
`examples`	Selected work and its included descendants, with frozen input/result/lifecycle
`records`	Artifact, feedback and other records with contracts and links
`provenance`	Invocation identities needed to explain record ownership
`sourceRuns`	Run IDs, workflow names, saved bundle digests and encoded inputs
`eventCutoff`	Last event ID included by the snapshot
`replay`	`requires-adapter`: your code must select inputs and restore the environment
`logs`, `logCompleteness`	Present when requested; retained events through the cutoff and their limits

Root examples with descendants can include their run's retained history. Child-only logs include attributable events, not unrelated sibling work. logCompleteness remains partial: hidden provider reasoning, unrecorded external actions and truncated payloads cannot be recovered.

This is an analysis export, not a database backup or a portable suspended execution. It does not reconstruct files or external services you never captured. Keep source snapshots or immutable artifacts when the input depends on them.

4. Prepare a fair comparison

Map the original allowed inputs into your benchmark. Keep historical accepted outputs and reviews in the evaluator's reference, not in the candidate's prompt. Record the snapshot ID and benchmark configuration so you can explain the comparison later.

Pagination and filters

List queries support --limit from 1 to 200 and --cursor. When nextCursor is non-null, pass it to the same command with the same filters and limit. Cursors freeze membership and evidence cutoffs, but a running example's outcome can still change. Use a snapshot when outcomes must also stay fixed.

Use --ancestor-dataset NAME to restrict child datasets to a parent's lineage, or --example ID --descendants to select one example tree. Outside a consumer, add --project PROJECT_ID. See the full command reference.

Retention and ownership

Normal prune protects runs that contain dataset membership or evidence records, including their bundles and history. Alpha.14 has no dataset deletion/unpin command. Retained evidence therefore continues to consume disk even when its run is completed and old enough for ordinary pruning.

Preserve databases, workspaces and external artifacts separately when making a backup or moving to another runtime. Protect exports according to the data they contain; recording a case does not redact its contents.

Reference: Dataset and Evidence · HTTP evidence endpoints