API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Spans

Create a span

client.Spans.New(ctx, body) (*Span, error)

POST/v5/spans

Get a span

Deprecated

client.Spans.Get(ctx, spanID) (*Span, error)

GET/v5/spans/{span_id}

Update a span

client.Spans.Update(ctx, spanID, body) (*Span, error)

PATCH/v5/spans/{span_id}

Create spans in a batch

client.Spans.Batch(ctx, body) (*APIListSpan, error)

POST/v5/spans/batch

Upsert spans in a batch

client.Spans.UpsertBatch(ctx, body) (*APIListSpan, error)

PUT/v5/spans/batch

Search spans

client.Spans.Search(ctx, params) (*CursorPage[Span], error)

POST/v5/spans/search

ModelsExpand Collapse

type APIListSpan struct{…}

Items []Span

ID string

AccountID string

Name string

StartTimestamp Time

formatdate-time

TraceID string

id for grouping traces together, uuid is recommended

maxLength256

ApplicationInteractionID stringOptional

The interaction ID this span belongs to

ApplicationVariantID stringOptional

The id of the application variant this span belongs to

CreatedBy IdentityOptional

The identity that created the entity.

ID string

Type IdentityType

One of the following:

const IdentityTypeUser IdentityType = "user"

const IdentityTypeServiceAccount IdentityType = "service_account"

Object IdentityObjectOptional

EndTimestamp TimeOptional

formatdate-time

Expected map[string, any]Optional

GroupID stringOptional

Reference to a group_id

Input map[string, any]Optional

InputTokens int64Optional

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

maximum4294967295

minimum0

Metadata map[string, any]Optional

Object SpanObjectOptional

ObsSpanID stringOptional

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

ObsTraceID stringOptional

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 map[string, any]Optional

OutputTokens int64Optional

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

maximum4294967295

minimum0

ParentID stringOptional

Reference to a parent span_id

Status SpanStatusOptional

One of the following:

const SpanStatusSuccess SpanStatus = "SUCCESS"

const SpanStatusError SpanStatus = "ERROR"

const SpanStatusCanceled SpanStatus = "CANCELED"

Type SpanTypeOptional

One of the following:

const SpanTypeTextInput SpanType = "TEXT_INPUT"

const SpanTypeTextOutput SpanType = "TEXT_OUTPUT"

const SpanTypeCompletionInput SpanType = "COMPLETION_INPUT"

const SpanTypeCompletion SpanType = "COMPLETION"

const SpanTypeKBRetrieval SpanType = "KB_RETRIEVAL"

const SpanTypeKBInput SpanType = "KB_INPUT"

const SpanTypeReranking SpanType = "RERANKING"

const SpanTypeExternalEndpoint SpanType = "EXTERNAL_ENDPOINT"

const SpanTypePromptEngineering SpanType = "PROMPT_ENGINEERING"

const SpanTypeDocumentInput SpanType = "DOCUMENT_INPUT"

const SpanTypeMapReduce SpanType = "MAP_REDUCE"

const SpanTypeDocumentSearch SpanType = "DOCUMENT_SEARCH"

const SpanTypeDocumentPrompt SpanType = "DOCUMENT_PROMPT"

const SpanTypeCustom SpanType = "CUSTOM"

const SpanTypeCodeExecution SpanType = "CODE_EXECUTION"

const SpanTypeDataManipulation SpanType = "DATA_MANIPULATION"

const SpanTypeEvaluation SpanType = "EVALUATION"

const SpanTypeFileRetrieval SpanType = "FILE_RETRIEVAL"

const SpanTypeKBAddChunk SpanType = "KB_ADD_CHUNK"

const SpanTypeKBManagement SpanType = "KB_MANAGEMENT"

const SpanTypeGuardrail SpanType = "GUARDRAIL"

const SpanTypeOutputGuardrail SpanType = "OUTPUT_GUARDRAIL"

const SpanTypeTracer SpanType = "TRACER"

