REST API Overview¶

The Opik SDK provides direct access to the underlying REST API client through the rest_client property. This allows advanced users to make direct API calls when needed, providing full access to all Opik platform functionality.

Warning

The REST client is not guaranteed to be backward compatible with future SDK versions. While it provides a convenient way to use the current REST API of Opik, it’s not considered safe to heavily rely on its API as Opik’s REST API contracts may change.

When to Use the REST API¶

The REST API is useful when you need to:

Perform operations not available in the high-level SDK
Build custom integrations or tools
Access advanced filtering or querying capabilities
Implement batch operations for performance
Work with raw API responses for specific use cases

Getting Started¶

To access the REST client, first create an Opik instance and then use the rest_client property:

import opik

# Initialize Opik client
client = opik.Opik()

# Access REST API through the rest_client property
rest_client = client.rest_client

Basic Examples¶

Here are some common patterns for using the REST API:

Working with Traces

# Get a specific trace
trace = client.rest_client.traces.get_trace_by_id("trace-id")

# Search for traces with filters
traces = client.rest_client.traces.search_traces(
    project_name="my-project",
    filters=[{
        "field": "name",
        "operator": "contains",
        "value": "important"
    }],
    max_results=100
)

Managing Datasets

# List all datasets
datasets = client.rest_client.datasets.find_datasets(
    page=0,
    size=20
)

# Create a new dataset
dataset = client.rest_client.datasets.create_dataset(
    name="my-dataset",
    description="A test dataset"
)

# Add items to the dataset
items = [
    {
        "input": {"question": "What is AI?"},
        "expected_output": {"answer": "Artificial Intelligence"}
    }
]
client.rest_client.datasets.create_or_update_dataset_items(
    dataset_id=dataset.id,
    items=items
)

Running Experiments

# Create an experiment
experiment = client.rest_client.experiments.create_experiment(
    name="my-experiment",
    dataset_name="my-dataset"
)

# Add experiment results
client.rest_client.experiments.create_experiment_items(
    experiment_id=experiment.id,
    items=[{
        "dataset_item_id": "item-id",
        "trace_id": "trace-id",
        "output": {"result": "success"}
    }]
)

Response Types and Pagination¶

Most list operations return paginated results with a consistent structure:

# Example paginated response structure
response = client.rest_client.datasets.find_datasets(page=0, size=10)

# Access the data
datasets = response.content  # List of dataset objects
total_count = response.total  # Total number of items
current_page = response.page  # Current page number
page_size = response.size     # Items per page

Error Handling¶

The REST API raises specific exceptions for different error conditions:

from opik.rest_api.core.api_error import ApiError

try:
    trace = client.rest_client.traces.get_trace_by_id("invalid-id")
except ApiError as e:
    if e.status_code == 404:
        print("Trace not found")
    else:
        print(f"API error: {e.status_code} - {e.body}")

Next Steps¶

Browse the REST API Clients for detailed API reference
See REST API Objects for data type documentation
Check the main SDK documentation for higher-level operations