Traces Client

The Traces client provides methods for managing traces in the Opik platform.

class opik.rest_api.traces.client.TracesClient(*, client_wrapper: SyncClientWrapper)

Bases: object

add_thread_comment(id_: str, *, text: str, id: str | None = OMIT, source_queue_id: str | None = OMIT, created_at: datetime | None = OMIT, last_updated_at: datetime | None = OMIT, created_by: str | None = OMIT, last_updated_by: str | None = OMIT, request_options: RequestOptions | None = None) → None

Add thread comment

Parameters:

  • id (Optional[str])

  • text (str)

  • id

  • source_queue_id (Optional[str])

  • created_at (Optional[dt.datetime])

  • last_updated_at (Optional[dt.datetime])

  • created_by (Optional[str])

  • last_updated_by (Optional[str])

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

Return type:

None

add_trace_comment(id_: str, *, text: str, id: str | None = OMIT, source_queue_id: str | None = OMIT, created_at: datetime | None = OMIT, last_updated_at: datetime | None = OMIT, created_by: str | None = OMIT, last_updated_by: str | None = OMIT, request_options: RequestOptions | None = None) → None

Add trace comment

Parameters:

  • id (Optional[str])

  • text (str)

  • id

  • source_queue_id (Optional[str])

  • created_at (Optional[dt.datetime])

  • last_updated_at (Optional[dt.datetime])

  • created_by (Optional[str])

  • last_updated_by (Optional[str])

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

Return type:

None

add_trace_feedback_score(id: str, *, name: str, value: float, source: Literal['ui', 'sdk', 'online_scoring'] | Any, category_name: str | None = OMIT, reason: str | None = OMIT, source_queue_id: str | None = OMIT, created_at: datetime | None = OMIT, last_updated_at: datetime | None = OMIT, created_by: str | None = OMIT, last_updated_by: str | None = OMIT, value_by_author: Dict[str, ValueEntry] | None = OMIT, request_options: RequestOptions | None = None) → None

Add trace feedback score

Parameters:

  • id (str)

  • name (str)

  • value (float)

  • source (FeedbackScoreSource)

  • category_name (Optional[str])

  • reason (Optional[str])

  • source_queue_id (Optional[str])

  • created_at (Optional[dt.datetime])

  • last_updated_at (Optional[dt.datetime])

  • created_by (Optional[str])

  • last_updated_by (Optional[str])

  • value_by_author (Optional[Dict[str, ValueEntry]])

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

Return type:

None

create_traces(*, traces: Sequence[TraceWrite], request_options: RequestOptions | None = None) → None

Create traces

Parameters:

  • traces (Sequence[TraceWrite])

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

Return type:

None

batch_update_traces(*, ids: Sequence[str], update: TraceUpdate, merge_tags: bool | None = OMIT, request_options: RequestOptions | None = None) → None

Update multiple traces

Parameters:

  • ids (Sequence[str]) – List of trace IDs to update (max 1000)

  • update (TraceUpdate)

  • merge_tags (Optional[bool]) – If true, merge tags with existing tags instead of replacing them. Default: false

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

Return type:

None

batch_update_threads(*, ids: Sequence[str], update: TraceThreadUpdate, merge_tags: bool | None = OMIT, request_options: RequestOptions | None = None) → None

Update multiple threads

Parameters:

  • ids (Sequence[str]) – List of thread model IDs to update (max 1000)

  • update (TraceThreadUpdate)

  • merge_tags (Optional[bool]) – If true, merge tags with existing tags instead of replacing them. Default: false

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

Return type:

None

close_trace_thread(*, project_name: str | None = OMIT, project_id: str | None = OMIT, thread_id: str | None = OMIT, thread_ids: Sequence[str] | None = OMIT, request_options: RequestOptions | None = None) → None

Close one or multiple trace threads. Supports both single thread_id and multiple thread_ids for batch operations.

Parameters:

  • project_name (Optional[str])

  • project_id (Optional[str])

  • thread_id (Optional[str])

  • thread_ids (Optional[Sequence[str]])

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

Return type:

None

