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

# Create spans batch

> Create multiple spans in a single API call. Partial success, not all-or-nothing: a span refused for a data problem (empty name, negative latency, oversize payload, unknown trace) does not stop its siblings, and its trace records how many of its spans were dropped. Set `includeRejected=true` to read which spans were refused. A span you are not allowed to write is the one exception and refuses the whole batch with a 403. See [Spans](https://docs.galtea.ai/sdk/api/span/service). These endpoints serve spans, the steps inside a trace. Their REST path `/traces` keeps the old name of this entity.

> [!WARNING]
>
> You are reading the docs of Galtea 5.16. [Read this page in the latest version](https://docs.galtea.ai/api-reference/spans/create-spans-batch.md).


## OpenAPI

````yaml /v5.16/openapi.json post /traces/batch
openapi: 3.0.0
info:
  version: 1.0.0
  title: Product Management Service API
  description: API documentation for Product Management Service
  contact:
    name: Galtea AI
servers:
  - url: https://api.galtea.ai
security:
  - bearerAuth: []
tags: []
externalDocs:
  description: Galtea Platform Documentation
  url: https://docs.galtea.ai
paths:
  /traces/batch:
    post:
      tags:
        - spans
      summary: Create spans batch
      description: >-
        Create multiple spans in a single API call. Partial success, not
        all-or-nothing: a span refused for a data problem (empty name, negative
        latency, oversize payload, unknown trace) does not stop its siblings,
        and its trace records how many of its spans were dropped. Set
        `includeRejected=true` to read which spans were refused. A span you are
        not allowed to write is the one exception and refuses the whole batch
        with a 403. See [Spans](https://docs.galtea.ai/sdk/api/span/service).
        These endpoints serve spans, the steps inside a trace. Their REST path
        `/traces` keeps the old name of this entity.
      operationId: createTracesBatch
      parameters:
        - name: includeRejected
          in: query
          required: false
          description: >-
            Return the object response, which reports every refused span,
            instead of the bare array of created spans.
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - traces
              properties:
                traces:
                  type: array
                  minItems: 1
                  description: The spans to create.
                  items:
                    type: object
                    required:
                      - inferenceResultId
                      - name
                    properties:
                      id:
                        type: string
                        description: Optional custom span ID
                        example: id_123
                      inferenceResultId:
                        type: string
                        description: ID of the trace this span belongs to
                        example: ir_123
                      name:
                        type: string
                        description: Name of the span
                      description:
                        example: Example Name
                        type: string
                        nullable: true
                        description: Optional description of the span
                      type:
                        type: string
                        enum:
                          - SPAN
                          - GENERATION
                          - EVENT
                          - AGENT
                          - TOOL
                          - CHAIN
                          - RETRIEVER
                          - EVALUATOR
                          - EMBEDDING
                          - GUARDRAIL
                        nullable: true
                        description: >-
                          Type of span. A value outside this list is not
                          dropped, it is normalized to one of these types, and
                          the original label is kept in the span's metadata
                          under `galtea.span.original_type`.
                      inputData:
                        type: object
                        nullable: true
                        description: Input data for the span
                      outputData:
                        oneOf:
                          - type: object
                          - type: string
                        nullable: true
                        description: >-
                          Output data from the span (an object, or a plain
                          string)
                      error:
                        type: string
                        nullable: true
                        description: Error message if the span failed
                        example: Error message
                      latencyMs:
                        type: number
                        nullable: true
                        description: Duration in milliseconds
                      metadata:
                        type: object
                        nullable: true
                        description: Additional span attributes
                      parentTraceId:
                        type: string
                        nullable: true
                        description: >-
                          Parent span ID for hierarchical spans (references id
                          of another span in batch)
                      startTime:
                        type: string
                        format: date-time
                        nullable: true
                        description: Start time of the span
                      endTime:
                        type: string
                        format: date-time
                        nullable: true
                        description: End time of the span
      responses:
        '200':
          description: >-
            At least one span was created. The default body is the bare array of
            created spans; with `includeRejected=true` it is the object form.
            Each `parentTraceId` is the value the span was stored with: a span
            whose parent arrives in a concurrent request can be attached after
            this body is built, so read the span back to see the settled parent.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    description: Default body. The created spans.
                    items:
                      $ref: '#/components/schemas/Trace'
                  - $ref: '#/components/schemas/CreateSpansBatchResult'
        '400':
          description: >-
            The request body carried no spans, or every span in it was dropped.
            A span naming an unknown trace is dropped like any other, so a
            single-span batch answers 400 here where `POST /traces` answers 404.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            One span belongs to a trace you cannot write to. This is the one
            refusal that costs the whole batch, so no span is created, unlike
            every other refusal, which is reported per span.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    Trace:
      type: object
      description: >-
        A span: one step inside a trace, such as a tool call, a retrieval or an
        LLM call. The schema name and the `/traces` path still carry the old
        name of this entity, "trace". The parent trace is `inferenceResultId`;
        the `parentTraceId` field is the parent span, not the trace. Span ids
        start with `trace_`, so a `trace_` id belongs here and never to a trace.
      properties:
        id:
          type: string
          example: trace_123
        inferenceResultId:
          type: string
          example: ir_123
        name:
          type: string
          example: fetch_user_data
        type:
          type: string
          enum:
            - SPAN
            - GENERATION
            - EVENT
            - AGENT
            - TOOL
            - CHAIN
            - RETRIEVER
            - EVALUATOR
            - EMBEDDING
            - GUARDRAIL
          nullable: true
          example: TOOL
        description:
          type: string
          nullable: true
          example: Fetches user data from the database by ID
          description: Human-readable description of the operation. Maximum 1MB.
        inputData:
          type: object
          nullable: true
          example:
            user_id: '123'
          description: Input parameters passed to the operation
        outputData:
          oneOf:
            - type: object
            - type: string
          nullable: true
          example:
            name: John Doe
            email: john@example.com
          description: >-
            Result returned by the operation. Usually an object; a plain string
            for retrieval-context spans
        error:
          type: string
          nullable: true
          example: Connection timeout
          description: Error message if failed
        latencyMs:
          type: number
          nullable: true
          example: 45.5
          description: Execution time in milliseconds
        metadata:
          type: object
          nullable: true
          example:
            model: gpt-4
            temperature: 0.7
          description: Additional custom metadata
        parentTraceId:
          type: string
          nullable: true
          example: trace_parent_123
          description: ID of parent span for hierarchical relationships
        startTime:
          type: string
          format: date-time
          nullable: true
        endTime:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
        modelId:
          type: string
          nullable: true
          readOnly: true
          example: model_123
          description: >-
            The model that answered this LLM call, matched by name when the span
            was ingested. Null when no live model of the organization, or global
            model, had the name the span reported. Deleting the model keeps it,
            so it can name a deleted model.
        modelName:
          type: string
          nullable: true
          readOnly: true
          example: gpt-4o-mini
          description: The model name the span reported, whether or not it matched a model.
        inputTokens:
          type: integer
          nullable: true
          readOnly: true
          example: 100
          description: >-
            Input tokens the LLM call reported. Null without
            `evaluation.readInference` on the product.
        outputTokens:
          type: integer
          nullable: true
          readOnly: true
          example: 50
          description: >-
            Output tokens the LLM call reported. Null without
            `evaluation.readInference` on the product.
        cacheReadInputTokens:
          type: integer
          nullable: true
          readOnly: true
          example: 20
          description: >-
            Input tokens the LLM call read from the cache. Null without
            `evaluation.readInference` on the product.
        tokens:
          type: integer
          nullable: true
          readOnly: true
          example: 170
          description: >-
            Sum of the input, output and cache-read tokens. Null without
            `evaluation.readInference` on the product.
        costPerInputToken:
          type: number
          nullable: true
          readOnly: true
          example: 0.00001
          description: >-
            Price of one input token, frozen at ingest from the model of this
            call, or from the version model when the span names no model. Null
            when the named model links to nothing or has no price. Null without
            `evaluation.readInference` on the product.
        costPerOutputToken:
          type: number
          nullable: true
          readOnly: true
          example: 0.00003
          description: >-
            Price of one output token, frozen at ingest like costPerInputToken.
            Null without `evaluation.readInference` on the product.
        costPerCacheReadInputToken:
          type: number
          nullable: true
          readOnly: true
          example: 0.000005
          description: >-
            Price of one cache-read token, frozen at ingest like
            costPerInputToken. Null without `evaluation.readInference` on the
            product.
        cost:
          type: number
          nullable: true
          readOnly: true
          example: 0.0026
          description: >-
            Cost of this call at the frozen rates. Null when no rates were
            found. A turn's cost sums its spans' costs. Null without
            `evaluation.readInference` on the product.
    CreateSpansBatchResult:
      type: object
      description: >-
        Batch create result returned when `includeRejected=true`.
        `partialSuccess` is present only when at least one span was refused.
      required:
        - spans
      properties:
        spans:
          type: array
          description: The spans that were created.
          items:
            $ref: '#/components/schemas/Trace'
        partialSuccess:
          type: object
          required:
            - rejectedSpans
            - errors
          properties:
            rejectedSpans:
              type: integer
              example: 1
              description: How many spans were refused.
            errors:
              type: array
              items:
                $ref: '#/components/schemas/RejectedSpan'
    Error:
      type: object
      properties:
        error:
          type: string
          example: Error type
        message:
          type: string
          example: Error message description
    RejectedSpan:
      type: object
      description: One span a batch create refused. Its siblings were still created.
      required:
        - index
        - name
        - reason
      properties:
        index:
          type: integer
          example: 2
          description: >-
            Position of the span in the request array, so the caller can find
            it.
        name:
          type: string
          nullable: true
          example: fetch_user_data
          description: Name the span was sent with. Null when it carried no usable name.
        reason:
          type: string
          example: '"latencyMs" must be a non-negative number'
          description: Why the span was refused.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authorization. Pass your API key in the Authorization header as
        a Bearer token. Both new (`gsk_*`) and legacy (`gsk-`) API keys are
        accepted, e.g. `Authorization: Bearer gsk_...` or `Authorization: Bearer
        gsk-...`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.