> ## 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.

# Query Traces & Spans

> Query traces and spans using a filter expression.

Requires a valid JWT token with the `read:traces` permission.
 
The following fields are supported in nested AND/OR conditions:

### Identifiers
| Field | Description |
|-------|-------------|
| `trace_id` | Trace identifier |
| `span_id` | Span identifier |

### Span fields
| Field | Description |
|-------|-------------|
| `span_attributes.*` | Any span attribute (e.g., `span_attributes.http.method`) |
| `resource_attributes.*` | Any resource attribute |
| `span_kind` | Span kind |
| `span_name` | Span name |
| `service_name` | Service name (equivalent to `resource_attributes.service.name`) |
| `unit` | Unit (equivalent to `span_attributes.unomiq.unit`) |
| `parent_unit` | Parent unit (equivalent to `span_attributes.unomiq.parent_unit`) |
| `duration_ms` | Span duration in milliseconds |

### Billing & Usage
| Field | Description |
|-------|-------------|
| `billing.resource_type` | Resource type (e.g., `db_job`, `api_request`, `llm_generate_content`) |
| `billing.resource_name` | Billing resource name |
| `billing.service_id` | Billing service ID |
| `billing.service_name` | Billing service name |
| `billing.sku_id` | Billing SKU ID |
| `billing.sku_name` | Billing SKU name |
| `billing.region` | Billing region |
| `cost` | Cost |
| `usage.amount` | Usage amount |
| `usage.unit` | Usage unit |

Returns a paginated list of matching traces with total count.



## OpenAPI

````yaml POST /engine/query
openapi: 3.1.0
info:
  title: Unomiq Engine API
  description: >-

    API for managing OpenTelemetry data, queries and boards.


    ## Authentication


    All API endpoints require authentication via JWT token in the Authorization
    header:


    ```

    Authorization: Bearer <your_jwt_token>

    ```


    Obtain your JWT token from the authentication service and include it in all
    requests.
        
  version: 1.0.0
servers:
  - url: https://engine-api.unomiq.com
    description: Production
