Skip to content

Spans

Create a span
spans.create(SpanCreateParams**kwargs) -> Span
POST/v5/spans
Get a span
Deprecated
spans.retrieve(strspan_id) -> Span
GET/v5/spans/{span_id}
Update a span
spans.update(strspan_id, SpanUpdateParams**kwargs) -> Span
PATCH/v5/spans/{span_id}
Create spans in a batch
spans.batch(SpanBatchParams**kwargs) -> APIListSpan
POST/v5/spans/batch
Upsert spans in a batch
spans.upsert_batch(SpanUpsertBatchParams**kwargs) -> APIListSpan
PUT/v5/spans/batch
Search spans
spans.search(SpanSearchParams**kwargs) -> SyncCursorPage[Span]
POST/v5/spans/search
ModelsExpand Collapse
class APIListSpan: …
items: List[Span]
id: str
account_id: str
name: str
start_timestamp: datetime
formatdate-time
trace_id: str

id for grouping traces together, uuid is recommended

maxLength256
application_interaction_id: Optional[str]

The interaction ID this span belongs to

application_variant_id: Optional[str]

The id of the application variant this span belongs to

created_by: Optional[Identity]

The identity that created the entity.

id: str
type: Literal["user", "service_account"]
One of the following:
"user"
"service_account"
object: Optional[Literal["identity"]]
end_timestamp: Optional[datetime]
formatdate-time
expected: Optional[Dict[str, object]]
group_id: Optional[str]

Reference to a group_id

input: Optional[Dict[str, object]]
input_tokens: Optional[int]

Prompt tokens the producer reported for this span, absent when it reported none. Same quantity the input_tokens sort orders by.

maximum4294967295
minimum0
metadata: Optional[Dict[str, object]]
object: Optional[Literal["span"]]
obs_span_id: Optional[str]

W3C span id of the observability span this span executed in.

obs_trace_id: Optional[str]

W3C trace id of the observability trace this span executed in. Null for spans written without the edge, and for accounts still served by the legacy trace store.

output: Optional[Dict[str, object]]
output_tokens: Optional[int]

Completion tokens the producer reported for this span, absent when it reported none. Same quantity the output_tokens sort orders by.

maximum4294967295
minimum0
parent_id: Optional[str]

Reference to a parent span_id

status: Optional[SpanStatus]
One of the following:
"SUCCESS"
"ERROR"
"CANCELED"
type: Optional[SpanType]
One of the following:
"TEXT_INPUT"
"TEXT_OUTPUT"
"COMPLETION_INPUT"
"COMPLETION"
"KB_RETRIEVAL"
"KB_INPUT"
"RERANKING"
"EXTERNAL_ENDPOINT"
"PROMPT_ENGINEERING"
"DOCUMENT_INPUT"
"MAP_REDUCE"
"DOCUMENT_SEARCH"
"DOCUMENT_PROMPT"
"CUSTOM"
"CODE_EXECUTION"
"DATA_MANIPULATION"
"EVALUATION"
"FILE_RETRIEVAL"
"KB_ADD_CHUNK"
"KB_MANAGEMENT"
"GUARDRAIL"
"OUTPUT_GUARDRAIL"
"TRACER"
"AGENT_TRACER"
"AGENT_WORKFLOW"
"STANDALONE"
object: Optional[Literal["list"]]
class Span: …
id: str
account_id: str
name: str
start_timestamp: datetime
formatdate-time
trace_id: str

id for grouping traces together, uuid is recommended

maxLength256
application_interaction_id: Optional[str]

The interaction ID this span belongs to

application_variant_id: Optional[str]

The id of the application variant this span belongs to

created_by: Optional[Identity]

The identity that created the entity.

id: str
type: Literal["user", "service_account"]
One of the following:
"user"
"service_account"
object: Optional[Literal["identity"]]
end_timestamp: Optional[datetime]
formatdate-time
expected: Optional[Dict[str, object]]
group_id: Optional[str]

Reference to a group_id

input: Optional[Dict[str, object]]
input_tokens: Optional[int]

Prompt tokens the producer reported for this span, absent when it reported none. Same quantity the input_tokens sort orders by.

maximum4294967295
minimum0
metadata: Optional[Dict[str, object]]
object: Optional[Literal["span"]]
obs_span_id: Optional[str]