get_traces_by_project(*, page: int | None = None, size: int | None = None, project_name: str | None = None, project_id: str | None = None, filters: str | None = None, truncate: bool | None = None, strip_attachments: bool | None = None, sorting: str | None = None, exclude: str | None = None, search: str | None = None, from_time: datetime | None = None, to_time: datetime | None = None, annotation_queue_id: str | None = None, request_options: RequestOptions | None = None) → TracePagePublic

Get traces by project_name or project_id

Parameters:

  • page (Optional[int])

  • size (Optional[int])

  • project_name (Optional[str])

  • project_id (Optional[str])

  • filters (Optional[str])

  • truncate (Optional[bool])

  • strip_attachments (Optional[bool])

  • sorting (Optional[str])

  • exclude (Optional[str])

  • search (Optional[str])

  • from_time (Optional[dt.datetime])

  • to_time (Optional[dt.datetime])

  • annotation_queue_id (Optional[str])

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

Returns:

Trace resource

Return type:

TracePagePublic

create_trace(*, start_time: datetime, id: str | None = OMIT, project_name: str | None = OMIT, name: str | None = OMIT, end_time: datetime | None = OMIT, input: Dict[str, Any | None] | List[Dict[str, Any | None]] | str | None = OMIT, output: Dict[str, Any | None] | List[Dict[str, Any | None]] | str | None = OMIT, metadata: Dict[str, Any | None] | List[Dict[str, Any | None]] | str | None = OMIT, tags: Sequence[str] | None = OMIT, error_info: ErrorInfoWrite | None = OMIT, last_updated_at: datetime | None = OMIT, ttft: float | None = OMIT, thread_id: str | None = OMIT, source: Literal['sdk', 'experiment', 'playground', 'optimization', 'evaluator'] | Any | None = OMIT, environment: str | None = OMIT, request_options: RequestOptions | None = None) → None

Get trace

Parameters:

  • start_time (dt.datetime)

  • id (Optional[str])

  • project_name (Optional[str]) – If null, the default project is used

  • name (Optional[str])

  • end_time (Optional[dt.datetime])

  • input (Optional[JsonListStringWrite])

  • output (Optional[JsonListStringWrite])

  • metadata (Optional[JsonListStringWrite])

  • tags (Optional[Sequence[str]])

  • error_info (Optional[ErrorInfoWrite])

  • last_updated_at (Optional[dt.datetime])

  • ttft (Optional[float]) – Time to first token in milliseconds

  • thread_id (Optional[str])

  • source (Optional[TraceWriteSource])

  • environment (Optional[str])

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

Return type:

None

get_trace_by_id(id: str, *, strip_attachments: bool | None = None, request_options: RequestOptions | None = None) → TracePublic

Get trace by id

Parameters:

  • id (str)

  • strip_attachments (Optional[bool])

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

Returns:

Trace resource

Return type:

TracePublic

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

Delete trace by id

Parameters:

  • id (str)

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

Return type:

None

update_trace(id: str, *, project_name: str | None = OMIT, project_id: str | None = OMIT, name: str | None = OMIT, end_time: datetime | None = OMIT, input: Dict[str, Any | None] | List[Dict[str, Any | None]] | str | None = OMIT, output: Dict[str, Any | None] | List[Dict[str, Any | None]] | str | None = OMIT, metadata: Dict[str, Any | None] | List[Dict[str, Any | None]] | str | None = OMIT, tags: Sequence[str] | None = OMIT, tags_to_add: Sequence[str] | None = OMIT, tags_to_remove: Sequence[str] | None = OMIT, error_info: ErrorInfo | None = OMIT, thread_id: str | None = OMIT, ttft: float | None = OMIT, source: Literal['sdk', 'experiment', 'playground', 'optimization', 'evaluator'] | Any | None = OMIT, environment: str | None = OMIT, request_options: RequestOptions | None = None) → None

Update trace by id

Parameters:

  • id (str)

  • project_name (Optional[str]) – If null and project_id not specified, Default Project is assumed

  • project_id (Optional[str]) – If null and project_name not specified, Default Project is assumed

  • name (Optional[str])

  • end_time (Optional[dt.datetime])

  • input (Optional[JsonListString])

  • output (Optional[JsonListString])

  • metadata (Optional[JsonListString])

  • tags (Optional[Sequence[str]]) – Tags

  • tags_to_add (Optional[Sequence[str]]) – Tags to add

  • tags_to_remove (Optional[Sequence[str]]) – Tags to remove

  • error_info (Optional[ErrorInfo])

  • thread_id (Optional[str])

  • ttft (Optional[float])

  • source (Optional[TraceUpdateSource])

  • environment (Optional[str])

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

