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:

1
import opik
2
3
# Initialize Opik client
4
client = opik.Opik()
5
6
# Access the REST API client
7
rest_client = client.rest_client
8
9
# Now you can use any of the available client methods
10
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

1
# Get a specific trace by ID
2
trace = client.rest_client.traces.get_trace_by_id("trace-id")
3
4
# Search traces with advanced filters
5
traces = client.rest_client.traces.search_traces(
6
    project_name="my-project",
7
    filters=[{
8
        "field": "name",
9
        "operator": "contains",
10
        "value": "important"
11
    }],
12
    max_results=100
13
)
14
15
# Add feedback to a trace
16
client.rest_client.traces.add_trace_feedback_score(
17
    id="trace-id",
18
    name="accuracy",
19
    value=0.95,
20
    source="manual"
21
)

Managing Datasets

1
# List all datasets with pagination
2
datasets = client.rest_client.datasets.find_datasets(
3
    page=0,
4
    size=20
5
)
6
7
# Create a new dataset
8
dataset = client.rest_client.datasets.create_dataset(
9
    name="evaluation-dataset",
10
    description="Dataset for model evaluation",
11
    project_name="my-project"
12
)
13
14
# Add items to the dataset
15
items = [
16
    {
17
        "input": {"question": "What is machine learning?"},
18
        "expected_output": {"answer": "A subset of AI..."}
19
    }
20
]
21
client.rest_client.datasets.create_or_update_dataset_items(
22
    dataset_id=dataset.id,
23
    items=items
24
)

Running Experiments

1
# Create an experiment linked to a dataset
2
experiment = client.rest_client.experiments.create_experiment(
3
    name="model-comparison",
4
    dataset_name="evaluation-dataset"
5
)
6
7
# Add experiment results
8
client.rest_client.experiments.create_experiment_items(
9
    experiment_id=experiment.id,
10
    items=[{
11
        "dataset_item_id": "item-id",
12
        "trace_id": "trace-id",
13
        "output": {"prediction": "model output"},
14
        "feedback_scores": [
15
            {"name": "accuracy", "value": 0.8}
16
        ]
17
    }]
18
)

Response Types and Pagination

Most list operations return paginated responses with a consistent structure:

1
# Example paginated response
2
response = client.rest_client.datasets.find_datasets(page=0, size=10)
3
4
# Access the response data
5
datasets = response.content    # List of dataset objects
6
total_count = response.total   # Total number of items
7
current_page = response.page   # Current page number
8
page_size = response.size      # Items per page

Error Handling

The REST API raises specific exceptions for different error conditions:

1
from opik.rest_api.core.api_error import ApiError
2
3
try:
4
    trace = client.rest_client.traces.get_trace_by_id("invalid-id")
5
except ApiError as e:
6
    if e.status_code == 404:
7
        print("Trace not found")
8
    elif e.status_code == 403:
9
        print("Access denied")
10
    else:
11
        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

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