Spans Client¶

The Spans client provides methods for managing spans in the Opik platform.

class opik.rest_api.spans.client.SpansClient(*, client_wrapper: SyncClientWrapper)¶

Bases: object

Add span 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.spans.add_span_comment(id_=’id’, text=’text’, )

add_span_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 span 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.spans.add_span_feedback_score(id=’id’, name=’name’, value=1.1, source=”ui”, )

Get spans by project_name or project_id and optionally by trace_id and/or type

Parameters:

page (Optional[int])
size (Optional[int])
project_name (Optional[str])
project_id (Optional[str])
trace_id (Optional[str])
type (Optional[GetSpansByProjectRequestType])
filters (Optional[str])
truncate (Optional[bool])
sorting (Optional[str])
exclude (Optional[str])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Spans resource

Return type:

SpanPagePublic

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.spans.get_spans_by_project()

Create span

Parameters:

start_time (dt.datetime)
id (Optional[str])
project_name (Optional[str]) – If null, the default project is used
trace_id (Optional[str])
parent_span_id (Optional[str])
name (Optional[str])
type (Optional[SpanWriteType])
end_time (Optional[dt.datetime])
input (Optional[JsonListStringWrite])
output (Optional[JsonListStringWrite])
metadata (Optional[JsonNodeWrite])
model (Optional[str])
provider (Optional[str])
tags (Optional[Sequence[str]])
usage (Optional[Dict[str, int]])
error_info (Optional[ErrorInfoWrite])
last_updated_at (Optional[dt.datetime])
total_estimated_cost (Optional[float])
total_estimated_cost_version (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.spans.create_span(start_time=datetime.datetime.fromisoformat(“2024-01-15 09:30:00+00:00”, ), )

create_spans(*, spans: Sequence[SpanWrite], request_options: RequestOptions | None = None) → None¶

Create spans

Parameters:

spans (Sequence[SpanWrite])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Examples

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

get_span_by_id(id: str, *, request_options: RequestOptions | None = None) → SpanPublic¶

Get span by id

Parameters:

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

Returns:

Span resource

Return type:

SpanPublic

Examples

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

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

Delete span 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.spans.delete_span_by_id(id=’id’, )

Update span by id

Parameters:

id (str)
trace_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
parent_span_id (Optional[str])
name (Optional[str])
type (Optional[SpanUpdateType])
end_time (Optional[dt.datetime])
input (Optional[JsonListString])
output (Optional[JsonListString])
metadata (Optional[JsonNode])
model (Optional[str])
provider (Optional[str])
tags (Optional[Sequence[str]])
usage (Optional[Dict[str, int]])
total_estimated_cost (Optional[float])
error_info (Optional[ErrorInfo])
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.spans.update_span(id=’id’, trace_id=’trace_id’, )

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

Delete span 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.spans.delete_span_comments(ids=[‘ids’], )

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

Delete span 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.spans.delete_span_feedback_score(id=’id’, name=’name’, )

find_feedback_score_names_1(*, project_id: str | None = None, type: Literal['general', 'tool', 'llm', 'guardrail'] | Any | None = None, request_options: RequestOptions | None = None) → List[str]¶

Find Feedback Score names

Parameters:

project_id (Optional[str])
type (Optional[FindFeedbackScoreNames1RequestType])
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.spans.find_feedback_score_names_1()

get_span_comment(comment_id: str, span_id: str, *, request_options: RequestOptions | None = None) → Comment¶

Get span comment

Parameters:

comment_id (str)
span_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.spans.get_span_comment(comment_id=’commentId’, span_id=’spanId’, )

Get span stats

Parameters:

project_id (Optional[str])
project_name (Optional[str])
trace_id (Optional[str])
type (Optional[GetSpanStatsRequestType])
filters (Optional[str])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Span stats resource

Return type:

ProjectStatsPublic

Examples

from Opik import OpikApi client = OpikApi(api_key=”YOUR_API_KEY”, workspace_name=”YOUR_WORKSPACE_NAME”, ) client.spans.get_span_stats()

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

Batch feedback scoring for spans

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.spans.score_batch_of_spans(scores=[FeedbackScoreBatchItem(id=’id’, name=’name’, value=1.1, source=”ui”, )], )

Search spans

Parameters:

trace_id (Optional[str])
project_name (Optional[str])
project_id (Optional[str])
type (Optional[SpanSearchStreamRequestPublicType])
filters (Optional[Sequence[SpanFilterPublic]])
limit (Optional[int]) – Max number of spans to be streamed
last_retrieved_id (Optional[str])
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:

Spans stream or error during process

Return type:

Iterator[bytes]

Update span 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.spans.update_span_comment(comment_id=’commentId’, text=’text’, )

Usage Example¶

import opik

client = opik.Opik()

# Get a span by ID
span = client.rest_client.spans.get_span_by_id("span-id")

# Search for spans
spans = client.rest_client.spans.search_spans(
    project_name="my-project",
    trace_id="trace-id",
    max_results=100
)

# Add feedback score to a span
client.rest_client.spans.add_span_feedback_score(
    id="span-id",
    name="relevance",
    value=0.85
)