Documentation | Spans

Spans

SpansResource

Methods

client.spans.create() ->

post/v5/spans

Create a single span and return the persisted span.

Use this for one-off span ingestion; to write many spans in one request use POST /v5/spans/batch. When id is omitted the server generates a UUID. Depending on per-account server configuration the span is persisted to Postgres, to the ClickHouse-backed tracing service, or both; when the tracing service is the primary store, a write failure returns a retryable 503 with a Retry-After header.

client.spans.retrieve() ->

Span

get/v5/spans/{span_id}

Retrieve a single span by its id.

The span is read from Postgres or, for accounts migrated to the ClickHouse-backed tracing service, from that service — with automatic fallback to Postgres on error unless the account is in strict mode, where a tracing-service failure surfaces as a 503. Access is authorized against the span's parent trace, so a span in a trace the caller cannot read is rejected; an unknown id returns 404.

client.spans.update(, ) ->

Span

patch/v5/spans/{span_id}

Partially update a span's mutable fields and return the updated span.

Only the provided fields among name, end timestamp, output, metadata, and status are changed. This endpoint is available only for accounts still backed solely by Postgres: once an account begins dual-writing to the ClickHouse-backed tracing service — which is upsert-only and has no partial-update operation — PATCH returns 501 and PUT /v5/spans/batch must be used instead. Updates are authorized against the span's parent trace, and an unknown id returns 404.

client.spans.batch() ->

APIListSpan

post/v5/spans/batch

Create multiple spans (up to 1000) in a single request and return the created spans.

Prefer this over repeated POST /v5/spans calls when ingesting many spans at once; use PUT /v5/spans/batch instead when a span with the same id may already exist, since this endpoint inserts new spans rather than overwriting. A batch larger than 1000 spans is rejected with a validation error. Each item follows the same id-generation and per-account dual-write rules as the single-span create, and when the tracing service is the primary store a write failure returns a retryable 503.

client.spans.upsert_batch() ->

APIListSpan

put/v5/spans/batch

Insert or replace multiple spans (up to 1000) in a single request, keyed by span id.

Use this for idempotent ingestion where a span with the same id may already exist — it will be overwritten — unlike POST /v5/spans/batch, which only inserts. Items without an id are assigned a generated UUID, and duplicate ids within the request are collapsed to the last occurrence. A batch larger than 1000 spans is rejected with a validation error. The write follows the same per-account dual-write rules, and when the tracing service is the primary store a write failure returns a retryable 503.

client.spans.search() -> SyncCursorPage[

Span

]

post/v5/spans/search

Search and list spans matching a set of filters, returning a keyset-paginated page.

Filters in the request body include trace and span ids, names, statuses, types, free-text search, metadata, duration bounds, and more, scoped to an optional time window. Results are keyset-paginated on indexed columns rather than offset-paginated, and total is not computed (it is always 0); use the pagination cursors to page through results. Reads route to Postgres or the ClickHouse-backed tracing service per account (with Postgres fallback outside strict mode), and results are narrowed to traces the caller is authorized to read — a filter that resolves to no authorized traces yields an empty page rather than an error.

Parameters

ending_before: Optional[str]

from_ts: Optional[Union[str, datetime]]

(format: date-time)

The starting (oldest) timestamp in ISO format.

limit: Optional[int]

(maximum: 10000, minimum: 1, default: 100)

sort_by: Optional[str]

sort_order: Optional[

SortOrder

]

starting_after: Optional[str]

to_ts: Optional[Union[str, datetime]]

(format: date-time)

The ending (most recent) timestamp in ISO format.

acp_types: Optional[Sequence[str]]

Filter by ACP types

agentex_agent_ids: Optional[Sequence[str]]

Filter by Agentex agent IDs

agentex_agent_names: Optional[Sequence[str]]

Filter by Agentex agent names

application_variant_ids: Optional[Sequence[str]]

Filter by application variant IDs

assessment_types: Optional[Sequence[str]]

Filter spans by traces that have assessments of these types

excluded_span_ids: Optional[Sequence[str]]

List of span IDs to exclude from results

excluded_trace_ids: Optional[Sequence[str]]

List of trace IDs to exclude from results

extra_metadata: Optional[Dict[str,

object

]]

Filter on custom metadata key-value pairs

group_id: Optional[str]

Filter by group ID

max_duration_ms: Optional[int]

Maximum span duration in milliseconds (inclusive)

min_duration_ms: Optional[int]

Minimum span duration in milliseconds (inclusive)

names: Optional[Sequence[str]]

Filter by trace/span name

parent_ids: Optional[Sequence[str]]

Filter to the direct children of any of these parent span IDs

parents_only: Optional[

bool

]

Only fetch spans that are the top-level (ie. have no parent_id)

search_texts: Optional[Sequence[str]]

Free text search across span input and output fields. For exact trace ID lookup, use the trace_ids filter.

span_ids: Optional[Sequence[str]]

Filter by span IDs

statuses: Optional[List[

SpanStatus

]]

Filter on span status

"SUCCESS"

"ERROR"

"CANCELED"

trace_ids: Optional[Sequence[str]]

Filter by trace IDs

types: Optional[List[

SpanType

]]

"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"

Returns

Span

id: str

account_id: str

name: str

start_timestamp:

datetime

(format: date-time)

trace_id: str

(maxLength: 256)

id for grouping traces together, uuid is recommended

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.

end_timestamp: Optional[datetime]

(format: date-time)

expected: Optional[Dict[str,

object

]]

group_id: Optional[str]

Reference to a group_id

input: Optional[Dict[str,

object

]]

metadata: Optional[Dict[str,

object

]]

object: Optional[Literal["span"]]

(default: "span")

output: Optional[Dict[str,

object

]]

parent_id: Optional[str]

Reference to a parent span_id

status: Optional[SpanStatus]

type: Optional[SpanType]

Request example

import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
page = client.spans.search()
page = page.items[0]
print(page.id)

200Example

{
  "has_more": true,
  "items": [
    {
      "id": "id",
      "account_id": "account_id",
      "name": "name",
      "start_timestamp": "2019-12-27T18:11:19.117Z",
      "trace_id": "trace_id",
      "application_interaction_id": "application_interaction_id",
      "application_variant_id": "application_variant_id",
      "created_by": {
        "id": "id",
        "type": "user",
        "object": "identity"
      },
      "end_timestamp": "2019-12-27T18:11:19.117Z",
      "expected": {
        "foo": "bar"
      },
      "group_id": "group_id",
      "input": {
        "foo": "bar"
      },
      "metadata": {
        "foo": "bar"
      },
      "object": "span",
      "output": {
        "foo": "bar"
      },
      "parent_id": "parent_id",
      "status": "SUCCESS",
      "type": "TEXT_INPUT"
    }
  ],
  "total": 0,
  "limit": 0,
  "object": "list"
}

Domain types

class APIListSpan: ...

class Span: ...

class SpanBatchCreate: ...

class SpanCreate: ...

Literal["SUCCESS", "ERROR", "CANCELED"]

Literal["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"]