W3C span id of the observability span this span executed in.

obs_trace_id: Optional[str]

W3C trace id of the observability trace this span executed in. Null for spans written without the edge, and for accounts still served by the legacy trace store.

output: Optional[Dict[str, object]]
output_tokens: Optional[int]

Completion tokens the producer reported for this span, absent when it reported none. Same quantity the output_tokens sort orders by.

maximum4294967295
minimum0
parent_id: Optional[str]

Reference to a parent span_id

status: Optional[SpanStatus]
One of the following:
"SUCCESS"
"ERROR"
"CANCELED"
type: Optional[SpanType]
One of the following:
"TEXT_INPUT"
"TEXT_OUTPUT"
"COMPLETION_INPUT"
"COMPLETION"
"KB_RETRIEVAL"
"KB_INPUT"
"RERANKING"
"EXTERNAL_ENDPOINT"
"PROMPT_ENGINEERING"
"DOCUMENT_INPUT"
"MAP_REDUCE"
"DOCUMENT_SEARCH"
"DOCUMENT_PROMPT"
"CUSTOM"
"CODE_EXECUTION"
"DATA_MANIPULATION"
"EVALUATION"
"FILE_RETRIEVAL"
"KB_ADD_CHUNK"
"KB_MANAGEMENT"
"GUARDRAIL"
"OUTPUT_GUARDRAIL"
"TRACER"
"AGENT_TRACER"
"AGENT_WORKFLOW"
"STANDALONE"
class SpanBatchCreate: …
items: List[SpanCreate]
name: str
start_timestamp: datetime

When the span started. With trace_id and id it forms the span’s storage identity, so a span re-sent with a start_timestamp on another UTC day is stored as a second row that the store never collapses. Get span and trace detail return the newest version. Search returns the newest version whose start_timestamp falls in the queried window. Export, metrics and facets count both rows until the trace is deleted and re-sent.

formatdate-time
trace_id: str

id for grouping traces together, uuid is recommended

maxLength256
id: Optional[str]

The id of the span, at most 256 bytes. A value longer than 256 characters is refused here with a 422 before it is forwarded; a value within that count whose UTF-8 form exceeds 256 bytes is refused with a 400 naming the field once the tracing service is the account’s primary store, and accepted for accounts still written primarily to the legacy trace store.

maxLength256
application_interaction_id: Optional[str]

The optional application interaction ID this span belongs to

application_variant_id: Optional[str]

The optional application variant ID this span belongs to

end_timestamp: Optional[datetime]
formatdate-time
expected: Optional[Dict[str, object]]
group_id: Optional[str]

Reference to a group_id, at most 256 bytes. A value longer than 256 characters is refused here with a 422 before it is forwarded; a value within that count whose UTF-8 form exceeds 256 bytes is refused with a 400 naming the field once the tracing service is the account’s primary store, and accepted for accounts still written primarily to the legacy trace store.

maxLength256
input: Optional[Dict[str, object]]
metadata: Optional[Dict[str, object]]
obs_span_id: Optional[str]

W3C span id (16 lowercase hex chars) of the observability span this span executed in. Requires obs_trace_id.

obs_trace_id: Optional[str]

W3C trace id (32 lowercase hex chars) of the observability trace this span executed in, for correlating a business span with the infrastructure work it caused. Stored only by the sgp-traces service, so accounts still served by the legacy store accept the field and read it back as null.

output: Optional[Dict[str, object]]
parent_id: Optional[str]

Reference to a parent span_id

status: Optional[SpanStatus]
One of the following:
"SUCCESS"
"ERROR"
"CANCELED"
type: Optional[SpanType]
One of the following:
"TEXT_INPUT"
"TEXT_OUTPUT"
"COMPLETION_INPUT"
"COMPLETION"
"KB_RETRIEVAL"
"KB_INPUT"
"RERANKING"
"EXTERNAL_ENDPOINT"
"PROMPT_ENGINEERING"
"DOCUMENT_INPUT"
"MAP_REDUCE"
"DOCUMENT_SEARCH"
"DOCUMENT_PROMPT"
"CUSTOM"
"CODE_EXECUTION"
"DATA_MANIPULATION"
"EVALUATION"
"FILE_RETRIEVAL"
"KB_ADD_CHUNK"
"KB_MANAGEMENT"
"GUARDRAIL"
"OUTPUT_GUARDRAIL"
"TRACER"
"AGENT_TRACER"
"AGENT_WORKFLOW"
"STANDALONE"
class SpanCreate: …
name: str
start_timestamp: datetime