Return type:

None

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

Delete thread comments

Parameters:

  • ids (Sequence[str])

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

Return type:

None

delete_thread_feedback_scores(*, project_name: str, thread_id: str, names: Sequence[str], author: str | None = OMIT, source_queue_id: str | None = OMIT, request_options: RequestOptions | None = None) → None

Delete thread feedback scores

Parameters:

  • project_name (str)

  • thread_id (str)

  • names (Sequence[str])

  • author (Optional[str])

  • source_queue_id (Optional[str])

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

Return type:

None

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

Delete trace comments

Parameters:

  • ids (Sequence[str])

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

Return type:

None

delete_trace_feedback_score(id: str, *, name: str, author: str | None = OMIT, source_queue_id: str | None = OMIT, request_options: RequestOptions | None = None) → None

Delete trace feedback score

Parameters:

  • id (str)

  • name (str)

  • author (Optional[str])

  • source_queue_id (Optional[str])

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

Return type:

None

delete_trace_threads(*, thread_ids: Sequence[str], project_name: str | None = OMIT, project_id: str | None = OMIT, request_options: RequestOptions | None = None) → None

Delete trace threads

Parameters:

  • thread_ids (Sequence[str])

  • project_name (Optional[str]) – If null, project_id must be provided

  • project_id (Optional[str]) – If null, project_name must be provided

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

Return type:

None

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

Delete traces

Parameters:

  • ids (Sequence[str])

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

Return type:

None

find_feedback_score_names2(*, project_id: str | None = None, request_options: RequestOptions | None = None) → FeedbackScoreNamesPublic

Find Feedback Score names

Parameters:

  • project_id (Optional[str])

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

Returns:

Feedback Scores resource

Return type:

FeedbackScoreNamesPublic

find_trace_threads_feedback_score_names(*, project_id: str | None = None, request_options: RequestOptions | None = None) → FeedbackScoreNamesPublic

Find Trace Threads Feedback Score names

Parameters:

  • project_id (Optional[str])

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

Returns:

Find Trace Threads Feedback Score names

Return type:

FeedbackScoreNamesPublic

get_trace_stats(*, project_id: str | None = None, project_name: str | None = None, filters: str | None = None, search: str | None = None, from_time: datetime | None = None, to_time: datetime | None = None, request_options: RequestOptions | None = None) → ProjectStatsPublic

Get trace stats

Parameters:

  • project_id (Optional[str])

  • project_name (Optional[str])

  • filters (Optional[str])

  • search (Optional[str])

  • from_time (Optional[dt.datetime])

  • to_time (Optional[dt.datetime])

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

Returns:

Trace stats resource

Return type:

ProjectStatsPublic

get_thread_comment(thread_id: str, comment_id: str, *, request_options: RequestOptions | None = None) → Comment

Get thread comment

Parameters:

  • thread_id (str)

  • comment_id (str)

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

Returns:

Comment resource

Return type:

Comment

get_trace_thread_stats(*, project_id: str | None = None, project_name: str | None = None, filters: str | None = None, search: str | None = None, from_time: datetime | None = None, to_time: datetime | None = None, request_options: RequestOptions | None = None) → ProjectStatsPublic

Get trace thread stats

Parameters:

  • project_id (Optional[str])

  • project_name (Optional[str])

  • filters (Optional[str])

  • search (Optional[str])

  • from_time (Optional[dt.datetime])

  • to_time (Optional[dt.datetime])

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

Returns:

Trace thread stats resource

Return type:

ProjectStatsPublic

get_trace_comment(trace_id: str, comment_id: str, *, request_options: RequestOptions | None = None) → Comment

Get trace comment

Parameters:

  • trace_id (str)

  • comment_id (str)

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

Returns:

Comment resource

Return type:

Comment

