Opik¶

class opik.Opik(project_name: str | None = None, workspace: str | None = None, host: str | None = None, api_key: str | None = None, batching: bool = True, _use_batching: bool = False, _show_misconfiguration_message: bool = True)¶

Bases: object

__init__(project_name: str | None = None, workspace: str | None = None, host: str | None = None, api_key: str | None = None, batching: bool = True, _use_batching: bool = False, _show_misconfiguration_message: bool = True) → None¶

Initialize an Opik object that can be used to log traces and spans manually to Opik server.

Parameters:

project_name – The name of the project. If not provided, falls back to the active project context (from @track or opik.project_context), then to the Default Project.
workspace – The name of the workspace. If not provided, default will be used.
host – The host URL for the Opik server. If not provided, it will default to https://www.comet.com/opik/api.
api_key – The API key for Opik. This parameter is ignored for local installations.
batching – If True (default), enables request batching for higher throughput. When enabled, update operations (update_span, update_trace, Span.update, Trace.update) may cause data loss if the update arrives at the server before the batched create request is flushed.
_use_batching – Deprecated. Use batching instead.
_show_misconfiguration_message – intended for internal usage in specific conditions only. Print a warning message if the Opik server is not configured properly.

Returns:

None

property config: OpikConfig¶: Returns: OpikConfig: Read-only copy of the configuration of the Opik client.

property rest_client: OpikApi¶

Provides direct access to the underlying REST API client.

WARNING: This client is not guaranteed to be backward compatible with future SDK versions. While it provides a convenient way to use the current REST API of Opik. However, it’s not considered safe to heavily rely on its API as Opik’s REST API contracts may change.

Returns:: The REST client used by the Opik client.
Return type:: OpikApi

property project_name: str¶

This property retrieves the name of the project associated with the instance. It is a read-only property.

Returns:: The name of the project.
Return type:: str

auth_check() → None¶: Checks if current API key user has an access to the configured workspace and its content.

Create and log a new trace.

Parameters:

