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

# Export OTLP traces

> OTLP-compatible trace export endpoint. Accepts an `ExportTraceServiceRequest` payload as JSON (`application/json`) or protobuf (`application/x-protobuf`). Spans are converted to Zespan events and queued asynchronously.

Authenticated with `x-api-key`. Rate limited to 300 requests/minute per API key, capped at 1 MB and 100 spans per request, and counted against the organization's monthly event quota. Spans beyond the 100-span cap are reported in `partialSuccess.rejectedSpans`.




## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/traces
openapi: 3.1.0
info:
  title: Zespan Public API
  version: 1.0.0
  description: >
    The Zespan Public API covers the endpoints that customers call directly or
    through the Zespan SDKs: trace ingestion (native and OpenTelemetry), prompt
    management, datasets and dataset runs, and the runtime guardrails check.

    All endpoints authenticate with a project API key sent in the `x-api-key`
    header. Create and manage API keys from the project settings in the Zespan
    dashboard.
servers:
  - url: https://api.zespan.com
    description: Zespan production API
security:
  - ApiKeyAuth: []
tags:
  - name: Ingestion
    description: Send traces and events to Zespan.
  - name: OpenTelemetry
    description: OTLP-compatible ingestion endpoints.
  - name: Prompts
    description: Manage versioned prompts and their labels, tags, and folders.
  - name: Datasets
    description: Read datasets and manage dataset runs used for experiments and scoring.
  - name: Guardrails
    description: Runtime guardrail evaluation.
paths:
  /v1/traces:
    post:
      tags:
        - OpenTelemetry
      summary: Export OTLP traces
      description: >
        OTLP-compatible trace export endpoint. Accepts an
        `ExportTraceServiceRequest` payload as JSON (`application/json`) or
        protobuf (`application/x-protobuf`). Spans are converted to Zespan
        events and queued asynchronously.


        Authenticated with `x-api-key`. Rate limited to 300 requests/minute per
        API key, capped at 1 MB and 100 spans per request, and counted against
        the organization's monthly event quota. Spans beyond the 100-span cap
        are reported in `partialSuccess.rejectedSpans`.
      operationId: otelTraces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtelExportTraceServiceRequest'
          application/x-protobuf:
            schema:
              type: string
              format: binary
              description: Protobuf-encoded ExportTraceServiceRequest.
      responses:
        '202':
          description: Spans accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtelTracePartialSuccess'
        '400':
          description: Invalid trace data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request body exceeded 1 MB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded. Includes a `Retry-After` header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >
            Quota state could not be determined for a Free-plan organization.
            The request was not accepted; retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OtelExportTraceServiceRequest:
      type: object
      description: OTLP ExportTraceServiceRequest (JSON encoding).
      properties:
        resourceSpans:
          type: array
          items:
            type: object
            properties:
              resource:
                type: object
                properties:
                  attributes:
                    type: array
                    items:
                      $ref: '#/components/schemas/OtelKeyValue'
              scopeSpans:
                type: array
                items:
                  type: object
                  properties:
                    scope:
                      type: object
                      properties:
                        name:
                          type: string
                        version:
                          type: string
                    spans:
                      type: array
                      items:
                        $ref: '#/components/schemas/OtelSpan'
    OtelTracePartialSuccess:
      type: object
      properties:
        partialSuccess:
          type: object
          properties:
            rejectedSpans:
              type: integer
              example: 0
            errorMessage:
              type: string
              example: ''
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: Unauthorized
        code:
          type: string
          description: Machine-readable error code, when present.
          example: rate_limit_exceeded
      required:
        - error
    OtelKeyValue:
      type: object
      properties:
        key:
          type: string
          example: gen_ai.system
        value:
          type: object
          description: 'OTLP AnyValue (e.g. `{ "stringValue": "openai" }`).'
          additionalProperties: true
    OtelSpan:
      type: object
      required:
        - traceId
        - spanId
        - name
        - startTimeUnixNano
      properties:
        traceId:
          type: string
        spanId:
          type: string
        parentSpanId:
          type: string
        name:
          type: string
          example: chat.completions
        kind:
          type: integer
        startTimeUnixNano:
          type: string
          example: '1751716800000000000'
        endTimeUnixNano:
          type: string
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/OtelKeyValue'
        status:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Project API key. Manage keys in the Zespan dashboard under project
        settings.

````