get_trace_thread(*, thread_id: str, project_name: str | None = OMIT, project_id: str | None = OMIT, truncate: bool | None = OMIT, request_options: RequestOptions | None = None) → TraceThread

Get trace thread

Parameters:

  • thread_id (str)

  • project_name (Optional[str])

  • project_id (Optional[str])

  • truncate (Optional[bool])

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

Returns:

Trace thread resource

Return type:

TraceThread

get_trace_threads(*, page: int | None = None, size: int | None = None, project_name: str | None = None, project_id: str | None = None, truncate: bool | None = None, strip_attachments: bool | None = None, filters: str | None = None, sorting: str | None = None, search: str | None = None, from_time: datetime | None = None, to_time: datetime | None = None, annotation_queue_id: str | None = None, request_options: RequestOptions | None = None) → TraceThreadPage

Get trace threads

Parameters:

  • page (Optional[int])

  • size (Optional[int])

  • project_name (Optional[str])

  • project_id (Optional[str])

  • truncate (Optional[bool])

  • strip_attachments (Optional[bool])

  • filters (Optional[str])

  • sorting (Optional[str])

  • search (Optional[str])

  • from_time (Optional[dt.datetime])

  • to_time (Optional[dt.datetime])

  • annotation_queue_id (Optional[str])

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

Returns:

Trace threads resource

Return type:

TraceThreadPage

open_trace_thread(*, thread_id: str, project_name: str | None = OMIT, project_id: str | None = OMIT, truncate: bool | None = OMIT, request_options: RequestOptions | None = None) → None

Open trace thread

Parameters:

  • thread_id (str)

  • project_name (Optional[str])

  • project_id (Optional[str])

  • truncate (Optional[bool])

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

Return type:

None

score_batch_of_threads(*, scores: Sequence[FeedbackScoreBatchItemThread], request_options: RequestOptions | None = None) → None

Batch feedback scoring for threads

Parameters:
Return type:

None

score_batch_of_traces(*, scores: Sequence[FeedbackScoreBatchItem], request_options: RequestOptions | None = None) → None

Batch feedback scoring for traces

Parameters:

  • scores (Sequence[FeedbackScoreBatchItem])

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

Return type:

None

search_trace_threads(*, project_name: str | None = OMIT, project_id: str | None = OMIT, filters: Sequence[TraceThreadFilter] | None = OMIT, last_retrieved_thread_model_id: str | None = OMIT, limit: int | None = OMIT, truncate: bool | None = OMIT, strip_attachments: bool | None = OMIT, from_time: datetime | None = OMIT, to_time: datetime | None = OMIT, request_options: RequestOptions | None = None) → Iterator[bytes]

Search trace threads

Parameters:

  • project_name (Optional[str])

  • project_id (Optional[str])

  • filters (Optional[Sequence[TraceThreadFilter]])

  • last_retrieved_thread_model_id (Optional[str])

  • limit (Optional[int]) – Max number of trace thread to be streamed

  • truncate (Optional[bool]) – Truncate input, output and metadata to slim payloads

  • strip_attachments (Optional[bool]) – If true, returns attachment references like [file.png]; if false, downloads and reinjects stripped attachments

  • from_time (Optional[dt.datetime]) – Filter trace threads created from this time (ISO-8601 format).

  • to_time (Optional[dt.datetime]) – Filter trace threads created up to this time (ISO-8601 format). If not provided, defaults to current time. Must be after ‘from_time’.

  • request_options (Optional[RequestOptions]) – Request-specific configuration. You can pass in configuration such as chunk_size, and more to customize the request and response.

Returns:

Trace threads stream or error during process

Return type:

Iterator[bytes]

search_traces(*, project_name: str | None = OMIT, project_id: str | None = OMIT, filters: Sequence[TraceFilterPublic] | None = OMIT, last_retrieved_id: str | None = OMIT, limit: int | None = OMIT, truncate: bool | None = OMIT, strip_attachments: bool | None = OMIT, exclude: Sequence[Literal['name', 'start_time', 'end_time', 'input', 'output', 'metadata', 'tags', 'error_info', 'usage', 'created_at', 'created_by', 'last_updated_by', 'feedback_scores', 'span_feedback_scores', 'comments', 'guardrails_validations', 'total_estimated_cost', 'span_count', 'llm_span_count', 'has_tool_spans', 'duration', 'ttft', 'thread_id', 'visibility_mode', 'providers', 'experiment', 'source', 'environment'] | Any] | None = OMIT, from_time: datetime | None = OMIT, to_time: datetime | None = OMIT, request_options: RequestOptions | None = None) → Iterator[bytes]

