## Upsert spans in a batch `spans.upsert_batch(SpanUpsertBatchParams**kwargs) -> APIListSpan` **put** `/v5/spans/batch` Insert or replace multiple spans (up to 1000) in a single request. Use this for idempotent ingestion when spans may already exist, unlike POST /v5/spans/batch, which only inserts. Items without an `id` are assigned a generated UUID. The legacy trace store treats `id` as global and collapses repeated `id`s to the last occurrence. The tracing service keys spans by `trace_id` and `id`; it retains cross-trace ID collisions, and for a repeated pair keeps a completed span over an in-progress one, otherwise the later occurrence wins. In dual-write phases each store applies its own rule, and the primary store determines the returned list. A batch larger than 1000 spans is rejected with a validation error, as is any item whose `end_timestamp` precedes its `start_timestamp`, which returns a 422. When the tracing service is the primary store, its 400, 413 and 422 rejections keep that status and detail, as does a 403 when the request carried its own API key, and every other failure returns a 503 with a Retry-After header. A batch that forms a cycle, or a span whose parent belongs to another trace, is rejected with 409 before either store is written. A parent outside the batch is looked up in Postgres, so that part of the check ends once the account's spans stop being written there. Which writes the tracing service rejects depends in part on its storage engine: on Postgres deployments a NUL byte or invalid UTF-8 inside `trace_id`, `id`, `parent_id` or `group_id` fails the whole batch with a 400 naming the field, because replacing the byte would change the identity the response echoes; a NUL byte or invalid UTF-8 in any other field is replaced with U+FFFD and the span is persisted. ClickHouse deployments store the bytes verbatim. 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). ### Parameters - `items: Iterable[SpanCreateParam]` - `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. - `trace_id: str` id for grouping traces together, uuid is recommended - `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. - `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]` - `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. - `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]` - `"SUCCESS"` - `"ERROR"` - `"CANCELED"` - `type: Optional[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 - `class APIListSpan: …` - `items: List[Span]` - `id: str` - `account_id: str` - `name: str` - `start_timestamp: datetime` - `trace_id: str` 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. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `end_timestamp: Optional[datetime]` - `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. - `metadata: Optional[Dict[str, object]]` - `object: Optional[Literal["span"]]` - `"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. - `parent_id: Optional[str]` Reference to a parent span_id - `status: Optional[SpanStatus]` - `"SUCCESS"` - `"ERROR"` - `"CANCELED"` - `type: Optional[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"` - `object: Optional[Literal["list"]]` - `"list"` ### Example ```python 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.upsert_batch( items=[{ "name": "name", "start_timestamp": datetime.fromisoformat("2019-12-27T18:11:19.117"), "trace_id": "trace_id", }], ) print(api_list_span.items) ``` #### Response ```json { "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" }, "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" } ], "object": "list" } ```