For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Copy to LLMGithubGo to App
DocumentationIntegrationsBuilding Self-Improving AgentsSelf-hosting OpikSDK & API reference
DocumentationIntegrationsBuilding Self-Improving AgentsSelf-hosting OpikSDK & API reference
  • Getting Started
    • Home
    • Quickstart
    • Upgrading to Opik 2.0
    • Ollie Agent
    • FAQ
    • Changelog
  • Observability
    • Overview
    • Getting started
    • Concepts
    • Debugging agents with Ollie and Opik Connect
      • Log traces
      • Log conversations
      • Log media & attachments
      • Log Agent Graphs
      • Log distributed traces
      • Log user feedback
      • Cost tracking
      • Export data
      • Migrate data
      • SDK configuration
      • Offline fallback and message replay
  • Development
    • Overview
    • Agent playground
    • Prompt playground
  • Evaluation
    • Overview
    • Getting started
    • Concepts
  • Production
  • Administration
    • Overview
    • Roles and Permissions
  • Contributing
    • Contribution Overview
LogoLogo
Copy to LLMGithubGo to App
On this page
  • Options
  • Previewing a migration
  • opik migrate dataset
  • What gets copied
  • What happens when you run it
  • What is not copied
  • Examples
  • opik migrate prompt
  • What gets copied
  • Examples
  • Troubleshooting
ObservabilityAdvanced

Migrate data

Was this page helpful?
Previous

SDK configuration

Next
Built with

opik migrate moves an entity — and everything attached to it — from one project to another in the same workspace. It copies the entity’s full version history and its related data into the destination project.

It has two subcommands:

  • opik migrate dataset — a dataset (or test suite) with its full version history, plus the experiments, traces, spans, feedback scores, assertion results, comments, and optimizations attached to it.
  • opik migrate prompt — a prompt and its full version history.

Use it to consolidate or re-home an entity and its history under a different project.

These commands move data between projects in a single workspace. To move data between separate Opik installations or environments, use opik export / opik import instead.

The migration renames the source to <name>_v1 and gives the destination the original name. Preview with --dry-run first to see exactly what will change.

Options

The --workspace and --api-key flags go on the opik migrate group, before the subcommand. The rest are shared by both dataset and prompt.

FlagDefaultDescription
NAME (argument)—Exact name of the source dataset or prompt to migrate.
--to-project— (required)Destination project. It must already exist — create it first if needed.
--from-projectwhole workspaceOptional hint for which project the source lives in. Omit to search the whole workspace.
--dry-runfalsePreview what would happen without making any changes. See Previewing a migration.
--workspace (group flag)OPIK_WORKSPACE → ~/.opik.config → defaultWorkspace to operate in.
--api-key (group flag)OPIK_API_KEY → ~/.opik.configOpik API key.

Previewing a migration

Add --dry-run to any migration to see exactly what it would do without changing anything — nothing is renamed and nothing is copied. The command resolves the source, prints the plan it would run step by step, then exits.

$opik migrate dataset "MyDataset" --to-project="production" --dry-run

Use the preview to confirm the source resolved to the right entity and that the destination project is correct. When the plan looks right, run the same command again without --dry-run to apply it.

opik migrate dataset

$opik migrate dataset NAME --to-project=DESTINATION_PROJECT [OPTIONS]

NAME is the exact name of the source dataset. Both plain datasets and test suites are supported. Preview with --dry-run before applying.

What gets copied

EntityWhat comes across
DatasetName, description, visibility, tags, and type (dataset or test suite).
Version historyEvery version, in order, with the same items and ordering as the source.
ItemsEach item’s data, description, tags, evaluators, execution policy, and source.
ExperimentsName, type, evaluation method, tags, and metadata.
TracesInput, output, metadata, tags, timing, thread, errors, and environment.
SpansThe full span tree, inputs and outputs, metadata, model, provider, usage, cost, tags, and errors.
Feedback scoresOn traces and spans.
Assertion resultsFor test suites.
CommentsOn traces and spans.
OptimizationsOptimizations linked to the dataset, with their experiments re-linked on the destination.

What happens when you run it

The same steps appear in the --dry-run plan:

#StepWhat it does
1Rename sourceRenames the source to <name>_v1 to free up its name.
2Create destinationCreates the dataset under --to-project with the original name.
3Replay versionsReplays every version onto the destination, in order.
4Copy optimizationsRecreates any optimizations linked to the dataset.
5Copy experimentsRecreates the experiments, along with their traces and spans.

What is not copied

  • Prompt snapshots on experiments — migrate prompts separately with opik migrate prompt.
  • Attachments on traces and spans — files like images and audio are not copied.
  • Thread tags, status, feedback scores, and comments — the traces themselves (including their environment) do come across, but these thread-level fields don’t yet.

Examples

$# Migrate a dataset (with its experiments, traces, and spans)
$opik migrate dataset "MyDataset" --to-project="production"
$
$# Preview without making any changes
$opik migrate dataset "MyDataset" --to-project="production" --dry-run
$
$# Tell it which project the source is in
$opik migrate dataset "MyDataset" --to-project="production" --from-project="staging"

opik migrate prompt

$opik migrate prompt NAME --to-project=DESTINATION_PROJECT [OPTIONS]

NAME is the exact name of the source prompt. This subcommand migrates the prompt and its version history only — it does not copy experiments, traces, or spans. Preview with --dry-run before applying.

What gets copied

  • Prompt — name, description, tags, and template structure.
  • Version history — every version, oldest first, with its template, metadata, type, change description, and tags.
  • Commit hashes — each version’s commit hash is preserved, so the history matches the source exactly.

It renames the source to <name>_v1, creates the destination prompt under --to-project, and replays every version.

Examples

$# Migrate a prompt and its full version history
$opik migrate prompt "MyPrompt" --to-project="production"
$
$# Preview without making any changes
$opik migrate prompt "MyPrompt" --to-project="production" --dry-run

Troubleshooting

  • Name already used — the rename target <name>_v1 already exists. Rename or delete the conflicting entity and re-run:

    Cannot rename source to 'MyDataset_v1' — that name is already used by a dataset in project 'staging'. Rename or delete the conflicting dataset and re-run.