Skip to content
sgp
API Reference
Spans

Update a span

spans.update(strspan_id, SpanUpdateParams**kwargs) -> 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 served solely by the legacy trace store: once an account begins dual-writing to the 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.

Credential redaction: values in the free-form input, output, metadata, and expected objects, and in name, that are credential-shaped (bearer/JWT, API keys, connection-string passwords) or under a credential-named key are replaced with [REDACTED:credential] before the span is persisted, so the stored and returned span reflects the redacted value (EY 12.3).

ParametersExpand Collapse
span_id: str
end_timestamp: Optional[Union[str, datetime]]
formatdate-time
metadata: Optional[Dict[str, object]]
name: Optional[str]
output: Optional[Dict[str, object]]
status: Optional[SpanStatus]
One of the following:
"SUCCESS"
"ERROR"
"CANCELED"
ReturnsExpand Collapse
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"

Update a span

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
)
span = client.spans.update(
    span_id="span_id",
)
print(span.id)
{
  "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"
  },
  "input_tokens": 0,
  "metadata": {
    "foo": "bar"
  },
  "object": "span",
  "obs_span_id": "obs_span_id",
  "obs_trace_id": "obs_trace_id",
  "output": {
    "foo": "bar"
  },
  "output_tokens": 0,
  "parent_id": "parent_id",
  "status": "SUCCESS",
  "type": "TEXT_INPUT"
}
Returns Examples
{
  "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"
  },
  "input_tokens": 0,
  "metadata": {
    "foo": "bar"
  },
  "object": "span",
  "obs_span_id": "obs_span_id",
  "obs_trace_id": "obs_trace_id",
  "output": {
    "foo": "bar"
  },
  "output_tokens": 0,
  "parent_id": "parent_id",
  "status": "SUCCESS",
  "type": "TEXT_INPUT"
}