const SpanTypeAgentTracer SpanType = "AGENT_TRACER"

const SpanTypeAgentWorkflow SpanType = "AGENT_WORKFLOW"

const SpanTypeStandalone SpanType = "STANDALONE"

Object APIListSpanObjectOptional

type Span struct{…}

ID string

AccountID string

Name string

StartTimestamp Time

formatdate-time

TraceID string

id for grouping traces together, uuid is recommended

maxLength256

ApplicationInteractionID stringOptional

The interaction ID this span belongs to

ApplicationVariantID stringOptional

The id of the application variant this span belongs to

CreatedBy IdentityOptional

The identity that created the entity.

ID string

Type IdentityType

One of the following:

const IdentityTypeUser IdentityType = "user"

const IdentityTypeServiceAccount IdentityType = "service_account"

Object IdentityObjectOptional

EndTimestamp TimeOptional

formatdate-time

Expected map[string, any]Optional

GroupID stringOptional

Reference to a group_id

Input map[string, any]Optional

InputTokens int64Optional

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

maximum4294967295

minimum0

Metadata map[string, any]Optional

Object SpanObjectOptional

ObsSpanID stringOptional

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

ObsTraceID stringOptional

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 map[string, any]Optional

OutputTokens int64Optional

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

maximum4294967295

minimum0

ParentID stringOptional

Reference to a parent span_id

Status SpanStatusOptional

One of the following:

const SpanStatusSuccess SpanStatus = "SUCCESS"

const SpanStatusError SpanStatus = "ERROR"

const SpanStatusCanceled SpanStatus = "CANCELED"

Type SpanTypeOptional

One of the following:

const SpanTypeTextInput SpanType = "TEXT_INPUT"

const SpanTypeTextOutput SpanType = "TEXT_OUTPUT"

const SpanTypeCompletionInput SpanType = "COMPLETION_INPUT"

const SpanTypeCompletion SpanType = "COMPLETION"

const SpanTypeKBRetrieval SpanType = "KB_RETRIEVAL"

const SpanTypeKBInput SpanType = "KB_INPUT"

const SpanTypeReranking SpanType = "RERANKING"

const SpanTypeExternalEndpoint SpanType = "EXTERNAL_ENDPOINT"

const SpanTypePromptEngineering SpanType = "PROMPT_ENGINEERING"

const SpanTypeDocumentInput SpanType = "DOCUMENT_INPUT"

const SpanTypeMapReduce SpanType = "MAP_REDUCE"

const SpanTypeDocumentSearch SpanType = "DOCUMENT_SEARCH"

const SpanTypeDocumentPrompt SpanType = "DOCUMENT_PROMPT"

const SpanTypeCustom SpanType = "CUSTOM"

const SpanTypeCodeExecution SpanType = "CODE_EXECUTION"

const SpanTypeDataManipulation SpanType = "DATA_MANIPULATION"

const SpanTypeEvaluation SpanType = "EVALUATION"

const SpanTypeFileRetrieval SpanType = "FILE_RETRIEVAL"

const SpanTypeKBAddChunk SpanType = "KB_ADD_CHUNK"

const SpanTypeKBManagement SpanType = "KB_MANAGEMENT"

const SpanTypeGuardrail SpanType = "GUARDRAIL"

const SpanTypeOutputGuardrail SpanType = "OUTPUT_GUARDRAIL"

const SpanTypeTracer SpanType = "TRACER"

const SpanTypeAgentTracer SpanType = "AGENT_TRACER"

const SpanTypeAgentWorkflow SpanType = "AGENT_WORKFLOW"

const SpanTypeStandalone SpanType = "STANDALONE"

type SpanBatchCreate struct{…}

Items []SpanCreate

Name string

StartTimestamp Time

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

TraceID string

id for grouping traces together, uuid is recommended

maxLength256

ID stringOptional

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

ApplicationInteractionID stringOptional

The optional application interaction ID this span belongs to