security: []
paths:
  /engine/query:
    post:
      tags:
        - engine
      summary: Query Traces Spans
      description: >-
        Query traces and spans using a filter expression.


        Requires a valid JWT token with the `read:traces` permission.
         
        The following fields are supported in nested AND/OR conditions:


        ### Identifiers

        | Field | Description |

        |-------|-------------|

        | `trace_id` | Trace identifier |

        | `span_id` | Span identifier |


        ### Span fields

        | Field | Description |

        |-------|-------------|

        | `span_attributes.*` | Any span attribute (e.g.,
        `span_attributes.http.method`) |

        | `resource_attributes.*` | Any resource attribute |

        | `span_kind` | Span kind |

        | `span_name` | Span name |

        | `service_name` | Service name (equivalent to
        `resource_attributes.service.name`) |

        | `unit` | Unit (equivalent to `span_attributes.unomiq.unit`) |

        | `parent_unit` | Parent unit (equivalent to
        `span_attributes.unomiq.parent_unit`) |

        | `duration_ms` | Span duration in milliseconds |


        ### Billing & Usage

        | Field | Description |

        |-------|-------------|

        | `billing.resource_type` | Resource type (e.g., `db_job`,
        `api_request`, `llm_generate_content`) |

        | `billing.resource_name` | Billing resource name |

        | `billing.service_id` | Billing service ID |

        | `billing.service_name` | Billing service name |

        | `billing.sku_id` | Billing SKU ID |

        | `billing.sku_name` | Billing SKU name |

        | `billing.region` | Billing region |

        | `cost` | Cost |

        | `usage.amount` | Usage amount |

        | `usage.unit` | Usage unit |


        Returns a paginated list of matching traces with total count.
      operationId: query_traces_spans_engine_query_post
      parameters:
        - name: start_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: Start datetime (inclusive)
            examples:
              - '2025-01-15T00:00:00Z'
            title: Start Time
          description: Start datetime (inclusive)
        - name: end_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: End datetime (exclusive)
            examples:
              - '2025-01-16T00:00:00Z'
            title: End Time
          description: End datetime (exclusive)
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: Page number for pagination (1-indexed)
            default: 1
            title: Page
          description: Page number for pagination (1-indexed)
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Number of items per page
            default: 20
            title: Limit
          description: Number of items per page
        - name: X-Unomiq-App-Id
          in: header
          required: true
          schema:
            type: string
            title: X-Unomiq-App-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryFilter'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    QueryFilter:
      properties:
        filter:
          anyOf:
            - $ref: '#/components/schemas/Condition'
            - $ref: '#/components/schemas/AndGroup'
            - $ref: '#/components/schemas/OrGroup'
            - type: 'null'
          title: Filter
          description: Filter expression with nested AND/OR conditions
          examples:
            - and:
                - field: span_attributes.http.status_code
                  op: gte
                  value: '200'
                - field: span_attributes.http.status_code
                  op: lte
                  value: '299'
                - or:
                    - field: span_kind
                      op: eq
                      value: SERVER
                    - field: span_kind
                      op: eq
                      value: CLIENT
      type: object
      title: QueryFilter
      description: Request model for query filter.
    QueryResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Trace'
          type: array
          title: Data
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
      type: object
      required:
        - data
        - total
        - page
        - limit
      title: QueryResponse
      description: Response model for query operation.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Condition:
      properties:
        field:
          type: string
          pattern: >-
            ^(span_attributes\.[a-zA-Z0-9._]+|resource_attributes\.[a-zA-Z0-9._]+|trace_id|span_id|span_kind|span_name|service_name|unit|parent_unit|duration_ms|cost|billing\.resource_type|billing\.resource_name|billing\.service_id|billing\.service_name|billing\.sku_id|billing\.sku_name|billing\.region|usage\.amount|usage\.unit)$
          title: Field
          description: >-
            Field to filter on. Use dot notation for nested fields (e.g.,
            'billing.service_name', 'billing.region', 'usage.amount',
            'span_attributes.http.method', 'resource_attributes.service.name')
          examples:
            - span_attributes.http.method
            - resource_attributes.service.name
            - span_kind
            - service_name
            - billing.region
        op:
          $ref: '#/components/schemas/QueryOperator'
          description: Comparison operator
          examples:
            - eq
            - contains
            - gte
        value:
          type: string
          title: Value
          description: Value to compare against
          examples:
            - GET
            - my-service
            - SERVER
      type: object
      required:
        - field
        - op
        - value
      title: Condition
      description: A single filter condition.
    AndGroup:
      properties:
        and:
          items:
            anyOf:
              - $ref: '#/components/schemas/Condition'
              - $ref: '#/components/schemas/OrGroup'
              - $ref: '#/components/schemas/AndGroup'
          type: array
          title: And
          description: List of conditions to combine with AND
      type: object
      required:
        - and
      title: AndGroup
      description: A group of conditions combined with AND logic.
    OrGroup:
      properties:
        or:
          items:
            anyOf:
              - $ref: '#/components/schemas/Condition'
              - $ref: '#/components/schemas/AndGroup'
              - $ref: '#/components/schemas/OrGroup'
          type: array
          title: Or
          description: List of conditions to combine with OR
      type: object
      required:
        - or
      title: OrGroup
      description: A group of conditions combined with OR logic.
    Trace:
      properties:
        trace_id:
          type: string
          title: Trace Id
        span_id:
          type: string
          title: Span Id
        span_start_time_unix_nano:
          type: integer
          title: Span Start Time Unix Nano
        span_end_time_unix_nano:
          type: integer
          title: Span End Time Unix Nano
        duration_ms:
          type: number
          title: Duration Ms
        parent_span_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Span Id
        span_name:
          type: string
          title: Span Name
        span_kind:
          type: string
          title: Span Kind
        service_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Service Name
        unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Unit
        parent_unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Unit
        resource_attributes:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Resource Attributes
        span_attributes:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Span Attributes
        cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Cost
        billing:
          $ref: '#/components/schemas/BillingInfo'
        usage:
          $ref: '#/components/schemas/UsageInfo'
      type: object
      required:
        - trace_id
        - span_id
        - span_start_time_unix_nano
        - span_end_time_unix_nano
        - duration_ms
        - span_name
        - span_kind
      title: Trace
      description: Trace domain model.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    QueryOperator:
      type: string
      enum:
        - eq
        - neq
        - contains
        - starts_with
        - ends_with
        - gt
        - lt
        - gte
        - lte
      title: QueryOperator
      description: Supported query operators.
    BillingInfo:
      properties:
        resource_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Resource Type
        resource_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Resource Name
        service_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Service Id
        service_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Service Name
        sku_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Sku Id
        sku_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Sku Name
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
      type: object
      title: BillingInfo
      description: Billing information associated with a span.
    UsageInfo:
      properties:
        amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Amount
        unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Unit
      type: object
      title: UsageInfo
      description: Usage information associated with a span.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````