Projects Client

The Projects client provides methods for managing projects in the Opik platform.

class opik.rest_api.projects.client.ProjectsClient(*, client_wrapper: SyncClientWrapper)

Bases: object

find_alerts_by_project(project_id: str, *, page: int | None = None, size: int | None = None, sorting: str | None = None, filters: str | None = None, request_options: RequestOptions | None = None) → AlertPagePublic

Find alerts scoped to a project

Parameters:

  • project_id (str)

  • page (Optional[int])

  • size (Optional[int])

  • sorting (Optional[str])

  • filters (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Alerts page

Return type:

AlertPagePublic

find_dashboards_by_project(project_id: str, *, page: int | None = None, size: int | None = None, name: str | None = None, sorting: str | None = None, filters: str | None = None, request_options: RequestOptions | None = None) → DashboardPagePublic

Find dashboards scoped to a project

Parameters:

  • project_id (str)

  • page (Optional[int])

  • size (Optional[int])

  • name (Optional[str])

  • sorting (Optional[str])

  • filters (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dashboard page

Return type:

DashboardPagePublic

find_datasets_by_project(project_id: str, *, page: int | None = None, size: int | None = None, with_experiments_only: bool | None = None, with_optimizations_only: bool | None = None, name: str | None = None, sorting: str | None = None, filters: str | None = None, request_options: RequestOptions | None = None) → DatasetPagePublic

Find datasets scoped to a project

Parameters:

  • project_id (str)

  • page (Optional[int])

  • size (Optional[int])

  • with_experiments_only (Optional[bool])

  • with_optimizations_only (Optional[bool])

  • name (Optional[str])

  • sorting (Optional[str])

  • filters (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset page

Return type:

DatasetPagePublic

find_experiments_by_project(project_id: str, *, page: int | None = None, size: int | None = None, dataset_id: str | None = None, optimization_id: str | None = None, types: str | None = None, name: str | None = None, dataset_deleted: bool | None = None, sorting: str | None = None, filters: str | None = None, experiment_ids: str | None = None, force_sorting: bool | None = None, request_options: RequestOptions | None = None) → ExperimentPagePublic

Find experiments scoped to a project

Parameters:

  • project_id (str)

  • page (Optional[int])

  • size (Optional[int])

  • dataset_id (Optional[str])

  • optimization_id (Optional[str])

  • types (Optional[str])

  • name (Optional[str])

  • dataset_deleted (Optional[bool])

  • sorting (Optional[str])

  • filters (Optional[str])

  • experiment_ids (Optional[str])

  • force_sorting (Optional[bool])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Experiments page

Return type:

ExperimentPagePublic

find_optimizations_by_project(project_id: str, *, page: int | None = None, size: int | None = None, dataset_id: str | None = None, dataset_name: str | None = None, name: str | None = None, dataset_deleted: bool | None = None, filters: str | None = None, request_options: RequestOptions | None = None) → OptimizationPagePublic

Find optimizations scoped to a project

Parameters:

  • project_id (str)

  • page (Optional[int])

  • size (Optional[int])

  • dataset_id (Optional[str])

  • dataset_name (Optional[str])

  • name (Optional[str])

  • dataset_deleted (Optional[bool])

  • filters (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Optimizations page

Return type:

OptimizationPagePublic

get_prompts_by_project(project_id: str, *, page: int | None = None, size: int | None = None, name: str | None = None, sorting: str | None = None, filters: str | None = None, request_options: RequestOptions | None = None) → PromptPagePublic

Get prompts scoped to a project

Parameters:

  • project_id (str)

  • page (Optional[int])

  • size (Optional[int])

  • name (Optional[str])

  • sorting (Optional[str])

  • filters (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

OK

Return type:

PromptPagePublic

find_projects(*, page: int | None = None, size: int | None = None, name: str | None = None, sorting: str | None = None, request_options: RequestOptions | None = None) → ProjectPagePublic

Find projects

Parameters:

  • page (Optional[int])

  • size (Optional[int])

  • name (Optional[str])

  • sorting (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Project resource

Return type:

ProjectPagePublic

create_project(*, name: str, visibility: Literal['private', 'public'] | Any | None = OMIT, description: str | None = OMIT, request_options: RequestOptions | None = None) → None

Create project

Parameters:

  • name (str)

  • visibility (Optional[ProjectWriteVisibility])

  • description (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

get_project_by_id(id: str, *, request_options: RequestOptions | None = None) → ProjectPublic

Get project by id

Parameters:

  • id (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Project resource

Return type:

ProjectPublic

delete_project_by_id(id: str, *, request_options: RequestOptions | None = None) → None

Delete project by id

Parameters:

  • id (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

update_project(id: str, *, name: str | None = OMIT, description: str | None = OMIT, visibility: Literal['private', 'public'] | Any | None = OMIT, request_options: RequestOptions | None = None) → None

Update project by id

Parameters:

  • id (str)

  • name (Optional[str])

  • description (Optional[str])

  • visibility (Optional[ProjectUpdateVisibility])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

delete_projects_batch(*, ids: Sequence[str], request_options: RequestOptions | None = None) → None

Delete projects batch

Parameters:

  • ids (Sequence[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

find_feedback_score_names_by_project_ids(*, project_ids: str | None = None, request_options: RequestOptions | None = None) → FeedbackScoreNames

Find Feedback Score names By Project Ids

Parameters:

  • project_ids (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Feedback Scores resource

Return type:

FeedbackScoreNames

find_token_usage_names(id: str, *, request_options: RequestOptions | None = None) → TokenUsageNames

Find Token Usage names

Parameters:

  • id (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Token Usage names resource

Return type:

TokenUsageNames

get_project_kpi_cards(id: str, *, entity_type: Literal['traces', 'spans', 'threads'] | Any, interval_start: datetime, filters: str | None = OMIT, interval_end: datetime | None = OMIT, request_options: RequestOptions | None = None) → KpiCardResponse

Gets KPI card metrics for a project

Parameters:

  • id (str)

  • entity_type (KpiCardRequestEntityType)

  • interval_start (dt.datetime)

  • filters (Optional[str])

  • interval_end (Optional[dt.datetime])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

KPI Card Metrics

Return type:

KpiCardResponse

get_project_metrics(id: str, *, metric_type: Literal['FEEDBACK_SCORES', 'TRACE_COUNT', 'TOKEN_USAGE', 'DURATION', 'COST', 'GUARDRAILS_FAILED_COUNT', 'THREAD_COUNT', 'THREAD_DURATION', 'THREAD_FEEDBACK_SCORES', 'SPAN_FEEDBACK_SCORES', 'SPAN_COUNT', 'SPAN_DURATION', 'SPAN_TOKEN_USAGE', 'TRACE_AVERAGE_DURATION', 'TRACE_ERROR_RATE', 'SPAN_AVERAGE_DURATION', 'SPAN_COST', 'SPAN_ERROR_RATE', 'THREAD_AVERAGE_DURATION', 'THREAD_COST'] | Any | None = OMIT, interval: Literal['HOURLY', 'DAILY', 'WEEKLY', 'TOTAL'] | Any | None = OMIT, interval_start: datetime | None = OMIT, interval_end: datetime | None = OMIT, span_filters: Sequence[SpanFilterPublic] | None = OMIT, trace_filters: Sequence[TraceFilterPublic] | None = OMIT, thread_filters: Sequence[TraceThreadFilterPublic] | None = OMIT, breakdown: BreakdownConfigPublic | None = OMIT, request_options: RequestOptions | None = None) → ProjectMetricResponsePublic

Gets specified metrics for a project

Parameters:

  • id (str)

  • metric_type (Optional[ProjectMetricRequestPublicMetricType])

  • interval (Optional[ProjectMetricRequestPublicInterval])

  • interval_start (Optional[dt.datetime])

  • interval_end (Optional[dt.datetime])

  • span_filters (Optional[Sequence[SpanFilterPublic]])

  • trace_filters (Optional[Sequence[TraceFilterPublic]])

  • thread_filters (Optional[Sequence[TraceThreadFilterPublic]])

  • breakdown (Optional[BreakdownConfigPublic])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Project Metrics

Return type:

ProjectMetricResponsePublic

get_project_stats(*, page: int | None = None, size: int | None = None, name: str | None = None, filters: str | None = None, sorting: str | None = None, request_options: RequestOptions | None = None) → ProjectStatsSummary

Get Project Stats

Parameters:

  • page (Optional[int])

  • size (Optional[int])

  • name (Optional[str])

  • filters (Optional[str])

  • sorting (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Project Stats

Return type:

ProjectStatsSummary

retrieve_project(*, name: str, include_stats: bool | None = OMIT, request_options: RequestOptions | None = None) → ProjectDetailed

Retrieve project

Parameters:

  • name (str)

  • include_stats (Optional[bool])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Project resource

Return type:

ProjectDetailed

get_recent_activity(project_id: str, *, page: int | None = None, size: int | None = None, request_options: RequestOptions | None = None) → RecentActivityPagePublic

Returns the most recent activity items across all entity types for a project, sorted by date descending.

Parameters:

  • project_id (str)

  • page (Optional[int])

  • size (Optional[int])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Recent activity page

Return type:

RecentActivityPagePublic

Usage Example

import opik

client = opik.Opik()

# Find projects
projects = client.rest_client.projects.find_projects(
    page=0,
    size=10
)

# Get a project by ID
project = client.rest_client.projects.get_project_by_id("project-id")

# Create a new project
client.rest_client.projects.create_project(
    name="my-project",
    description="A test project"
)

# Get project metrics
metrics = client.rest_client.projects.get_project_metrics(
    project_id="project-id",
    metric_type="trace_count",
    interval="1h"
)