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

# Ingest OTLP traces

> Ingest OpenTelemetry Protocol (OTLP) traces in JSON format. Converts OTLP spans to Avido events and processes them through the standard ingestion pipeline. Supports OpenInference semantic conventions for LLM, tool, retriever, and other span types.



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/avido/openapi.documented.yml post /v0/otel/traces
openapi: 3.1.1
info:
  title: Avido API
  description: >-
    Avido's API for LLM usage events, tool calls, trace management, webhook
    validation, and more. See each endpoint's request/response schema for
    details.
  version: 0.1.0
  contact:
    name: Avido Support
    email: support@avidoai.com
    url: https://avidoai.com/support
servers:
  - url: https://api.avidoai.com
    description: Production API
security:
  - ApiKey: []
    ApplicationId: []
paths:
  /v0/otel/traces:
    post:
      tags:
        - Ingestion
      summary: Ingest OTLP traces
      description: >-
        Ingest OpenTelemetry Protocol (OTLP) traces in JSON format. Converts
        OTLP spans to Avido events and processes them through the standard
        ingestion pipeline. Supports OpenInference semantic conventions for LLM,
        tool, retriever, and other span types.
      operationId: postOtelTraces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtlpTracesRequest'
            examples:
              llmSpan:
                summary: LLM span example
                value:
                  resourceSpans:
                    - scopeSpans:
                        - spans:
                            - traceId: 4bf92f3577b34da6a3ce929d0e0e4736
                              spanId: 00f067aa0ba902b7
                              name: llm.generate
                              startTimeUnixNano: '1737052800000000000'
                              endTimeUnixNano: '1737052800500000000'
                              attributes:
                                - key: openinference.span.kind
                                  value:
                                    stringValue: LLM
                                - key: llm.model_name
                                  value:
                                    stringValue: gpt-4o-2024-08-06
                                - key: input.value
                                  value:
                                    stringValue: Tell me a joke.
                                - key: output.value
                                  value:
                                    stringValue: Why did the chicken cross the road?
                                - key: llm.token_count.prompt
                                  value:
                                    intValue: 12
                                - key: llm.token_count.completion
                                  value:
                                    intValue: 18
      responses:
        '201':
          description: Successfully ingested OTLP traces.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResponse'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    OtlpTracesRequest:
      type: object
      properties:
        resourceSpans:
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/OtlpResourceSpan'
      title: OTLP Traces Request
      description: >-
        OpenTelemetry Protocol traces request payload in JSON format. Contains
        resourceSpans array with nested spans, attributes, events, links, and
        metadata following the OTLP specification.
    IngestResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                description: Trace ID if the event was a trace. Not returned for steps.
                example: 123e4567-e89b-12d3-a456-426614174000
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              success:
                type: boolean
                description: Whether the event(s) were successfully ingested.
                example: true
              error:
                description: Error message if ingestion failed.
                example: Failed to write to database
                type: string
            required:
              - success
            additionalProperties: false
          description: Array of results for each ingested event.
      required:
        - data
      additionalProperties: false
      title: Ingest Success Response
      description: Response schema for successful event ingestion.
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message explaining the error.
          example: Resource not found
      required:
        - message
      additionalProperties: false
      title: ErrorResponse
      description: Standard error format for failed API operations.
    ValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message indicating what went wrong.
          example: Invalid request data
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              path:
                type: array
                items:
                  type: string
            required:
              - code
              - message
              - path
            additionalProperties: false
          description: Array of detailed validation error objects.
          example:
            - code: invalid_string
              message: Invalid UUID
              path:
                - id
      required:
        - message
        - issues
      additionalProperties: false
      title: ValidationErrorResponse
      description: Details about validation errors in incoming requests.
    OtlpResourceSpan:
      type: object
      properties:
        resource:
          type: object
          properties:
            attributes:
              maxItems: 200
              type: array
              items:
                $ref: '#/components/schemas/OtlpAttribute'
            droppedAttributesCount:
              description: Number of attributes that were dropped due to limits
              example: 0
              type: integer
              minimum: 0
              maximum: 9007199254740991
        scopeSpans:
          maxItems: 50
          type: array
          items:
            $ref: '#/components/schemas/OtlpScopeSpan'
        schemaUrl:
          description: Schema URL that identifies the schema of the resource
          example: https://opentelemetry.io/schemas/1.21.0
          type: string
          maxLength: 2048
          format: uri
      title: OTLP Resource Span
      description: >-
        OpenTelemetry Protocol resource span containing resource attributes and
        scope spans.
    OtlpAttribute:
      title: OTLP Attribute
      description: >-
        OpenTelemetry Protocol attribute with key-value structure. Values can be
        primitives, arrays, or nested key-value lists. Maximum nesting depth: 5
        levels.
      type: object
      properties:
        key:
          type: string
          maxLength: 256
        value:
          type: object
          properties:
            stringValue:
              type: string
              maxLength: 1048576
            intValue:
              anyOf:
                - type: string
                - type: number
            doubleValue:
              type: number
            boolValue:
              type: boolean
            arrayValue:
              type: object
              properties:
                values:
                  maxItems: 200
                  type: array
                  items:
                    $ref: '#/components/schemas/OtlpAttributeValue'
              required:
                - values
            kvlistValue:
              type: object
              properties:
                values:
                  maxItems: 200
                  type: array
                  items:
                    $ref: '#/components/schemas/OtlpAttribute'
              required:
                - values
      required:
        - key
        - value
    OtlpScopeSpan:
      type: object
      properties:
        scope:
          type: object
          properties:
            name:
              type: string
              maxLength: 256
            version:
              type: string
              maxLength: 64
            attributes:
              maxItems: 200
              type: array
              items:
                $ref: '#/components/schemas/OtlpAttribute'
            droppedAttributesCount:
              description: Number of attributes that were dropped due to limits
              example: 0
              type: integer
              minimum: 0
              maximum: 9007199254740991
        spans:
          maxItems: 512
          type: array
          items:
            $ref: '#/components/schemas/OtlpSpan'
        schemaUrl:
          description: Schema URL that identifies the schema of the instrumentation scope
          example: https://opentelemetry.io/schemas/1.21.0
          type: string
          maxLength: 2048
          format: uri
      title: OTLP Scope Span
      description: >-
        OpenTelemetry Protocol scope span containing instrumentation scope
        metadata and associated spans.
    OtlpAttributeValue:
      title: OTLP Attribute Value
      description: >-
        OpenTelemetry Protocol attribute value that can be a string, integer,
        double, boolean, array, or key-value list. Supports nested structures.
      type: object
      properties:
        stringValue:
          type: string
          maxLength: 1048576
        intValue:
          anyOf:
            - type: string
            - type: number
        doubleValue:
          type: number
        boolValue:
          type: boolean
        arrayValue:
          type: object
          properties:
            values:
              maxItems: 200
              type: array
              items:
                $ref: '#/components/schemas/OtlpAttributeValue'
          required:
            - values
        kvlistValue:
          type: object
          properties:
            values:
              maxItems: 200
              type: array
              items:
                $ref: '#/components/schemas/OtlpAttribute'
          required:
            - values
    OtlpSpan:
      type: object
      properties:
        traceId:
          type: string
          minLength: 32
          maxLength: 32
          pattern: ^[0-9a-f]{32}$
        spanId:
          type: string
          minLength: 16
          maxLength: 16
          pattern: ^[0-9a-f]{16}$
        traceState:
          description: >-
            W3C trace-context trace-state conveying information about request
            position in multiple distributed tracing graphs
          example: vendor1=value1,vendor2=value2
          type: string
          maxLength: 512
        parentSpanId:
          type: string
          minLength: 16
          maxLength: 16
          pattern: ^[0-9a-f]{16}$
        name:
          type: string
          maxLength: 2048
        kind:
          type: integer
          minimum: 0
          maximum: 5
        startTimeUnixNano:
          anyOf:
            - type: string
            - type: number
        endTimeUnixNano:
          anyOf:
            - type: string
            - type: number
        attributes:
          maxItems: 200
          type: array
          items:
            $ref: '#/components/schemas/OtlpAttribute'
        droppedAttributesCount:
          description: Number of attributes that were dropped due to limits
          example: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        events:
          description: >-
            List of timestamped events that occurred during the span's lifetime
            (e.g., browser timing marks, lifecycle events)
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/OtlpEvent'
        droppedEventsCount:
          description: Number of events that were dropped due to limits
          example: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        links:
          description: >-
            Links to other spans that are causally related (within same trace or
            across traces)
          maxItems: 50
          type: array
          items:
            $ref: '#/components/schemas/OtlpLink'
        droppedLinksCount:
          description: Number of links that were dropped due to limits
          example: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        status:
          type: object
          properties:
            code:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            message:
              type: string
              maxLength: 1048576
        flags:
          description: >-
            Flags as a bit field. Bits 0-7 are W3C trace flags, bits 8-9
            indicate parent remoteness state
          example: 1
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - traceId
        - spanId
        - name
        - startTimeUnixNano
        - endTimeUnixNano
      title: OTLP Span
      description: >-
        OpenTelemetry Protocol span representing a unit of work with timing,
        attributes, events, links, and status. Trace IDs must be 32 hex
        characters, span IDs must be 16 hex characters.
    OtlpEvent:
      type: object
      properties:
        timeUnixNano:
          anyOf:
            - type: string
            - type: number
          description: >-
            Time when the event occurred, UNIX epoch time in nanoseconds since
            1970-01-01T00:00:00Z
          example: '1737052800250000000'
        name:
          type: string
          maxLength: 2048
          description: Name of the event
          example: fetchStart
        attributes:
          maxItems: 200
          type: array
          items:
            $ref: '#/components/schemas/OtlpAttribute'
        droppedAttributesCount:
          description: Number of attributes that were dropped due to limits
          example: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - timeUnixNano
        - name
      title: OTLP Span Event
      description: >-
        A timestamped event that occurred during the span's lifetime. Common
        examples include browser timing marks (fetchStart, responseStart),
        lifecycle events, or custom application events.
    OtlpLink:
      type: object
      properties:
        traceId:
          type: string
          minLength: 32
          maxLength: 32
          pattern: ^[0-9a-f]{32}$
          description: Trace ID of the linked span (32 hex characters)
          example: 4bf92f3577b34da6a3ce929d0e0e4736
        spanId:
          type: string
          minLength: 16
          maxLength: 16
          pattern: ^[0-9a-f]{16}$
          description: Span ID of the linked span (16 hex characters)
          example: 00f067aa0ba902b7
        traceState:
          description: W3C trace-context trace-state associated with the linked span
          example: vendor1=value1,vendor2=value2
          type: string
          maxLength: 512
        attributes:
          maxItems: 200
          type: array
          items:
            $ref: '#/components/schemas/OtlpAttribute'
        droppedAttributesCount:
          description: Number of attributes that were dropped due to limits
          example: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        flags:
          description: Flags for the link (8 least significant bits are W3C trace flags)
          example: 1
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - traceId
        - spanId
      title: OTLP Span Link
      description: >-
        A link from this span to another span, establishing a causal
        relationship. Links can point to spans in the same trace or across
        different traces.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your unique Avido API key
    ApplicationId:
      type: apiKey
      in: header
      name: x-application-id
      description: Your unique Avido Application ID

````