When the span started. With trace_id and id it forms the span’s storage identity, so a span re-sent with a start_timestamp on another UTC day is stored as a second row that the store never collapses. Get span and trace detail return the newest version. Search returns the newest version whose start_timestamp falls in the queried window. Export, metrics and facets count both rows until the trace is deleted and re-sent.

formatdate-time
trace_id: str

id for grouping traces together, uuid is recommended

maxLength256
id: Optional[str]

The id of the span, at most 256 bytes. A value longer than 256 characters is refused here with a 422 before it is forwarded; a value within that count whose UTF-8 form exceeds 256 bytes is refused with a 400 naming the field once the tracing service is the account’s primary store, and accepted for accounts still written primarily to the legacy trace store.

maxLength256
application_interaction_id: Optional[str]

The optional application interaction ID this span belongs to

application_variant_id: Optional[str]

The optional application variant ID this span belongs to

end_timestamp: Optional[datetime]
formatdate-time
expected: Optional[Dict[str, object]]
group_id: Optional[str]

Reference to a group_id, at most 256 bytes. A value longer than 256 characters is refused here with a 422 before it is forwarded; a value within that count whose UTF-8 form exceeds 256 bytes is refused with a 400 naming the field once the tracing service is the account’s primary store, and accepted for accounts still written primarily to the legacy trace store.

maxLength256
input: Optional[Dict[str, object]]
metadata: Optional[Dict[str, object]]
obs_span_id: Optional[str]

W3C span id (16 lowercase hex chars) of the observability span this span executed in. Requires obs_trace_id.

obs_trace_id: Optional[str]

W3C trace id (32 lowercase hex chars) of the observability trace this span executed in, for correlating a business span with the infrastructure work it caused. Stored only by the sgp-traces service, so accounts still served by the legacy store accept the field and read it back as null.

output: Optional[Dict[str, object]]
parent_id: Optional[str]

Reference to a parent span_id

status: Optional[SpanStatus]
One of the following:
"SUCCESS"
"ERROR"
"CANCELED"
type: Optional[SpanType]
One of the following:
"TEXT_INPUT"
"TEXT_OUTPUT"
"COMPLETION_INPUT"
"COMPLETION"
"KB_RETRIEVAL"
"KB_INPUT"
"RERANKING"
"EXTERNAL_ENDPOINT"
"PROMPT_ENGINEERING"
"DOCUMENT_INPUT"
"MAP_REDUCE"
"DOCUMENT_SEARCH"
"DOCUMENT_PROMPT"
"CUSTOM"
"CODE_EXECUTION"
"DATA_MANIPULATION"
"EVALUATION"
"FILE_RETRIEVAL"
"KB_ADD_CHUNK"
"KB_MANAGEMENT"
"GUARDRAIL"
"OUTPUT_GUARDRAIL"
"TRACER"
"AGENT_TRACER"
"AGENT_WORKFLOW"
"STANDALONE"
Literal["SUCCESS", "ERROR", "CANCELED"]
One of the following:
"SUCCESS"
"ERROR"
"CANCELED"
Literal["TEXT_INPUT", "TEXT_OUTPUT", "COMPLETION_INPUT", 23 more]
One of the following:
"TEXT_INPUT"
"TEXT_OUTPUT"
"COMPLETION_INPUT"
"COMPLETION"
"KB_RETRIEVAL"
"KB_INPUT"
"RERANKING"
"EXTERNAL_ENDPOINT"
"PROMPT_ENGINEERING"
"DOCUMENT_INPUT"
"MAP_REDUCE"
"DOCUMENT_SEARCH"
"DOCUMENT_PROMPT"
"CUSTOM"
"CODE_EXECUTION"
"DATA_MANIPULATION"
"EVALUATION"
"FILE_RETRIEVAL"
"KB_ADD_CHUNK"
"KB_MANAGEMENT"
"GUARDRAIL"
"OUTPUT_GUARDRAIL"
"TRACER"
"AGENT_TRACER"
"AGENT_WORKFLOW"
"STANDALONE"