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

# Get Traces

> Get traces within a time range.

Requires a valid JWT token with the `read:traces` permission.

Retrieves a paginated list of aggregated information for traces by
selecting root spans (`parent_span_id` is null or `span_kind` = `SPAN_KIND_SERVER`)
within the specified time range, aggregating trace duration, span count, and total cost.

By default, filters apply only to root spans. Set `search_child_spans=true`
to apply filters across all spans, returning traces where at least one
span meets the conditions.

Traces can be filtered with an expression that supports nested
AND/OR conditions on the following fields:

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



## OpenAPI

````yaml POST /traces
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:
  /traces:
    post:
      tags:
        - traces
      summary: Get Traces
      description: >-
        Get traces within a time range.


        Requires a valid JWT token with the `read:traces` permission.


        Retrieves a paginated list of aggregated information for traces by

        selecting root spans (`parent_span_id` is null or `span_kind` =
        `SPAN_KIND_SERVER`)

        within the specified time range, aggregating trace duration, span count,
        and total cost.


        By default, filters apply only to root spans. Set
        `search_child_spans=true`

        to apply filters across all spans, returning traces where at least one

        span meets the conditions.


        Traces can be filtered with an expression that supports nested

        AND/OR conditions on the following fields:


        ### 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 |
      operationId: get_traces_traces_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: search_child_spans
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              When true, apply filters to all spans including child spans. When
              false, apply filters only to root spans.
            default: false
            title: Search Child Spans
          description: >-
            When true, apply filters to all spans including child spans. When
            false, apply filters only to root spans.
        - 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/RootTraceListResponse'
        '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.
    RootTraceListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/RootTrace'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
      type: object
      required:
        - data
        - pagination
      title: RootTraceListResponse
      description: Paginated response for root traces.
    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.
    RootTrace:
      properties:
        trace_id:
          type: string
          title: Trace Id
        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
        span_name:
          type: string
          title: Span Name
        duration_ms:
          type: number
          title: Duration Ms
        spans_count:
          type: integer
          title: Spans Count
        total_cost:
          type: number
          title: Total Cost
        min_start_time_unix_nano:
          type: integer
          title: Min Start Time Unix Nano
      type: object
      required:
        - trace_id
        - span_name
        - duration_ms
        - spans_count
        - total_cost
        - min_start_time_unix_nano
      title: RootTrace
      description: Summary of a root trace with aggregated metrics.
    PaginationInfo:
      properties:
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
        total:
          type: integer
          title: Total
      type: object
      required:
        - page
        - limit
        - total
      title: PaginationInfo
      description: Pagination metadata.
    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.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````