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_trace_comment(id_: str, *, text: str, 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

  • 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

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.add_trace_comment(id_=’id’, text=’text’, )

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, 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 feedback score

Parameters:

  • id (str)

  • name (str)

  • value (float)

  • source (FeedbackScoreSource)

  • category_name (Optional[str])

  • reason (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

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.add_trace_feedback_score(id=’id’, name=’name’, value=1.1, source=”ui”, )

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

Close trace thread

Parameters:

  • thread_id (str)

  • project_name (Optional[str])

  • project_id (Optional[str])

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

Return type:

None

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.close_trace_thread(thread_id=’thread_id’, )

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, sorting: str | None = None, exclude: 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])

  • sorting (Optional[str])

  • exclude (Optional[str])

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

Returns:

Trace resource

Return type:

TracePagePublic

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.get_traces_by_project()

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] | None = OMIT, tags: Sequence[str] | None = OMIT, error_info: ErrorInfoWrite | None = OMIT, last_updated_at: datetime | None = OMIT, thread_id: 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[JsonNodeWrite])

  • tags (Optional[Sequence[str]])

  • error_info (Optional[ErrorInfoWrite])

  • last_updated_at (Optional[dt.datetime])

  • thread_id (Optional[str])

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

Return type:

None

Examples

from Opik import OpikApi import datetime client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.create_trace(start_time=datetime.datetime.fromisoformat(“2024-01-15 09:30:00+00:00”, ), )

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

Examples

from Opik import OpikApi from Opik import TraceWrite import datetime client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.create_traces(traces=[TraceWrite(start_time=datetime.datetime.fromisoformat(“2024-01-15 09:30:00+00:00”, ), )], )

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

Get trace by id

Parameters:

  • id (str)

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

Returns:

Trace resource

Return type:

TracePublic

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.get_trace_by_id(id=’id’, )

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

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.delete_trace_by_id(id=’id’, )

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] | None = OMIT, tags: Sequence[str] | None = OMIT, error_info: ErrorInfo | None = OMIT, thread_id: 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[JsonNode])

  • tags (Optional[Sequence[str]])

  • error_info (Optional[ErrorInfo])

  • thread_id (Optional[str])

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

Return type:

None

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.update_trace(id=’id’, )

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

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.delete_trace_comments(ids=[‘ids’], )

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

Delete trace feedback score

Parameters:

  • id (str)

  • name (str)

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

Return type:

None

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.delete_trace_feedback_score(id=’id’, name=’name’, )

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

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.delete_trace_threads(thread_ids=[‘thread_ids’], )

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

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.delete_traces(ids=[‘ids’], )

find_feedback_score_names_2(*, project_id: str | None = None, request_options: RequestOptions | None = None) → List[str]

Find Feedback Score names

Parameters:

  • project_id (Optional[str])

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

Returns:

Feedback Scores resource

Return type:

List[str]

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.find_feedback_score_names_2()

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

Get trace stats

Parameters:

  • project_id (Optional[str])

  • project_name (Optional[str])

  • filters (Optional[str])

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

Returns:

Trace stats resource

Return type:

ProjectStatsPublic

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.get_trace_stats()

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

Get trace comment

Parameters:

  • comment_id (str)

  • trace_id (str)

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

Returns:

Comment resource

Return type:

Comment

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.get_trace_comment(comment_id=’commentId’, trace_id=’traceId’, )

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

Get trace thread

Parameters:

  • thread_id (str)

  • project_name (Optional[str])

  • project_id (Optional[str])

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

Returns:

Trace thread resource

Return type:

TraceThread

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.get_trace_thread(thread_id=’thread_id’, )

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, filters: str | None = None, sorting: 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])

  • filters (Optional[str])

  • sorting (Optional[str])

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

Returns:

Trace threads resource

Return type:

TraceThreadPage

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.get_trace_threads()

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

Open trace thread

Parameters:

  • thread_id (str)

  • project_name (Optional[str])

  • project_id (Optional[str])

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

Return type:

None

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.open_trace_thread(thread_id=’thread_id’, )

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

Examples

from Opik import OpikApi from Opik import FeedbackScoreBatchItem client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.score_batch_of_traces(scores=[FeedbackScoreBatchItem(id=’id’, name=’name’, value=1.1, source=”ui”, )], )

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, 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 image included in either input, output or metadata

  • 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]

update_trace_comment(comment_id: str, *, text: str, 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])

  • 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

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.traces.update_trace_comment(comment_id=’commentId’, text=’text’, )

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
)