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.

Parameters

items: Iterable[

SpanCreateParam

]

name: str

start_timestamp:

datetime

(format: date-time)

trace_id: str

(maxLength: 256)

id for grouping traces together, uuid is recommended

id: Optional[str]

The id of the span

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]

(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

]]

output: Optional[Dict[str,

object

]]

parent_id: Optional[str]

Reference to a parent span_id

status: Optional[SpanStatus]

type: Optional[SpanType]

Returns

APIListSpan

items: List[

Span

]

object: Optional[Literal["list"]]

(default: "list")

Request example

import os
from datetime import datetime
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
api_list_span = client.spans.batch(
    items=[{
        "name": "name",
        "start_timestamp": datetime.fromisoformat("2019-12-27T18:11:19.117"),
        "trace_id": "trace_id",
    }],
)
print(api_list_span.items)

200Example

{
  "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"
    }
  ],
  "object": "list"
}

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.

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