ApplicationVariantID stringOptional

The optional application variant ID this span belongs to

EndTimestamp TimeOptional

formatdate-time

Expected map[string, any]Optional

GroupID stringOptional

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 map[string, any]Optional

Metadata map[string, any]Optional

ObsSpanID stringOptional

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

ObsTraceID stringOptional

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 map[string, any]Optional

ParentID stringOptional

Reference to a parent span_id

Status SpanStatusOptional

One of the following:

const SpanStatusSuccess SpanStatus = "SUCCESS"

const SpanStatusError SpanStatus = "ERROR"

const SpanStatusCanceled SpanStatus = "CANCELED"

Type SpanTypeOptional

One of the following:

const SpanTypeTextInput SpanType = "TEXT_INPUT"

const SpanTypeTextOutput SpanType = "TEXT_OUTPUT"

const SpanTypeCompletionInput SpanType = "COMPLETION_INPUT"

const SpanTypeCompletion SpanType = "COMPLETION"

const SpanTypeKBRetrieval SpanType = "KB_RETRIEVAL"

const SpanTypeKBInput SpanType = "KB_INPUT"

const SpanTypeReranking SpanType = "RERANKING"

const SpanTypeExternalEndpoint SpanType = "EXTERNAL_ENDPOINT"

const SpanTypePromptEngineering SpanType = "PROMPT_ENGINEERING"

const SpanTypeDocumentInput SpanType = "DOCUMENT_INPUT"

const SpanTypeMapReduce SpanType = "MAP_REDUCE"

const SpanTypeDocumentSearch SpanType = "DOCUMENT_SEARCH"

const SpanTypeDocumentPrompt SpanType = "DOCUMENT_PROMPT"

const SpanTypeCustom SpanType = "CUSTOM"

const SpanTypeCodeExecution SpanType = "CODE_EXECUTION"

const SpanTypeDataManipulation SpanType = "DATA_MANIPULATION"

const SpanTypeEvaluation SpanType = "EVALUATION"

const SpanTypeFileRetrieval SpanType = "FILE_RETRIEVAL"

const SpanTypeKBAddChunk SpanType = "KB_ADD_CHUNK"

const SpanTypeKBManagement SpanType = "KB_MANAGEMENT"

const SpanTypeGuardrail SpanType = "GUARDRAIL"

const SpanTypeOutputGuardrail SpanType = "OUTPUT_GUARDRAIL"

const SpanTypeTracer SpanType = "TRACER"

const SpanTypeAgentTracer SpanType = "AGENT_TRACER"

const SpanTypeAgentWorkflow SpanType = "AGENT_WORKFLOW"

const SpanTypeStandalone SpanType = "STANDALONE"

type SpanCreate struct{…}

Name string

StartTimestamp Time

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

TraceID string

id for grouping traces together, uuid is recommended

maxLength256

ID stringOptional

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

ApplicationInteractionID stringOptional

The optional application interaction ID this span belongs to

ApplicationVariantID stringOptional

The optional application variant ID this span belongs to

EndTimestamp TimeOptional

formatdate-time

Expected map[string, any]Optional

GroupID stringOptional

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 map[string, any]Optional

Metadata map[string, any]Optional

ObsSpanID stringOptional

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

ObsTraceID stringOptional

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 map[string, any]Optional

ParentID stringOptional

Reference to a parent span_id

Status SpanStatusOptional

One of the following:

const SpanStatusSuccess SpanStatus = "SUCCESS"

const SpanStatusError SpanStatus = "ERROR"

const SpanStatusCanceled SpanStatus = "CANCELED"

Type SpanTypeOptional

One of the following:

const SpanTypeTextInput SpanType = "TEXT_INPUT"

const SpanTypeTextOutput SpanType = "TEXT_OUTPUT"

const SpanTypeCompletionInput SpanType = "COMPLETION_INPUT"

const SpanTypeCompletion SpanType = "COMPLETION"

