Upgrading to Opik 2.0

Opik 2.0 reorganized the product around projects. A project now maps to a single agent or app and is the home for everything related to it. This page explains what changed, how to work with the SDK from now on, where your existing data was moved, and how to relocate it if it didn't land where you want.

What changed: projects are the home for everything

In Opik 1.x, traces and threads lived in projects, but datasets, prompts, experiments, optimizations, automation rules, alerts, and dashboards were workspace-wide. In 2.0, a project maps to one agent or app and scopes all of its work.

These entities are now scoped to a project:

Datasets and test suites
Experiments and optimizations
Prompts
Automation rules — in 1.x a rule could target multiple projects; in 2.0 a rule is scoped to a single project
Alerts
Dashboards — workspace-level dashboards remain supported through a dedicated view

You also get a workspace-level project selector, project-scoped navigation across the app, a unified Logs page (threads, traces, and spans in one place), and a redesigned trace view. The result is a focused view of everything tied to a single agent. See the 2.0 release notes for the full picture.

How to work now

Upgrade to the Opik SDK 2.0 or later:

Bash

pip install --upgrade "opik>=2.0.0"

Bash

npm install opik@latest

The main change is to pass the project to the methods you call. The dataset, test suite, prompt, and experiment APIs all take a project_name (projectName in TypeScript). Omit it and Opik uses the project from the OPIK_PROJECT_NAME environment variable or your config, falling back to Default Project.

All snippets below assume a client:

Python

import opik

client = opik.Opik()

TypeScript

import { Opik } from "opik";

const client = new Opik();

Datasets

Python

client.create_dataset(name="qa-pairs", project_name="my-agent")
client.get_dataset(name="qa-pairs", project_name="my-agent")
client.get_or_create_dataset(name="qa-pairs", project_name="my-agent")
client.get_datasets(project_name="my-agent")
client.delete_dataset(name="qa-pairs", project_name="my-agent")
client.get_dataset_experiments(dataset_name="qa-pairs", project_name="my-agent")

TypeScript

await client.createDataset("qa-pairs", "QA pairs", "my-agent");
await client.getDataset("qa-pairs", "my-agent");
await client.getOrCreateDataset("qa-pairs", "QA pairs", "my-agent");
await client.getDatasets(100, "my-agent");
await client.deleteDataset("qa-pairs", "my-agent");
await client.getDatasetExperiments("qa-pairs", 100, "my-agent");

Test suites

Python

client.create_test_suite(name="qa-suite", project_name="my-agent")
client.get_test_suite(name="qa-suite", project_name="my-agent")
client.get_or_create_test_suite(name="qa-suite", project_name="my-agent")
client.get_test_suites(project_name="my-agent")
client.delete_test_suite(name="qa-suite", project_name="my-agent")
client.get_test_suite_experiments(name="qa-suite", project_name="my-agent")

TypeScript

await client.createTestSuite({ name: "qa-suite", projectName: "my-agent" });
await client.getTestSuite("qa-suite", "my-agent");
await client.getOrCreateTestSuite({ name: "qa-suite", projectName: "my-agent" });
await client.getTestSuites(1000, "my-agent");
await client.deleteTestSuite("qa-suite", "my-agent");
await client.getTestSuiteExperiments("qa-suite", 100, "my-agent");

Prompts

Python

client.create_prompt(name="assistant", prompt="Answer: {{question}}", project_name="my-agent")
client.create_chat_prompt(
    name="assistant-chat",
    messages=[{"role": "user", "content": "{{question}}"}],
    project_name="my-agent",
)
client.get_prompt(name="assistant", project_name="my-agent")
client.get_chat_prompt(name="assistant-chat", project_name="my-agent")
client.get_prompt_history(name="assistant", project_name="my-agent")
client.get_chat_prompt_history(name="assistant-chat", project_name="my-agent")
client.get_all_prompts(name="assistant", project_name="my-agent")
client.search_prompts(project_name="my-agent")

TypeScript

await client.createPrompt({
  name: "assistant",
  prompt: "Answer: {{question}}",
  projectName: "my-agent",
});
await client.createChatPrompt({
  name: "assistant-chat",
  messages: [{ role: "user", content: "{{question}}" }],
  projectName: "my-agent",
});
await client.getPrompt({ name: "assistant", projectName: "my-agent" });
await client.getChatPrompt({ name: "assistant-chat", projectName: "my-agent" });

Experiments

An experiment — and every trace, span, and feedback score it produces — always lands in the same project as the dataset it runs against. You don't scope an experiment separately: put the dataset in the project you want, and each run of it follows. This holds whether you call opik.evaluate(...) or create the experiment directly.

Python

# project_name must be the dataset's project — the experiment and its data land there
client.create_experiment(dataset_name="qa-pairs", name="run-1", project_name="my-agent")
client.get_experiment_by_name(name="run-1", project_name="my-agent")
client.get_experiments_by_name(name="run-1", project_name="my-agent")

TypeScript

await client.createExperiment({
  datasetName: "qa-pairs",
  name: "run-1",
  projectName: "my-agent", // the dataset's project
});
await client.getExperiment("run-1", "my-agent");
await client.getExperimentsByName("run-1", "my-agent");

Where your existing data lands

When your workspace is upgraded to 2.0, your workspace-scoped 1.x data — datasets, prompts, experiments, and optimizations — is moved into projects.

Each item is placed in the project Opik can infer from the runs that used it. When there's nothing to infer from (no associated runs, or the original project had been deleted), the item is placed in your Default Project.

So if you don't see a dataset, prompt, or experiment where you expected it, check the project its traces and experiments belong to — and check Default Project.

Moving data to a different project

If something landed in a project you don't want, you can move it with the opik migrate CLI. It relocates a dataset (with its experiments, traces, and spans) or a prompt (with its full version history) into another project.

Bash

# Move a dataset that landed in Default Project into your agent's project
opik migrate dataset "qa-pairs" --to-project="my-agent"

Preview any move with --dry-run first. See Migrate data for the full guide — what's copied, the options, and troubleshooting.