REST API Client

The Opik Python SDK includes a complete REST API client that provides direct access to all Opik platform functionality. This low-level client is available through the rest_client property and is useful for advanced operations, custom integrations, and scenarios where the high-level SDK doesn't provide the needed functionality.

Accessing the REST Client

The REST client is accessible through any Opik instance:

Python

import opik

# Initialize Opik client
client = opik.Opik()

# Access the REST API client
rest_client = client.rest_client

# Now you can use any of the available client methods
traces = rest_client.traces.search_traces(project_name="my-project")

Available Clients

The REST API is organized into functional client modules:

Core Resources

traces - Manage traces and their lifecycle
spans - Manage spans within traces
datasets - Manage datasets and dataset items
experiments - Manage experiments and results
projects - Manage projects and project settings

Feedback & Evaluation

feedback_definitions - Define feedback score types
automation_rule_evaluators - Set up automated evaluation rules
optimizations - Run optimization experiments

Content & Assets

prompts - Manage prompt templates and versions
attachments - Handle file attachments for traces and spans

System & Configuration

check - System health and access verification
workspaces - Workspace management
llm_provider_key - API key management for LLM providers
service_toggles - Feature flag management
system_usage - Usage metrics and monitoring

Integrations

chat_completions - Chat completion endpoints
open_telemetry_ingestion - OpenTelemetry data ingestion
guardrails - Content validation and safety checks

Common Usage Patterns

Working with Traces

Python

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

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

# Add feedback to a trace
client.rest_client.traces.add_trace_feedback_score(
    id="trace-id",
    name="accuracy",
    value=0.95,
    source="manual"
)

Managing Datasets

Python

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

# Create a new dataset
dataset = client.rest_client.datasets.create_dataset(
    name="evaluation-dataset",
    description="Dataset for model evaluation",
    project_name="my-project"
)

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

Running Experiments

Python

# Create an experiment linked to a dataset
experiment = client.rest_client.experiments.create_experiment(
    name="model-comparison",
    dataset_name="evaluation-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": {"prediction": "model output"},
        "feedback_scores": [
            {"name": "accuracy", "value": 0.8}
        ]
    }]
)

Response Types and Pagination

Most list operations return paginated responses with a consistent structure:

Python

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

# Access the response 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:

Python

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")
    elif e.status_code == 403:
        print("Access denied")
    else:
        print(f"API error: {e.status_code} - {e.body}")

When to Use the REST API

Consider using the REST API client when you need to:

Advanced Filtering: Complex search operations with multiple filters
Batch Operations: Process large amounts of data efficiently
Custom Integrations: Build tools that integrate with external systems
Raw Data Access: Work directly with API responses for specific use cases
Unsupported Operations: Access functionality not available in the high-level SDK

Complete API Reference

For comprehensive documentation of all REST API methods, parameters, and response types, see the complete REST API Reference.

The reference documentation includes:

Overview & Getting Started - Detailed usage patterns and examples
API Clients - Complete method reference for all clients
Data Types - Response models and data structures

Best Practices

Use High-Level SDK First: Try the main SDK APIs before resorting to REST client
Handle Pagination: Always implement proper pagination for list operations
Error Handling: Implement robust error handling for network and API errors
Rate Limiting: Be mindful of API rate limits for batch operations
Version Compatibility: Test thoroughly when upgrading SDK versions