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:
Available Clients
The REST API is organized into functional client modules:
Core Resources
traces
- Manage traces and their lifecyclespans
- Manage spans within tracesdatasets
- Manage datasets and dataset itemsexperiments
- Manage experiments and resultsprojects
- Manage projects and project settings
Feedback & Evaluation
feedback_definitions
- Define feedback score typesautomation_rule_evaluators
- Set up automated evaluation rulesoptimizations
- Run optimization experiments
Content & Assets
prompts
- Manage prompt templates and versionsattachments
- Handle file attachments for traces and spans
System & Configuration
check
- System health and access verificationworkspaces
- Workspace managementllm_provider_key
- API key management for LLM providersservice_toggles
- Feature flag managementsystem_usage
- Usage metrics and monitoring
Integrations
chat_completions
- Chat completion endpointsopen_telemetry_ingestion
- OpenTelemetry data ingestionguardrails
- Content validation and safety checks
Common Usage Patterns
Working with Traces
Managing Datasets
Running Experiments
Response Types and Pagination
Most list operations return paginated responses with a consistent structure:
Error Handling
The REST API raises specific exceptions for different error conditions:
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