> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert spans in a 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.



## OpenAPI

````yaml /openapi/v5.yaml put /v5/spans/batch
openapi: 3.1.0
info:
  title: EGP API V5
  description: >-
    This is the parent API for all EGP APIs. If you are looking for the EGP API,
    please go to https://api.egp.scale.com/docs.
  contact:
    name: Scale Generative AI Platform
    url: https://scale.com/genai-platform
  version: 0.1.0
servers:
  - url: https://api.egp.scale.com
security: []
paths:
  /v5/spans/batch:
    put:
      tags:
        - Spans
      summary: Upsert spans in a batch
      description: >-
        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.
      operationId: PUT-V5-/v5/spans/batch
      parameters:
        - name: x-selected-account-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpanBatchCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIList_Span_'
        '400':
          description: The tracing service rejected the request as malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanWriteErrorResponse'
        '403':
          description: The API key in the request is not allowed to write these spans.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanWriteErrorResponse'
        '409':
          description: >-
            The spans form a cycle, a span's parent belongs to another trace, or
            Postgres already holds one of the ids.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanWriteErrorResponse'
        '413':
          description: The request body exceeded the tracing service's size limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanWriteErrorResponse'
        '422':
          description: >-
            The request failed validation. This API returns one entry per
            offending field, while a rejection forwarded from the tracing
            service returns a single message.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/HTTPValidationError'
                  - $ref: '#/components/schemas/SpanWriteErrorResponse'
        '503':
          description: The spans were not stored and the request can be retried.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanWriteErrorResponse'
      security:
        - APIKeyHeader: []
components:
  schemas:
    SpanBatchCreateRequest:
      properties:
        items:
          items:
            $ref: '#/components/schemas/SpanCreateRequest'
          type: array
          title: Items
      type: object
      required:
        - items
      title: SpanBatchCreateRequest
    APIList_Span_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/Span'
          type: array
          title: Items
      type: object
      required:
        - items
    SpanWriteErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: >-
            Why the write failed. Forwarded from the tracing service when it
            supplied an RFC 9457 detail, otherwise a generic message.
      type: object
      required:
        - detail
      title: SpanWriteErrorResponse
      description: Error body of a span write that was rejected or could not be completed.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SpanCreateRequest:
      properties:
        id:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
          title: Id
          description: >-
            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.
        name:
          type: string
          title: Name
        trace_id:
          type: string
          maxLength: 256
          title: Trace Id
          description: id for grouping traces together, uuid is recommended
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
          description: Reference to a parent span_id
        group_id:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
          title: Group Id
          description: >-
            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.
        start_timestamp:
          type: string
          format: date-time
          title: Start Timestamp
          description: >-
            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.
        end_timestamp:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: End Timestamp
        input:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Input
        output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
        status:
          anyOf:
            - $ref: '#/components/schemas/ApplicationOperationStatus'
            - type: 'null'
          default: SUCCESS
        type:
          anyOf:
            - $ref: '#/components/schemas/ApplicationOperationType'
            - type: 'null'
          default: STANDALONE
        application_interaction_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Application Interaction Id
          description: The optional application interaction ID this span belongs to
        application_variant_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Application Variant Id
          description: The optional application variant ID this span belongs to
        expected:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Expected
        obs_trace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Obs Trace Id
          description: >-
            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.
        obs_span_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Obs Span Id
          description: >-
            W3C span id (16 lowercase hex chars) of the observability span this
            span executed in. Requires obs_trace_id.
      type: object
      required:
        - name
        - trace_id
        - start_timestamp
      title: SpanCreateRequest
    Span:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: span
          title: Object
          default: span
        created_by:
          anyOf:
            - $ref: '#/components/schemas/Identity'
            - type: 'null'
          description: The identity that created the entity.
        name:
          type: string
          title: Name
        trace_id:
          type: string
          maxLength: 256
          title: Trace Id
          description: id for grouping traces together, uuid is recommended
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
          description: Reference to a parent span_id
        group_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Group Id
          description: Reference to a group_id
        start_timestamp:
          type: string
          format: date-time
          title: Start Timestamp
        end_timestamp:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: End Timestamp
        input:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Input
        output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
        expected:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Expected
        status:
          anyOf:
            - $ref: '#/components/schemas/ApplicationOperationStatus'
            - type: 'null'
          default: SUCCESS
        type:
          anyOf:
            - $ref: '#/components/schemas/ApplicationOperationType'
            - type: 'null'
          default: STANDALONE
        application_interaction_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Application Interaction Id
          description: The interaction ID this span belongs to
        application_variant_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Application Variant Id
          description: The id of the application variant this span belongs to
        obs_trace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Obs Trace Id
          description: >-
            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.
        obs_span_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Obs Span Id
          description: W3C span id of the observability span this span executed in.
        input_tokens:
          anyOf:
            - type: integer
              maximum: 4294967295
              minimum: 0
            - type: 'null'
          title: Input Tokens
          description: >-
            Prompt tokens the producer reported for this span, absent when it
            reported none. Same quantity the input_tokens sort orders by.
        output_tokens:
          anyOf:
            - type: integer
              maximum: 4294967295
              minimum: 0
            - type: 'null'
          title: Output Tokens
          description: >-
            Completion tokens the producer reported for this span, absent when
            it reported none. Same quantity the output_tokens sort orders by.
        account_id:
          type: string
          title: Account Id
      type: object
      required:
        - id
        - name
        - trace_id
        - start_timestamp
        - account_id
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ApplicationOperationStatus:
      type: string
      enum:
        - SUCCESS
        - ERROR
        - CANCELED
      title: ApplicationOperationStatus
    ApplicationOperationType:
      type: string
      enum:
        - 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
      title: ApplicationOperationType
    Identity:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: identity
          title: Object
          default: identity
        type:
          $ref: '#/components/schemas/IdentityType'
      type: object
      required:
        - id
        - type
      title: Identity
    IdentityType:
      type: string
      enum:
        - user
        - service_account
      title: IdentityType
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````