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.

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

Accessing the REST Client

The REST client is accessible through any Opik instance:

1import opik
2
3# Initialize Opik client
4client = opik.Opik()
5
6# Access the REST API client
7rest_client = client.rest_client
8
9# Now you can use any of the available client methods
10traces = 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
2trace = client.rest_client.traces.get_trace_by_id("trace-id")
3
4# Search traces with advanced filters
5traces = 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
16client.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
2datasets = client.rest_client.datasets.find_datasets(
3 page=0,
4 size=20
5)
6
7# Create a new dataset
8dataset = client.rest_client.datasets.create_dataset(
9 name="evaluation-dataset",
10 description="Dataset for model evaluation"
11)
12
13# Add items to the dataset
14items = [
15 {
16 "input": {"question": "What is machine learning?"},
17 "expected_output": {"answer": "A subset of AI..."}
18 }
19]
20client.rest_client.datasets.create_or_update_dataset_items(
21 dataset_id=dataset.id,
22 items=items
23)

Running Experiments

1# Create an experiment linked to a dataset
2experiment = client.rest_client.experiments.create_experiment(
3 name="model-comparison",
4 dataset_name="evaluation-dataset"
5)
6
7# Add experiment results
8client.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
2response = client.rest_client.datasets.find_datasets(page=0, size=10)
3
4# Access the response data
5datasets = response.content # List of dataset objects
6total_count = response.total # Total number of items
7current_page = response.page # Current page number
8page_size = response.size # Items per page

Error Handling

The REST API raises specific exceptions for different error conditions:

1from opik.rest_api.core.api_error import ApiError
2
3try:
4 trace = client.rest_client.traces.get_trace_by_id("invalid-id")
5except 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:

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