Search traces

Parameters:

  • project_name (Optional[str])

  • project_id (Optional[str])

  • filters (Optional[Sequence[TraceFilterPublic]])

  • last_retrieved_id (Optional[str])

  • limit (Optional[int]) – Max number of traces to be streamed

  • truncate (Optional[bool]) – Truncate input, output and metadata to slim payloads

  • strip_attachments (Optional[bool]) – If true, returns attachment references like [file.png]; if false, downloads and reinjects stripped attachments

  • exclude (Optional[Sequence[TraceSearchStreamRequestPublicExcludeItem]]) – Fields to exclude from the response

  • from_time (Optional[dt.datetime]) – Filter traces created from this time (ISO-8601 format).

  • to_time (Optional[dt.datetime]) – Filter traces created up to this time (ISO-8601 format). If not provided, defaults to current time. Must be after ‘from_time’.

  • request_options (Optional[RequestOptions]) – Request-specific configuration. You can pass in configuration such as chunk_size, and more to customize the request and response.

Returns:

Traces stream or error during process

Return type:

Iterator[bytes]

exist(*, project_id: str | None = None, project_name: str | None = None, source: str | None = None, thread_only: bool | None = None, request_options: RequestOptions | None = None) → ExistenceResponse

Returns whether the project has at least one trace matching the given scope. Cheap existence probe (LIMIT 1) used to drive empty-state decisions without scanning or aggregating the whole project.

Parameters:

  • project_id (Optional[str])

  • project_name (Optional[str])

  • source (Optional[str])

  • thread_only (Optional[bool])

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

Returns:

Trace existence

Return type:

ExistenceResponse

update_thread(thread_model_id: str, *, tags: Sequence[str] | None = OMIT, tags_to_add: Sequence[str] | None = OMIT, tags_to_remove: Sequence[str] | None = OMIT, request_options: RequestOptions | None = None) → None

Update thread

Parameters:

  • thread_model_id (str)

  • tags (Optional[Sequence[str]])

  • tags_to_add (Optional[Sequence[str]])

  • tags_to_remove (Optional[Sequence[str]])

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

Return type:

None

update_thread_comment(comment_id: str, *, text: str, id: str | None = OMIT, source_queue_id: str | None = OMIT, created_at: datetime | None = OMIT, last_updated_at: datetime | None = OMIT, created_by: str | None = OMIT, last_updated_by: str | None = OMIT, request_options: RequestOptions | None = None) → None

Update thread comment by id

Parameters:

  • comment_id (str)

  • text (str)

  • id (Optional[str])

  • source_queue_id (Optional[str])

  • created_at (Optional[dt.datetime])

  • last_updated_at (Optional[dt.datetime])

  • created_by (Optional[str])

  • last_updated_by (Optional[str])

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

Return type:

None

update_trace_comment(comment_id: str, *, text: str, id: str | None = OMIT, source_queue_id: str | None = OMIT, created_at: datetime | None = OMIT, last_updated_at: datetime | None = OMIT, created_by: str | None = OMIT, last_updated_by: str | None = OMIT, request_options: RequestOptions | None = None) → None

Update trace comment by id

Parameters:

  • comment_id (str)

  • text (str)

  • id (Optional[str])

  • source_queue_id (Optional[str])

  • created_at (Optional[dt.datetime])

  • last_updated_at (Optional[dt.datetime])

  • created_by (Optional[str])

  • last_updated_by (Optional[str])

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

Return type:

None

Usage Example

import opik

client = opik.Opik()

# Get a trace by ID
trace = client.rest_client.traces.get_trace_by_id("trace-id")

# Search for traces
traces = client.rest_client.traces.search_traces(
    project_name="my-project",
    max_results=100
)

# Add feedback score to a trace
client.rest_client.traces.add_trace_feedback_score(
    id="trace-id",
    name="accuracy",
    value=0.95
)