const SpanTypeKBRetrieval SpanType = "KB_RETRIEVAL"

const SpanTypeKBInput SpanType = "KB_INPUT"

const SpanTypeReranking SpanType = "RERANKING"

const SpanTypeExternalEndpoint SpanType = "EXTERNAL_ENDPOINT"

const SpanTypePromptEngineering SpanType = "PROMPT_ENGINEERING"

const SpanTypeDocumentInput SpanType = "DOCUMENT_INPUT"

const SpanTypeMapReduce SpanType = "MAP_REDUCE"

const SpanTypeDocumentSearch SpanType = "DOCUMENT_SEARCH"

const SpanTypeDocumentPrompt SpanType = "DOCUMENT_PROMPT"

const SpanTypeCustom SpanType = "CUSTOM"

const SpanTypeCodeExecution SpanType = "CODE_EXECUTION"

const SpanTypeDataManipulation SpanType = "DATA_MANIPULATION"

const SpanTypeEvaluation SpanType = "EVALUATION"

const SpanTypeFileRetrieval SpanType = "FILE_RETRIEVAL"

const SpanTypeKBAddChunk SpanType = "KB_ADD_CHUNK"

const SpanTypeKBManagement SpanType = "KB_MANAGEMENT"

const SpanTypeGuardrail SpanType = "GUARDRAIL"

const SpanTypeOutputGuardrail SpanType = "OUTPUT_GUARDRAIL"

const SpanTypeTracer SpanType = "TRACER"

const SpanTypeAgentTracer SpanType = "AGENT_TRACER"

const SpanTypeAgentWorkflow SpanType = "AGENT_WORKFLOW"

const SpanTypeStandalone SpanType = "STANDALONE"

type SpanStatus string

One of the following:

const SpanStatusSuccess SpanStatus = "SUCCESS"

const SpanStatusError SpanStatus = "ERROR"

const SpanStatusCanceled SpanStatus = "CANCELED"

type SpanType string

One of the following:

const SpanTypeTextInput SpanType = "TEXT_INPUT"

const SpanTypeTextOutput SpanType = "TEXT_OUTPUT"

const SpanTypeCompletionInput SpanType = "COMPLETION_INPUT"

const SpanTypeCompletion SpanType = "COMPLETION"

const SpanTypeKBRetrieval SpanType = "KB_RETRIEVAL"

const SpanTypeKBInput SpanType = "KB_INPUT"

const SpanTypeReranking SpanType = "RERANKING"

const SpanTypeExternalEndpoint SpanType = "EXTERNAL_ENDPOINT"

const SpanTypePromptEngineering SpanType = "PROMPT_ENGINEERING"

const SpanTypeDocumentInput SpanType = "DOCUMENT_INPUT"

const SpanTypeMapReduce SpanType = "MAP_REDUCE"

const SpanTypeDocumentSearch SpanType = "DOCUMENT_SEARCH"

const SpanTypeDocumentPrompt SpanType = "DOCUMENT_PROMPT"

const SpanTypeCustom SpanType = "CUSTOM"

const SpanTypeCodeExecution SpanType = "CODE_EXECUTION"

const SpanTypeDataManipulation SpanType = "DATA_MANIPULATION"

const SpanTypeEvaluation SpanType = "EVALUATION"

const SpanTypeFileRetrieval SpanType = "FILE_RETRIEVAL"

const SpanTypeKBAddChunk SpanType = "KB_ADD_CHUNK"

const SpanTypeKBManagement SpanType = "KB_MANAGEMENT"

const SpanTypeGuardrail SpanType = "GUARDRAIL"

const SpanTypeOutputGuardrail SpanType = "OUTPUT_GUARDRAIL"

const SpanTypeTracer SpanType = "TRACER"

const SpanTypeAgentTracer SpanType = "AGENT_TRACER"

const SpanTypeAgentWorkflow SpanType = "AGENT_WORKFLOW"

const SpanTypeStandalone SpanType = "STANDALONE"