id – The unique identifier for the trace, if not provided, a new ID will be generated. Must be a valid [UUIDv7](https://uuid7.com/) ID.
name – The name of the trace.
start_time – The start time of the trace. If not provided, the current local time will be used.
end_time – The end time of the trace.
input – The input data for the trace. This can be any valid JSON serializable object.
output – The output data for the trace. This can be any valid JSON serializable object.
metadata – Additional metadata for the trace. This can be any valid JSON serializable object.
tags – Tags associated with the trace.
feedback_scores – The list of feedback score dicts associated with the trace. Dicts don’t require to have an id value.
project_name – The name of the project. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
error_info – The dictionary with error information (typically used when the trace function has failed).
thread_id – Used to group multiple traces into a thread. The identifier is user-defined and has to be unique per project.
attachments – The list of attachments to be uploaded to the trace.

Returns:

The created trace object.

Return type:

trace.Trace

copy_traces(project_name: str, destination_project_name: str, delete_original_project: bool = False) → None¶

Copy traces from one project to another. This method will copy all traces in a source project to the destination project. Optionally, you can also delete these traces from the source project.

As the traces are copied, the IDs for both traces and spans will be updated as part of the copy process.

Note: This method is not optimized for large projects, if you run into any issues please raise an issue on GitHub. In addition, be aware that deleting traces that are linked to experiments will lead to inconsistencies in the UI.

Parameters:

project_name – The name of the project to copy traces from.
destination_project_name – The name of the project to copy traces to.
delete_original_project – Whether to delete the original project. Defaults to False.

Returns:

None

Create and log a new span.

Parameters:

trace_id – The unique identifier for the trace. If not provided, a new ID will be generated. Must be a valid [UUIDv7](https://uuid7.com/) ID.
id – The unique identifier for the span. If not provided, a new ID will be generated. Must be a valid [UUIDv7](https://uuid7.com/) ID.
parent_span_id – The unique identifier for the parent span.
name – The name of the span.
type – The type of the span. Default is “general”.
start_time – The start time of the span. If not provided, the current local time will be used.
end_time – The end time of the span.
metadata – Additional metadata for the span. This can be any valid JSON serializable object.
input – The input data for the span. This can be any valid JSON serializable object.
output – The output data for the span. This can be any valid JSON serializable object.
tags – Tags associated with the span.
feedback_scores – The list of feedback score dicts associated with the span. Dicts don’t require having an id value.
project_name – The name of the project. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
usage – Usage data for the span. In order for input, output, and total tokens to be visible in the UI, the usage must contain OpenAI-formatted keys (they can be passed additionally to the original usage on the top level of the dict): prompt_tokens, completion_tokens, and total_tokens. If OpenAI-formatted keys were not found, Opik will try to calculate them automatically if the usage format is recognized (you can see which provider’s formats are recognized in opik.LLMProvider enum), but it is not guaranteed.
model – The name of LLM (in this case type parameter should be == llm)
provider – The provider of LLM. You can find providers officially supported by Opik for cost tracking in opik.LLMProvider enum. If your provider is not here, please open an issue in our GitHub - https://github.com/comet-ml/opik. If your provider is not in the list, you can still specify it, but the cost tracking will not be available
error_info – The dictionary with error information (typically used when the span function has failed).
total_cost – The cost of the span in USD. This value takes priority over the cost calculated by Opik from the usage.
attachments – The list of attachments to be uploaded to the span.

Returns:

The created span object.

Return type:

span.Span

Update the attributes of an existing span.

This method should only be used after the span has been fully created and stored. If called before or immediately after span creation, the update may silently fail or result in incorrect data.

This method uses four parameters to identify the span:

id
trace_id
parent_span_id
project_name

These parameters must match exactly the values used when the span was created. If any of them are incorrect, the update may not apply and no error will be raised.

All other parameters are optional and will update the corresponding fields in the span. If a parameter is not provided, the existing value will remain unchanged.

Parameters:

id – The unique identifier for the span to update.
trace_id – The unique identifier for the trace to which the span belongs.
parent_span_id – The unique identifier for the parent span.
project_name – The project name to which the span belongs.
end_time – The new end time of the span.
metadata – The new metadata to be associated with the span.
input – The new input data for the span.
output – The new output data for the span.
tags – A new list of tags to be associated with the span.
usage – The new usage data for the span. In order for input, output and total tokens to be visible in the UI, the usage must contain OpenAI-formatted keys (they can be passed additionaly to original usage on the top level of the dict): prompt_tokens, completion_tokens and total_tokens. If OpenAI-formatted keys were not found, Opik will try to calculate them automatically if the usage format is recognized (you can see which provider’s formats are recognized in opik.LLMProvider enum), but it is not guaranteed.
model – The new name of LLM.
provider – The new provider of LLM. You can find providers officially supported by Opik for cost tracking in opik.LLMProvider enum. If your provider is not here, please open an issue in our github - https://github.com/comet-ml/opik. If your provider not in the list, you can still specify it but the cost tracking will not be available
error_info – The new dictionary with error information (typically used when the span function has failed).
total_cost – The new cost of the span in USD. This value takes priority over the cost calculated by Opik from the usage.
attachments – The new list of attachments to be uploaded to the span.

Returns:

None

Update the trace attributes.

This method should only be used after the trace has been fully created and stored. If called before or immediately after trace creation, the update may silently fail or result in incorrect data.

This method uses two parameters to identify the trace:

trace_id
project_name

These parameters must match exactly the values used when the trace was created. If any of them are incorrect, the update may not apply and no error will be raised.

All other parameters are optional and will update the corresponding fields in the trace. If a parameter is not provided, the existing value will remain unchanged.

Parameters:

trace_id – The unique identifier for the trace.
project_name – The project name to which the trace belongs.
end_time – The end time of the trace.
metadata – Additional metadata to be associated with the trace.
input – The input data for the trace.
output – The output data for the trace.
tags – A list of tags to be associated with the trace.
error_info – The dictionary with error information (typically used when the trace function has failed).
thread_id – Used to group multiple traces into a thread. The identifier is user-defined and has to be unique per project.

Returns:

None

log_spans_feedback_scores(scores: List[BatchFeedbackScoreDict], project_name: str | None = None) → None¶

Log feedback scores for spans.

Parameters:

scores (List[BatchFeedbackScoreDict]) – A list of feedback score dictionaries. Specifying a span id via id key for each score is mandatory.
project_name – The name of the project in which the spans are logged. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default. Deprecated: use project_name in the feedback score dictionary that’s listed in the scores parameter.

Returns:

None

Example

>>> from opik import Opik
>>> client = Opik()
>>> # Batch logging across multiple projects
>>> scores = [
>>>     {"id": span1_id, "name": "accuracy", "value": 0.95, "project_name": "project-A"},
>>>     {"id": span2_id, "name": "accuracy", "value": 0.88, "project_name": "project-B"},
>>> ]
>>> client.log_spans_feedback_scores(scores=scores)

log_traces_feedback_scores(scores: List[BatchFeedbackScoreDict], project_name: str | None = None) → None¶

Log feedback scores for traces.

Parameters:

scores (List[BatchFeedbackScoreDict]) – A list of feedback score dictionaries. Specifying a trace id via id key for each score is mandatory.
project_name – The name of the project in which the traces are logged. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default. Deprecated: use project_name in the feedback score dictionary that’s listed in the scores parameter.

Returns:

None

Example

>>> from opik import Opik
>>> client = Opik()
>>> # Batch logging across multiple projects
>>> scores = [
>>>     {"id": trace1_id, "name": "accuracy", "value": 0.95, "project_name": "project-A"},
>>>     {"id": trace2_id, "name": "accuracy", "value": 0.88, "project_name": "project-B"},
>>> ]
>>> client.log_traces_feedback_scores(scores=scores)

log_assertion_results(assertion_results: List[BatchAssertionResultDict], project_name: str | None = None) → None¶

Log assertion results for traces via the dedicated assertion-results ingestion endpoint.

Parameters:

assertion_results – A list of assertion result dictionaries. Each entry requires id (trace id), name, and status (“passed” or “failed”).
project_name – The project the traces belong to. If not provided, falls back to the active project context, then to the client’s default.

log_threads_feedback_scores(scores: List[BatchFeedbackScoreDict], project_name: str | None = None) → None¶

Log feedback scores for threads.

Parameters:

scores (List[BatchFeedbackScoreDict]) – A list of feedback score dictionaries. Specifying a thread id via id key for each score is mandatory.
project_name – The name of the project in which the threads are logged. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default. Deprecated: use project_name in the feedback score dictionary that’s listed in the scores parameter.

Returns:

None

Example

>>> from opik import Opik
>>> client = Opik()
>>> # Batch logging across multiple projects
>>> scores = [
>>>     {"id": "thread_123", "name": "user_satisfaction", "value": 0.85, "project_name": "project-A"},
>>>     {"id": "thread_456", "name": "user_satisfaction", "value": 0.92, "project_name": "project-B"},
>>> ]
>>> client.log_threads_feedback_scores(scores=scores)

search_threads(project_name: str | None = None, filter_string: str | None = None, max_results: int = 1000, truncate: bool = True) → List[TraceThread]¶

Search for threads in a given project based on specific criteria.

Parameters:

project_name – The name of the project to search the threads for. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
filter_string –
A filter string to narrow down the search using Opik Query Language (OQL). The format is: “<COLUMN> <OPERATOR> <VALUE> [AND <COLUMN> <OPERATOR> <VALUE>]*”

Supported columns: - id: String (=, !=, contains, not_contains, starts_with, ends_with, >, <) - first_message, last_message: String (=, !=, contains, not_contains, starts_with, ends_with, >, <) - environment: Enum for lifecycle stage (=, !=, in, not_in) - status: Enum (=, !=) - start_time, end_time, created_at, last_updated_at: DateTime (=, !=, >, >=, <, <=) - feedback_scores: Numeric with dot notation (=, !=, >, >=, <, <=, is_empty, is_not_empty) - tags, annotation_queue_ids: List (=, !=, contains, not_contains, is_empty, is_not_empty) - duration, number_of_messages: Numeric (=, !=, >, >=, <, <=)

Examples: - status = “active” - Filter by thread status - id = “thread_123” - Filter by specific thread ID - number_of_messages >= 5 - Filter by message count - first_message contains “hello” - Filter by first message content - feedback_scores.user_frustration > 0.5 - Filter by feedback score - tags contains “important” - Filter by tag - environment = “production” - Filter by environment - environment in (“production”, “staging”) - Filter by multiple environments

If not provided, all threads in the project will be returned up to the limit.
max_results – The maximum number of threads to retrieve. The default value is 1000.
truncate – Whether to truncate image data stored in input, output, or metadata.

Returns:

A list of TraceThread objects that match the search criteria.

Example

>>> from opik import Opik
>>> client = Opik()
>>> threads = client.search_threads(
>>>     project_name="Demo Project",
>>>     filter_string='id = "thread_123"',
>>>     max_results=10,
>>> )

delete_trace_feedback_score(trace_id: str, name: str) → None¶

Deletes a feedback score associated with a specific trace.

Parameters:

trace_id – The unique identifier of the trace for which the feedback score needs to be deleted.
name – str The name associated with the feedback score that should be deleted.

Returns:

None

delete_span_feedback_score(span_id: str, name: str) → None¶

Deletes a feedback score associated with a specific span.

Parameters:

span_id – The unique identifier of the trace for which the feedback score needs to be deleted.
name – str The name associated with the feedback score that should be deleted.

Returns:

None

create_environment(name: str, description: str | None = None, color: str | None = None) → EnvironmentPublic¶

Create a new environment in the current workspace.

Parameters:

name – Human-readable environment name (e.g. production).
description – Optional description.
color – Optional color hex code used for UI display.

Returns:

The created environment.

get_environments() → List[EnvironmentPublic]¶

List environments in the current workspace.

The backend caps the response at the workspace limit (default 20).

update_environment(name: str, description: str | None = None, color: str | None = None) → EnvironmentPublic¶

Update the description and/or color of an environment, identified by name.

Returns the updated environment.

delete_environment(name: str) → None¶: Delete an environment by name. No-op if no matching environment exists.

get_dataset(name: str, project_name: str | None = None) → Dataset¶

Get dataset by name

Parameters:

name – The name of the dataset
project_name – The name of the project to which the dataset belongs. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.

Returns:

dataset object associated with the name passed.

Return type:

dataset.Dataset

get_datasets(max_results: int = 100, sync_items: bool = False, project_name: str | None = None) → List[Dataset]¶

Returns all datasets up to the specified limit.

Parameters:

project_name – The name of the project to which the datasets belong. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
max_results – The maximum number of datasets to return.
sync_items – If True, eagerly preload item hashes for every returned dataset — one REST roundtrip per dataset. Defaults to False: the hashes are loaded lazily on the first dataset.insert(...) call, so callers that only inspect metadata pay nothing and callers that insert still get content-hash dedup correctly.

Returns:

A list of dataset objects that match the filter string.

Return type:

List[dataset.Dataset]

get_dataset_experiments(dataset_name: str, max_results: int = 100, project_name: str | None = None) → List[Experiment]¶

Returns all experiments up to the specified limit.

Parameters:

dataset_name – The name of the dataset
max_results – The maximum number of experiments to return.
project_name – The name of the project to which the datasets belong. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.

Returns:

A list of experiment objects.

Return type:

List[experiment.Experiment]

delete_dataset(name: str, project_name: str | None = None) → None¶

Delete dataset by name

Parameters:

name – The name of the dataset
project_name – The name of the project to which the dataset belongs. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.

create_dataset(name: str, description: str | None = None, project_name: str | None = None) → Dataset¶

Create a new dataset.

Parameters:

name – The name of the dataset.
description – An optional description of the dataset.
project_name – The name of the project to which the dataset belongs. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.

Returns:

The created dataset object.

Return type:

dataset.Dataset

get_or_create_dataset(name: str, description: str | None = None, project_name: str | None = None) → Dataset¶

Get an existing dataset by name or create a new one if it does not exist.

Parameters:

name – The name of the dataset.
description – An optional description of the dataset.
project_name – The name of the project to which the dataset belongs. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.

Returns:

The dataset object.

Return type:

dataset.Dataset

Create a new dashboard.

Parameters:

name – The name of the dashboard.
type – The dashboard type, either "multi_project" or "experiments". Determines which widget types are allowed.
description – An optional description of the dashboard.
project_name – For a project-scoped dashboard, the project name. If it does not exist it will be created. Ignored when project_id is provided.
project_id – For a project-scoped dashboard, the project id. Takes precedence over project_name. If neither is provided, a workspace-level dashboard is created.
sections – Optional initial sections (DashboardSection objects or dicts). If omitted, the dashboard starts with a single empty “Overview” section.

Returns:

The created dashboard object.

Return type:

dashboard.Dashboard

get_dashboard(dashboard_id: str) → Dashboard¶

Get a dashboard by id.

Parameters:: dashboard_id – The id of the dashboard.
Returns:: The dashboard object.
Return type:: dashboard.Dashboard

get_dashboards(name: str | None = None, project_id: str | None = None, max_results: int = 100, sorting: str | None = None, filters: str | None = None) → List[Dashboard]¶

Get dashboards in the workspace.

Parameters:

name – Optional name to filter dashboards by.
project_id – Optional project id to filter dashboards by.
max_results – The maximum number of dashboards to return.
sorting – Optional serialized sorting specification.
filters – Optional serialized filter specification.

Returns:

The matching dashboards.

Return type:

List[dashboard.Dashboard]

delete_dashboard(dashboard_id: str) → None¶

Delete a dashboard by id.

Parameters:: dashboard_id – The id of the dashboard.

Create a new test suite for regression testing.

Test suites are pre-configured test suites that let you validate that prompt changes, model updates, or code modifications don’t break existing functionality.

Parameters:

name – The name of the test suite.
description – Optional description of what this suite tests.
global_assertions – Suite-level assertions applied to all items. Each string describes an expected behavior that will be checked by an LLM.
global_execution_policy – Suite-level execution policy. Example: {“runs_per_item”: 3, “pass_threshold”: 2}
tags – Optional list of tags for the suite.
project_name – Optional name of the project to associate the suite with.

Returns:

The created test suite object.

Return type:

TestSuite

Example

>>> suite = client.create_test_suite(
...     name="Refund Policy Tests",
...     description="Regression tests for refund scenarios",
...     project_name="custom-project",
...     global_assertions=[
...         "No hallucinated information",
...         "Response is helpful",
...     ],
... )
>>>
>>> suite.insert([
...     {"data": {"user_input": "How do I get a refund?", "user_tier": "premium"}},
... ])
>>>
>>> results = suite.run(task=my_llm_function)

get_test_suite(name: str, project_name: str | None = None) → TestSuite¶

Get an existing test suite by name.

Retrieves the dataset and its version-level assertions and execution policy from the backend, returning a fully configured TestSuite.

Parameters:

name – The name of the test suite.
project_name – Optional name of the project the suite is associated with.

Returns:

The test suite object.

Return type:

TestSuite

Raises:

ApiError – If no dataset with the given name exists (404).

Get an existing test suite by name or create a new one if it does not exist.

If the suite already exists it is returned as-is — the global_assertions, global_execution_policy, description, and tags parameters are only used when creating a new suite. To modify an existing suite, use TestSuite.update() instead.

Parameters:

name – The name of the test suite.
description – Optional description (used only when creating).
global_assertions – Suite-level assertions (used only when creating).
global_execution_policy – Execution policy (used only when creating).
tags – Optional list of tags (used only when creating).
project_name – Optional name of the project the suite is associated with.

Returns:

The test suite object.

Return type:

TestSuite

delete_test_suite(name: str, project_name: str | None = None) → None¶

Delete a test suite by name.

Parameters:

name – The name of the test suite.
project_name – The name of the project the suite belongs to.

get_test_suites(max_results: int = 100, project_name: str | None = None) → List[TestSuite]¶

Returns all test suites up to the specified limit.

Only returns test suites, not regular datasets.

Parameters:

max_results – The maximum number of test suites to return.
project_name – The name of the project the suites belong to.

Returns:

A list of test suite objects.

Return type:

List[TestSuite]

get_test_suite_experiments(name: str, max_results: int = 100, project_name: str | None = None) → List[Experiment]¶

Returns all experiments for a test suite.

Parameters:

name – The name of the test suite.
max_results – The maximum number of experiments to return.
project_name – The name of the project the suite belongs to.

Returns:

A list of experiment objects.

Return type:

List[Experiment]

create_experiment(dataset_name: str, name: str | None = None, experiment_config: Dict[str, Any] | None = None, prompt: BasePrompt | None = None, prompts: List[BasePrompt] | None = None, type: Literal['regular', 'trial', 'mini-batch'] = 'regular', evaluation_method: Literal['dataset', 'evaluation_suite'] = 'dataset', optimization_id: str | None = None, tags: List[str] | None = None, dataset_version_id: str | None = None, project_name: str | None = None, experiment_id: str | None = None) → Experiment¶

Creates a new experiment using the given dataset name and optional parameters.

Parameters:

dataset_name – The name of the dataset to associate with the experiment.
name – The optional name for the experiment. If None, a generated name will be used.
experiment_config – Optional experiment configuration parameters. Must be a dictionary if provided.
prompt – Prompt object to associate with the experiment. Deprecated, use prompts argument instead.
prompts – List of Prompt objects to associate with the experiment.
type – The type of the experiment. Can be “regular”, “trial”, or “mini-batch”. Defaults to “regular”. “trial” and “mini-batch” are only relevant for prompt optimization experiments.
optimization_id – Optional ID of the optimization associated with the experiment.
tags – Optional list of tags to associate with the experiment.
dataset_version_id – Optional ID of the dataset version to associate with the experiment.
project_name – Optional name of the project to associate the experiment with.
experiment_id – Optional explicit id for the experiment. When None a fresh id is generated. Callers that must know the id before creation (e.g. the migrate cascade, which records it for crash-safe cleanup) can supply their own.

Returns:

The newly created experiment object.

Return type:

experiment.Experiment

update_experiment(id: str, name: str | None = None, experiment_config: Dict[str, Any] | None = None) → None¶

Update an experiment’s name and/or configuration.

Parameters:

id – The experiment ID.
name – The new name for the experiment. If None, the name will not be updated.
experiment_config – The new configuration for the experiment. If None, the configuration will not be updated.

Raises:

ValueError – if id is None or empty, or if both name and experiment_config are None

get_experiment_by_name(name: str, project_name: str | None = None) → Experiment¶

Returns an existing experiment by its name.

Parameters:

name – The name of the experiment.
project_name – The name of the project the experiment belongs to. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.

Returns:

the API object for an existing experiment.

Return type:

experiment.Experiment

get_experiments_by_name(name: str, project_name: str | None = None) → List[Experiment]¶

Returns a list of existing experiments containing the given string in their name. Search is case-insensitive.

Parameters:

name – The string to search for in the experiment names.
project_name – The project name to search within. If None, uses the default project.

Returns:

List of existing experiments.

Return type:

List[experiment.Experiment]

get_experiment_by_id(id: str) → Experiment¶

Returns an existing experiment by its id.

Parameters:: id – The id of the experiment.
Returns:: the API object for an existing experiment.
Return type:: experiment.Experiment

end(timeout: int | None = None, *, flush: bool = True) → FlushResult | None¶

End the Opik session, releasing this client’s connection reference. When flush is True (the default), all pending messages are submitted first; when flush is False, anything still queued is dropped.

Connection resources are shared and ref-counted across clients with a matching configuration: this releases the current client’s reference. The underlying streamer/threads are torn down only when the last client sharing them is ended (or garbage-collected). When flush is True the flush drains the shared queue, so pending data from other clients on the same connection is delivered too.

Parameters:

timeout (Optional[int]) – The timeout for closing the streamer. Once the timeout is reached, the streamer will be closed regardless of whether all messages have been sent. If no timeout is set, the default value from the Opik configuration will be used. Ignored when flush is False.
flush (bool) – If True (default), wait for queued messages and file uploads to reach the backend before closing — the safe choice for production and atexit shutdown. If False, return as soon as the stop signals have been sent, dropping anything still in flight — useful in per-test teardown where assertions have already polled the backend during the test body.

After end() the client must not be used again. Calling trace(), span(), flush(), etc. on an ended client is unsupported and its behavior is undefined: it may silently no-op, or — because the transport is shared — it may still succeed by riding another live client’s resources. Do not rely on either outcome; create a new client instead.

The outcome is also available afterwards via last_flush_result.

Returns:: The flush outcome (including any data-loss detail) when flush is True; None when flush is False (nothing was flushed).

flush(timeout: int | None = None) → bool¶

Flush the streamer to ensure all messages are sent.

Attachment/file upload failures are not counted in the data-loss detail (dropped_* / failures), but an incomplete upload still makes the flush report as not fully flushed — so flushed (and hence the returned bool) does reflect uploads. Never raises and never blocks beyond timeout: an observability SDK must not disrupt the app it instruments. Detailed outcome — including any data that was dropped — is available via last_flush_result.

Parameters:: timeout (Optional[int]) – The timeout for flushing the streamer. Once the timeout is reached, the flush method will return regardless of whether all messages have been sent.
Returns:: True if all messages were delivered within the timeout with no data loss; False if the timeout was hit or any message was dropped.

property last_flush_result: FlushResult | None¶

Outcome of the most recent flush()/end() on this client.

None until the first flush.

get_errors_report() → ErrorsReport¶

Report of messages the background sender terminally dropped.

Unlike last_flush_result, which is scoped to a single flush, this reports the sender’s retained data-loss history — including drops that happened before or between flushes.

The report is capped: the total counts are exact, but the per-drop failures list keeps only the most recent entries (bounded, drop-oldest) so it never grows without bound — see ErrorsReport.

The sender is shared across clients with a matching configuration, so the report may include drops from sibling clients on the same connection.

search_traces(project_name: str | None = None, filter_string: str | None = None, max_results: int = 1000, truncate: bool = True, exclude: List[str] | None = None, wait_for_at_least: int | None = None, wait_for_timeout: int = httpx_client.READ_TIMEOUT_SECONDS, max_batch_size: int = rest_stream_parser.MAX_ENDPOINT_BATCH_SIZE) → List[TracePublic]¶

Search for traces in the given project. Optionally, you can wait for at least a certain number of traces to be found before returning within the specified timeout. If wait_for_at_least number of traces are not found within the specified timeout, an exception will be raised.

Parameters:

project_name – The name of the project to search traces in. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
filter_string –
A filter string to narrow down the search using Opik Query Language (OQL). The format is: “<COLUMN> <OPERATOR> <VALUE> [AND <COLUMN> <OPERATOR> <VALUE>]*”

Supported columns include: - id, name, created_by, thread_id, type, model, provider: String fields with full operator support - environment: Enum field for lifecycle stage (=, !=, in, not_in) - status: String field (=, contains, not_contains only) - start_time, end_time: DateTime fields (use ISO 8601 format, e.g., “2024-01-01T00:00:00Z”) - input, output: String fields for content (=, contains, not_contains only) - metadata: Dictionary field (use dot notation, e.g., “metadata.model”) - feedback_scores: Numeric field (use dot notation, e.g., “feedback_scores.accuracy”) - tags: List field (use “contains” operator only) - usage.total_tokens, usage.prompt_tokens, usage.completion_tokens: Numeric usage fields - duration, number_of_messages, total_estimated_cost: Numeric fields

Supported operators by column: - id, name, created_by, thread_id, type, model, provider: =, !=, contains, not_contains, starts_with, ends_with, >, < - environment: =, !=, in, not_in - status: =, contains, not_contains - start_time, end_time: =, >, <, >=, <= - input, output: =, contains, not_contains - metadata: =, contains, >, < - feedback_scores: =, >, <, >=, <=, is_empty, is_not_empty - tags: contains (only) - usage.total_tokens, usage.prompt_tokens, usage.completion_tokens, duration, number_of_messages, total_estimated_cost: =, !=, >, <, >=, <=

Examples: - start_time >= “2024-01-01T00:00:00Z” - Filter by start date - start_time > “2024-01-01T00:00:00Z” AND start_time < “2024-02-01T00:00:00Z” - Date range - input contains “question” - Filter by input content - usage.total_tokens > 1000 - Filter by token usage - feedback_scores.accuracy > 0.8 - Filter by feedback score - feedback_scores.my_metric is_empty - Filter traces with empty feedback score - feedback_scores.my_metric is_not_empty - Filter traces with non-empty feedback score - tags contains “production” - Filter by tag - metadata.model = “gpt-4” - Filter by metadata field - thread_id = “thread_123” - Filter by thread ID - environment = “production” - Filter by environment - environment in (“production”, “staging”) - Filter by multiple environments

If not provided, all traces in the project will be returned up to the limit.
max_results – The maximum number of traces to return.
truncate – Whether to truncate image data stored in input, output, or metadata
exclude – Fields to exclude from the response. For example, [“feedback_scores”]
wait_for_at_least – The minimum number of traces to wait for before returning.
wait_for_timeout – The timeout for waiting for traces.
max_batch_size – The maximum number of traces requested per page from the backend (default 2000). The backend buffers a page in memory before streaming it, so a large page of heavy traces (e.g. with inline attachments) can spike server memory; lower this to bound per-request memory. On a connection/timeout error the page size is automatically halved and the page retried.

Raises:

exceptions.SearchTimeoutError if wait_for_at_least traces are not found within the specified timeout. –

search_spans(project_name: str | None = None, trace_id: str | None = None, filter_string: str | None = None, max_results: int = 1000, truncate: bool = True, exclude: List[str] | None = None, wait_for_at_least: int | None = None, wait_for_timeout: int = httpx_client.READ_TIMEOUT_SECONDS, max_batch_size: int = rest_stream_parser.MAX_ENDPOINT_BATCH_SIZE) → List[SpanPublic]¶

Search for spans in the given trace. This allows you to search spans based on the span input, output, metadata, tags, etc. or based on the trace ID. Also, you can wait for at least a certain number of spans to be found before returning within the specified timeout. If wait_for_at_least number of spans are not found within the specified timeout, an exception will be raised.

Parameters:

project_name – The name of the project to search spans in. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
trace_id – The ID of the trace to search spans in. If provided, the search will be limited to the spans in the given trace.
filter_string –
A filter string to narrow down the search using Opik Query Language (OQL). The format is: “<COLUMN> <OPERATOR> <VALUE> [AND <COLUMN> <OPERATOR> <VALUE>]*”

Supported columns include: - id, name, created_by, thread_id, type, model, provider: String fields with full operator support - environment: Enum field for lifecycle stage (=, !=, in, not_in) - status: String field (=, contains, not_contains only) - start_time, end_time: DateTime fields (use ISO 8601 format, e.g., “2024-01-01T00:00:00Z”) - input, output: String fields for content (=, contains, not_contains only) - metadata: Dictionary field (use dot notation, e.g., “metadata.model”) - feedback_scores: Numeric field (use dot notation, e.g., “feedback_scores.accuracy”) - tags: List field (use “contains” operator only) - usage.total_tokens, usage.prompt_tokens, usage.completion_tokens: Numeric usage fields - duration, number_of_messages, total_estimated_cost: Numeric fields

Supported operators by column: - id, name, created_by, thread_id, type, model, provider: =, !=, contains, not_contains, starts_with, ends_with, >, < - environment: =, !=, in, not_in - status: =, contains, not_contains - start_time, end_time: =, >, <, >=, <= - input, output: =, contains, not_contains - metadata: =, contains, >, < - feedback_scores: =, >, <, >=, <=, is_empty, is_not_empty - tags: contains (only) - usage.total_tokens, usage.prompt_tokens, usage.completion_tokens, duration, number_of_messages, total_estimated_cost: =, !=, >, <, >=, <=

Examples: - start_time >= “2024-01-01T00:00:00Z” - Filter by start date - start_time > “2024-01-01T00:00:00Z” AND start_time < “2024-02-01T00:00:00Z” - Date range - input contains “question” - Filter by input content - usage.total_tokens > 1000 - Filter by token usage - feedback_scores.accuracy > 0.8 - Filter by feedback score - feedback_scores.my_metric is_empty - Filter spans with empty feedback score - feedback_scores.my_metric is_not_empty - Filter spans with non-empty feedback score - tags contains “production” - Filter by tag - metadata.model = “gpt-4” - Filter by metadata field - thread_id = “thread_123” - Filter by thread ID - environment = “production” - Filter by environment - environment in (“production”, “staging”) - Filter by multiple environments

If not provided, all spans in the project/trace will be returned up to the limit.
max_results – The maximum number of spans to return.
truncate – Whether to truncate image data stored in input, output, or metadata
exclude – List of fields to exclude from the response (e.g., [“feedback_scores”, “input”, “output”])
wait_for_at_least – The minimum number of spans to wait for before returning.
wait_for_timeout – The timeout for waiting for spans.
max_batch_size – The maximum number of spans requested per page from the backend (default 2000). The backend buffers a page in memory before streaming it, so a large page of heavy spans (e.g. with inline attachments) can spike server memory; lower this to bound per-request memory. On a connection/timeout error the page size is automatically halved and the page retried.

Raises:

exceptions.SearchTimeoutError if wait_for_at_least spans are not found within the specified timeout. –

get_trace_content(id: str) → TracePublic¶

Parameters:: id (str) – trace id
Returns:: pydantic model object with all the data associated with the trace found. Raises an error if trace was not found.
Return type:: trace_public.TracePublic

get_span_content(id: str) → SpanPublic¶

Parameters:: id (str) – span id
Returns:: pydantic model object with all the data associated with the span found. Raises an error if span was not found.
Return type:: span_public.SpanPublic

get_project(id: str) → ProjectPublic¶

Fetches a project by its unique identifier.

Parameters:: id (str) – project id (uuid).
Returns:: pydantic model object with all the data associated with the project found. Raises an error if project was not found
Return type:: project_public.ProjectPublic

get_project_url(project_name: str | None = None) → str¶

Returns a URL to the project in the current workspace. This method does not make any requests or perform any checks (e.g. that the project exists). It only builds a URL string based on the data provided.

Parameters:: project_name (str) – project name to return URL for. If not provided, a default project name for the current Opik instance will be used.
Returns:: URL
Return type:: str

get_threads_client() → ThreadsClient¶

Creates and provides an instance of the ThreadsClient tied to the current context.

The ThreadsClient can be used to interact with the threads API to manage and interact with conversational threads.

Returns:: An instance of threads_client.ThreadsClient initialized with the current context.
Return type:: ThreadsClient

get_attachment_client() → AttachmentClient¶

Creates and provides an instance of the AttachmentClient tied to the current context.

The AttachmentClient can be used to interact with the attachments API to retrieve attachment lists, download attachments, and upload attachments for traces and spans.

Returns:: An instance of attachment.client.AttachmentClient
Return type:: AttachmentClient

queue_attachment_upload(entity_type: Literal['trace', 'span'], entity_id: str, project_name: str, file_path: str, file_name: str | None = None, mime_type: str | None = None) → None¶

Queue a local file for background upload as an attachment via the streamer.

This method is non-blocking: the upload is handled by the background streamer which provides parallelization, automatic retries, and monitoring. Call flush() to wait for all queued uploads to complete.

Parameters:

entity_type – The type of entity to attach the file to ("trace" or "span").
entity_id – The ID of the trace or span to attach the file to.
project_name – The name of the project containing the entity.
file_path – Path to the local file to upload.
file_name – Name to assign the attachment. Defaults to the file’s basename.
mime_type – MIME type of the file. Auto-detected from the file name if not provided.

create_prompt(name: str, prompt: str, metadata: Dict[str, Any] | None = None, type: PromptType = prompt_module.PromptType.MUSTACHE, id: str | None = None, description: str | None = None, change_description: str | None = None, tags: List[str] | None = None, project_name: str | None = None) → Prompt¶

Creates a new text prompt with the given name and template. If a text prompt with the same name already exists, it will create a new version of the existing prompt if the templates differ.

Parameters:

name – The name of the prompt.
prompt – The template content of the prompt.
metadata – Optional metadata to be included in the prompt.
type – The template type (MUSTACHE or JINJA2).
id – Optional unique identifier (UUID) for the prompt.
description – Optional description of the prompt (up to 255 characters).
change_description – Optional description of changes in this version.
tags – Optional list of tags to associate with the prompt.
project_name – Optional project name to associate with the prompt. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.

Returns:

A Prompt object containing details of the created or retrieved prompt.

Raises:

PromptTemplateStructureMismatch – If a chat prompt with the same name already exists (template structure is immutable).
ApiError – If there is an error during the creation of the prompt.

create_chat_prompt(name: str, messages: List[Dict[str, Any]], metadata: Dict[str, Any] | None = None, type: PromptType = prompt_module.PromptType.MUSTACHE, id: str | None = None, description: str | None = None, change_description: str | None = None, tags: List[str] | None = None, project_name: str | None = None) → ChatPrompt¶

Creates a new chat prompt with the given name and message templates. If a chat prompt with the same name already exists, it will create a new version if the messages differ.

Parameters:

name – The name of the chat prompt.
messages – List of message dictionaries with ‘role’ and ‘content’ fields.
metadata – Optional metadata to be included in the prompt.
type – The template type (MUSTACHE or JINJA2).
id – Optional unique identifier (UUID) for the prompt.
description – Optional description of the prompt (up to 255 characters).
change_description – Optional description of changes in this version.
tags – Optional list of tags to associate with the prompt.
project_name – Optional project name for the prompt.

Returns:

A ChatPrompt object containing details of the created or retrieved chat prompt.

Raises:

PromptTemplateStructureMismatch – If a text prompt with the same name already exists (template structure is immutable).
ApiError – If there is an error during the creation of the prompt.

Retrieve a text prompt by name, optionally targeting a specific version.

This method only returns text prompts. Results are cached client-side (TTL configurable via OPIK_PROMPT_CACHE_TTL_SECONDS, default 300 s). When called inside an @track context the prompt reference is injected into the active trace/span metadata.

Parameters:

name – The name of the prompt.
commit – DEPRECATED in favour of version. Mutually exclusive with version.
project_name – The name of the project to retrieve the prompt from. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
no_cache – If True, skip the local cache and fetch directly from the backend, guaranteeing a fresh value.
version – Optional sequential version selector in the wire format "v<N>" (e.g. "v3"). If not provided, the latest version is retrieved.
environment – Optional environment name. When provided, returns the version that the given environment currently points to. Mutually exclusive with version.

Returns:

The details of the specified text prompt, or None if not found.

Return type:

Prompt

Raises:

PromptTemplateStructureMismatch – If the prompt exists but is a chat prompt (template structure mismatch).
ValueError – If both version and environment are provided.

Retrieve a chat prompt by name, optionally targeting a specific version.

This method only returns chat prompts. Results are cached client-side (TTL configurable via OPIK_PROMPT_CACHE_TTL_SECONDS, default 300 s). When called inside an @track context the prompt reference is injected into the active trace/span metadata.

Parameters:

name – The name of the prompt.
commit – DEPRECATED in favour of version. Mutually exclusive with version.
project_name – The name of the project to retrieve the prompt from. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
no_cache – If True, skip the local cache and fetch directly from the backend, guaranteeing a fresh value.
version – Optional sequential version selector in the wire format "v<N>" (e.g. "v3"). If not provided, the latest version is retrieved.
environment – Optional environment name. When provided, returns the version that the given environment currently points to. Mutually exclusive with version.

Returns:

The details of the specified chat prompt, or None if not found.

Return type:

ChatPrompt

Raises:

PromptTemplateStructureMismatch – If the prompt exists but is a text prompt (template structure mismatch).
ValueError – If both version and environment are provided.

set_prompt_environments(prompt_name: str, environments: List[str], *, version: str | None = None, project_name: str | None = None) → None¶

Replace the full set of environments owned by a prompt version.

The provided list becomes the resolved version’s complete set of environments. Pass an empty list to clear all environments from the version. Ownership of any environment in the list moves to this version: any other version of the same prompt that previously owned one of them is cleared. Existing Prompt objects already in memory are not mutated — re-fetch with client.get_prompt(...) to see the change.

Parameters:

prompt_name – The name of the prompt.
environments – Environments to assign. Each must already be registered in the workspace. Pass [] to clear.
version – Optional sequential version selector in the wire format "v<N>" (e.g. "v3"). Defaults to the latest version.
project_name – Project the prompt belongs to. Defaults to the active project context, then to the client’s default.

Raises:

PromptNotFoundError – The prompt name (or the supplied version) does not exist in the resolved project.
EnvironmentNotFoundError – One of environments is not registered in the workspace.

get_prompt_history(name: str, search: str | None = None, filter_string: str | None = None, project_name: str | None = None) → List[Prompt]¶

Retrieve all text prompt versions history for a given prompt name.

Parameters:

name – The name of the prompt.
search – Optional search text to find in template or change description fields.
project_name – The name of the project to retrieve the prompt history from. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
filter_string –
A filter string to narrow down the search using Opik Query Language (OQL). The format is: “<COLUMN> <OPERATOR> <VALUE> [AND <COLUMN> <OPERATOR> <VALUE>]*”

Supported columns include: - id, commit, template, change_description, created_by: String fields with full operator support - metadata: Dictionary field (use dot notation, e.g., “metadata.environment”) - type: Enum field (=, != only) - tags: List field (use “contains” operator only) - created_at: DateTime field (use ISO 8601 format, e.g., “2024-01-01T00:00:00Z”)

Examples: - tags contains “production” - Filter by tag - tags contains “v1” AND tags contains “production” - Filter by multiple tags - template contains “customer” - Filter by template content - created_by = “user@example.com” - Filter by creator - created_at >= “2024-01-01T00:00:00Z” - Filter by creation date - metadata.environment = “prod” - Filter by metadata field

Returns:

A list of text Prompt instances for the given name, or an empty list if not found.

Return type:

List[Prompt]

Raises:

PromptTemplateStructureMismatch – If the prompt exists but is a chat prompt (template structure mismatch).

Example

# Get all versions of a prompt
versions = client.get_prompt_history(name="my-prompt", project_name="my-project")

# Filter by tags (versions containing "production" tag)
versions = client.get_prompt_history(
    name="my-prompt",
    project_name="my-project",
    filter_string='tags contains "production"'
)

# Search for specific text in template or change description fields
versions = client.get_prompt_history(
    name="my-prompt",
    project_name="my-project",
    search="customer"
)

# Combine search and filtering
versions = client.get_prompt_history(
    name="my-prompt",
    project_name="my-project",
    search="customer",
    filter_string='tags contains "production"'
)

get_chat_prompt_history(name: str, search: str | None = None, filter_string: str | None = None, project_name: str | None = None) → List[ChatPrompt]¶

Retrieve all chat prompt versions history for a given prompt name.

Parameters:

name – The name of the prompt.
search – Optional search text to find in template or change description fields.
project_name – The name of the project to retrieve the prompt history from. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
filter_string –
A filter string to narrow down the search using Opik Query Language (OQL). The format is: “<COLUMN> <OPERATOR> <VALUE> [AND <COLUMN> <OPERATOR> <VALUE>]*”

Supported columns include: - id, commit, template, change_description, created_by: String fields with full operator support - metadata: Dictionary field (use dot notation, e.g., “metadata.environment”) - type: Enum field (=, != only) - tags: List field (use “contains” operator only) - created_at: DateTime field (use ISO 8601 format, e.g., “2024-01-01T00:00:00Z”)

Examples: - tags contains “production” - Filter by tag - tags contains “v1” AND tags contains “production” - Filter by multiple tags - template contains “helpful assistant” - Filter by template content - created_by = “user@example.com” - Filter by creator - created_at >= “2024-01-01T00:00:00Z” - Filter by creation date - metadata.environment = “prod” - Filter by metadata field

Returns:

A list of ChatPrompt instances for the given name, or an empty list if not found.

Return type:

List[ChatPrompt]

Raises:

PromptTemplateStructureMismatch – If the prompt exists but is a text prompt (template structure mismatch).

Example

# Get all versions of a chat prompt
versions = client.get_chat_prompt_history(name="my-chat-prompt", project_name="my-project")

# Filter by tags (versions containing "production" tag)
versions = client.get_chat_prompt_history(
    name="my-chat-prompt",
    project_name="my-project",
    filter_string='tags contains "production"'
)

# Search for specific text in template or change description fields
versions = client.get_chat_prompt_history(
    name="my-chat-prompt",
    project_name="my-project",
    search="helpful assistant"
)

# Combine search and filtering
versions = client.get_chat_prompt_history(
    name="my-chat-prompt",
    project_name="my-project",
    search="helpful assistant",
    filter_string='tags contains "production"'
)

get_all_prompts(name: str, project_name: str | None = None) → List[Prompt]¶

DEPRECATED: Please use Opik.get_prompt_history() instead. Retrieve all the prompt versions history for a given prompt name.

Parameters:

name – The name of the prompt.
project_name – The name of the project to retrieve the prompt history from. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.

Returns:

A list of Prompt instances for the given name.

Return type:

List[prompt_module.Prompt]

search_prompts(filter_string: str | None = None, project_name: str | None = None) → List[Prompt | ChatPrompt]¶

Retrieve the latest prompt versions (both string and chat prompts) for the given search parameters.

Parameters:

project_name – The name of the project to search in. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
filter_string –
A filter string to narrow down the search using Opik Query Language (OQL). The format is: “<COLUMN> <OPERATOR> <VALUE> [AND <COLUMN> <OPERATOR> <VALUE>]*”

Supported columns include: - id, name: String fields - tags: List field (use “contains” operator only) - created_by: String field - template_structure: String field (“string” or “chat”)

Supported operators by column: - id: =, !=, contains, not_contains, starts_with, ends_with, >, < - name: =, !=, contains, not_contains, starts_with, ends_with, >, < - created_by: =, !=, contains, not_contains, starts_with, ends_with, >, < - template_structure: =, != - tags: contains (only)

Examples: - tags contains “alpha” - Filter by tag - tags contains “alpha” AND tags contains “beta” - Filter by multiple tags - name contains “summary” - Filter by name substring - created_by = “user@example.com” - Filter by creator - id starts_with “prompt_” - Filter by ID prefix - template_structure = “text” - Only text prompts - template_structure = “chat” - Only chat prompts

If not provided, all prompts (both text and chat) will be returned.

Returns:

A list of Prompt and/or ChatPrompt instances found.

Return type:

List[Union[Prompt, ChatPrompt]]

create_optimization(dataset_name: str, objective_name: str, name: str | None = None, metadata: Dict[str, Any] | None = None, optimization_id: str | None = None, project_name: str | None = None) → Optimization¶

delete_optimizations(ids: List[str]) → None¶

get_optimization_by_id(id: str) → Optimization¶

get_experiments_client() → ExperimentsClient¶

Retrieves an instance of ExperimentsClient.

Returns:: An instance of the ExperimentsClient initialized with a cached REST client.

get_prompts_client() → PromptClient¶

Retrieves an instance of PromptClient for bulk prompt operations.

Use this client for operations like updating prompt version tags in batch.

Returns:: An instance of the PromptClient initialized with a cached REST client.

Example

prompts_client = client.get_prompts_client()
prompts_client.batch_update_prompt_version_tags(
    version_ids=["version-id-1", "version-id-2"],
    tags=["production", "v2"]
)

create_traces_annotation_queue(name: str, project_name: str | None = None, description: str | None = None, instructions: str | None = None, comments_enabled: bool | None = None, feedback_definition_names: List[str] | None = None) → TracesAnnotationQueue¶

Create a new annotation queue for traces.

Parameters:

name – The name of the annotation queue.
project_name – The name of the project. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
description – An optional description of the queue.
instructions – Optional instructions for reviewers.
comments_enabled – Whether to enable comments on items.
feedback_definition_names – Optional list of feedback definition names.

Returns:

The created traces annotation queue object.

Return type:

TracesAnnotationQueue

create_threads_annotation_queue(name: str, project_name: str | None = None, description: str | None = None, instructions: str | None = None, comments_enabled: bool | None = None, feedback_definition_names: List[str] | None = None) → ThreadsAnnotationQueue¶

Create a new annotation queue for threads.

Parameters:

name – The name of the annotation queue.
project_name – The name of the project. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
description – An optional description of the queue.
instructions – Optional instructions for reviewers.
comments_enabled – Whether to enable comments on items.
feedback_definition_names – Optional list of feedback definition names.

Returns:

The created threads annotation queue object.

Return type:

ThreadsAnnotationQueue

get_traces_annotation_queue(queue_id: str) → TracesAnnotationQueue¶

Get a traces annotation queue by its ID.

Parameters:: queue_id – The ID of the annotation queue.
Returns:: The traces annotation queue object.
Return type:: TracesAnnotationQueue
Raises:: OpikException – If the queue is not found or is not a traces queue.

get_threads_annotation_queue(queue_id: str) → ThreadsAnnotationQueue¶

Get a threads annotation queue by its ID.

Parameters:: queue_id – The ID of the annotation queue.
Returns:: The threads annotation queue object.
Return type:: ThreadsAnnotationQueue
Raises:: OpikException – If the queue is not found or is not a threads queue.

get_traces_annotation_queues(project_name: str | None = None, max_results: int = 1000) → List[TracesAnnotationQueue]¶

Get all traces annotation queues for a project.

Parameters:

project_name – The name of the project. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
max_results – Maximum number of queues to return. Defaults to 1000.

Returns:

A list of traces annotation queue objects.

Return type:

List[TracesAnnotationQueue]

get_threads_annotation_queues(project_name: str | None = None, max_results: int = 1000) → List[ThreadsAnnotationQueue]¶

Get all threads annotation queues for a project.

Parameters:

project_name – The name of the project. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
max_results – Maximum number of queues to return. Defaults to 1000.

Returns:

A list of threads annotation queue objects.

Return type:

List[ThreadsAnnotationQueue]

delete_annotation_queue(queue_id: str) → None¶

Delete an annotation queue by its ID.

Parameters:: queue_id – The ID of the annotation queue to delete.

get_or_create_config(*, fallback: _ConfigT, project_name: str | None = None, env: str | None = None, version: str | None = None, timeout_in_seconds: int | None = 5) → _ConfigT¶

get_or_create_config(*, fallback: None = None, project_name: str | None = None, env: str | None = None, version: str | None = None, timeout_in_seconds: int | None = 5) → Config

Fetch a config from the backend, optionally auto-creating from a fallback.

Must be called from inside a function decorated with @opik.track.

At most one of env or version may be provided.

env — fetch the version deployed to an environment (e.g. "staging").
version — fetch a specific version by name. The special value "latest" fetches the latest version in the project; when no config exists at all and fallback is provided, auto-creates one from it.
Neither — equivalent to env="prod". If no config exists at all in the project and fallback is provided, auto-creates one from it (the backend tags the first version as "prod").

Failure modes depend on whether fallback is provided:

With fallback: Backend errors (timeouts, network failures) return the fallback instance with is_fallback=True. If an explicit env/version is requested but missing, raises ConfigNotFound. If no config exists at all, auto-creates from the fallback. The return value is an instance of type(fallback).
Without fallback: Backend errors are re-raised. If no config exists at all, raises ConfigNotFound instead of auto-creating. The return value is a generic Config instance — typed field access is only available when a fallback supplies the subclass.

If the backend blueprint is missing any field declared on the fallback’s class, raises ConfigMismatch.

Parameters:

fallback – An instance of a user-defined Config subclass. When provided, used as the return value if the backend is unreachable and as the initial values when auto-creating.
project_name – Opik project name. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
env – Environment tag to fetch (e.g. "prod", "staging").
version – Fetch a specific version by its name. Use "latest" to fetch the latest version.
timeout_in_seconds – Maximum seconds to wait for the backend response. With a fallback, a timeout returns the fallback and the cache continues refreshing in the background; without one, the timeout is raised. Pass None to wait indefinitely.

create_config(config: Config, project_name: str | None = None, description: str | None = None) → str¶

Write a config version to the backend unconditionally.

Unlike get_or_create_config(), this does not require a @opik.track context and always performs a write — the new version’s values overwrite the latest blueprint’s values.

Parameters:

config – An instance of a user-defined Config subclass.
project_name – Opik project name. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
description – Optional description stored with the version.

Returns:

The version name of the newly written blueprint.

set_config_env(*, project_name: str | None = None, version: str, env: str) → None¶

Tag a specific config version with an environment name.

After tagging, get_or_create_config(env=env) for the project will return this version.

Parameters:

project_name – Opik project name. If not provided, falls back to the active project context (from @track or opik.project_context), then to the client’s default.
version – Version name of the blueprint to tag.
env – Environment name (e.g. "prod", "staging").