> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.comet.com/docs/opik/_mcp/server.

# 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.

> **Warning**
>
> 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:

```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](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/overview.html).

The reference documentation includes:

* **[Overview & Getting Started](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/overview.html)** - Detailed usage patterns and examples
* **[API Clients](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/clients/index.html)** - Complete method reference for all clients
* **[Data Types](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/objects.html)** - 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