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

# Receive Traces

> Submit trace data to the OpenTelemetry Collector using OTLP/HTTP protocol.

The request must include a valid OAuth2 bearer token in the Authorization header,
obtained from the Unomiq OAuth API.

The collector processes traces through the following pipeline:
1. Extract API key ID from JWT sub claim
2. Extract app ID from JWT custom claim
3. Filter out spans without app ID (silently dropped, no error returned)

Note: The endpoint always returns 200 OK if the request is valid, even if spans are
filtered out due to missing app ID. Check partialSuccess in the response for details.




## OpenAPI

````yaml POST /v1/traces
openapi: 3.0.3
info:
  title: Unomiq OpenTelemetry Collector API
  description: >
    OTLP/HTTP endpoint for receiving OpenTelemetry traces.


    This API accepts trace data in the OpenTelemetry Protocol (OTLP) format over
    HTTP.

    All requests must be authenticated using OAuth2/OIDC bearer tokens.


    The collector enriches traces with API Key ID and app IDs from JWT claims
    before exporting them to the processor pipeline.
  version: 1.0.0
servers:
  - url: https://gateway-api.unomiq.com
security:
  - bearerAuth: []
tags:
  - name: Traces
    description: OpenTelemetry trace ingestion endpoints
paths:
  /v1/traces:
    post:
      tags:
        - Traces
      summary: Receive traces
      description: >
        Submit trace data to the OpenTelemetry Collector using OTLP/HTTP
        protocol.


        The request must include a valid OAuth2 bearer token in the
        Authorization header,

        obtained from the Unomiq OAuth API.


        The collector processes traces through the following pipeline:

        1. Extract API key ID from JWT sub claim

        2. Extract app ID from JWT custom claim

        3. Filter out spans without app ID (silently dropped, no error returned)


        Note: The endpoint always returns 200 OK if the request is valid, even
        if spans are

        filtered out due to missing app ID. Check partialSuccess in the response
        for details.
      operationId: exportTraces
      parameters:
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            enum:
              - application/json
          description: Content type of the request body
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportTraceServiceRequest'
            example:
              resourceSpans:
                - resource:
                    attributes:
                      - key: service.name
                        value:
                          stringValue: my-service
                      - key: service.version
                        value:
                          stringValue: 1.0.0
                  scopeSpans:
                    - scope:
                        name: my-instrumentation-library
                        version: 1.0.0
                      spans:
                        - traceId: 5B8EFFF798038103D269B633813FC60C
                          spanId: EEE19B7EC3C1B174
                          parentSpanId: EEE19B7EC3C1B173
                          name: GET /api/users
                          kind: 2
                          startTimeUnixNano: '1544712660000000000'
                          endTimeUnixNano: '1544712661000000000'
                          attributes:
                            - key: http.method
                              value:
                                stringValue: GET
                            - key: http.url
                              value:
                                stringValue: https://api.example.com/users
                            - key: http.status_code
                              value:
                                intValue: 200
                          status:
                            code: 0
      responses:
        '200':
          description: Traces accepted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportTraceServiceResponse'
              example:
                partialSuccess:
                  rejectedSpans: 0
                  errorMessage: ''
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              example:
                code: 3
                message: Invalid trace data format
                details: []
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              examples:
                missing_token:
                  summary: Missing authorization header
                  value:
                    code: 16
                    message: Missing authorization header
                    details: []
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    code: 16
                    message: Invalid or expired JWT token
                    details: []
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              example:
                code: 13
                message: Internal server error
                details: []
        '503':
          description: Service unavailable (memory limit exceeded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              example:
                code: 14
                message: Memory limit exceeded - refusing spans
                details: []
      security:
        - bearerAuth: []
components:
  schemas:
    ExportTraceServiceRequest:
      type: object
      description: >
        OTLP ExportTraceServiceRequest. The request body follows the standard
        OTLP/HTTP JSON format.

        See https://opentelemetry.io/docs/specs/otlp/#otlphttp-request for the
        full schema.
      properties:
        resourceSpans:
          type: array
          description: Array of ResourceSpans as defined by the OTLP specification
          items:
            type: object
    ExportTraceServiceResponse:
      type: object
      description: >
        OTLP ExportTraceServiceResponse.

        See https://opentelemetry.io/docs/specs/otlp/#otlphttp-response for the
        full schema.
      properties:
        partialSuccess:
          type: object
          properties:
            rejectedSpans:
              type: integer
              format: int64
              description: Number of spans that were rejected
            errorMessage:
              type: string
              description: Error message describing why spans were rejected
    Status:
      type: object
      description: OTLP status response
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: Status code
          example: 3
        message:
          type: string
          description: Error message
          example: Invalid request
        details:
          type: array
          description: Additional error details
          items:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        OAuth2/OIDC JWT token with required app ID and API key ID claims.

````