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

# Query trace facets

> Count the traces that match a search, grouped into facets.



## OpenAPI

````yaml https://api.uselemma.ai/openapi.json post /traces/facets
openapi: 3.1.0
info:
  title: Lemma Platform API
  description: Lemma Platform HTTP API for AI observability and workspace operations.
  version: 0.1.0
servers:
  - url: https://api.uselemma.ai
    description: Lemma production API
security:
  - bearerAuth: []
paths:
  /traces/facets:
    post:
      tags:
        - Traces
      summary: Query trace facets
      description: Count the traces that match a search, grouped into facets.
      operationId: query_trace_facets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  minLength: 1
                match:
                  oneOf:
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: none
                      required:
                        - kind
                      additionalProperties: false
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: trace_input
                        query:
                          type: string
                          minLength: 1
                          maxLength: 4096
                      required:
                        - kind
                        - query
                      additionalProperties: false
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: span_content
                        query:
                          type: string
                          maxLength: 4096
                        trace_id:
                          type: string
                          format: uuid
                      required:
                        - kind
                        - query
                      additionalProperties: false
                start_inclusive:
                  type: string
                  format: date-time
                end_exclusive:
                  type: string
                  format: date-time
                filters:
                  type: object
                  properties:
                    agent_name:
                      type:
                        - string
                        - 'null'
                    has_error:
                      type: boolean
                    has_issues:
                      type: boolean
                    tool:
                      anyOf:
                        - type: object
                          properties:
                            name:
                              type: 'null'
                          required:
                            - name
                          additionalProperties: false
                        - type: object
                          properties:
                            name:
                              type: string
                              minLength: 1
                            errors_only:
                              type: boolean
                          required:
                            - name
                          additionalProperties: false
                    model:
                      type:
                        - string
                        - 'null'
                    thread_id:
                      type:
                        - string
                        - 'null'
                      minLength: 1
                    attribute_filters:
                      type: array
                      items:
                        type: object
                        properties:
                          path:
                            type: string
                            minLength: 1
                            maxLength: 256
                          op:
                            type: string
                            minLength: 1
                            maxLength: 32
                          value:
                            anyOf:
                              - type: string
                              - type: number
                              - type: boolean
                          values:
                            type: array
                            items:
                              anyOf:
                                - type: string
                                - type: number
                                - type: boolean
                            minItems: 1
                            maxItems: 20
                        required:
                          - path
                          - op
                        additionalProperties: false
                      maxItems: 20
                    min_spans:
                      type: integer
                      minimum: 0
                    max_spans:
                      type: integer
                      minimum: 0
                    min_duration_ms:
                      type: number
                      minimum: 0
                    max_duration_ms:
                      type: number
                      minimum: 0
                    min_tokens:
                      type: integer
                      minimum: 0
                    min_thread_traces:
                      type: integer
                      minimum: 1
                    max_thread_traces:
                      type: integer
                      minimum: 1
                  additionalProperties: false
                requested_facets:
                  type: array
                  items:
                    type: string
                    enum:
                      - agent
                      - status
                      - tool
                      - model
                      - span
                      - error_status
                      - service
                      - attribute_key
                  minItems: 1
                  maxItems: 8
                facet_max_values:
                  type: integer
                  minimum: 1
                  maximum: 200
                cursor:
                  type: string
                  minLength: 1
                  maxLength: 16384
              required:
                - project_id
                - requested_facets
              additionalProperties: false
      responses:
        '200':
          description: Query trace facets
          content:
            application/json:
              schema:
                type: object
                properties:
                  facets:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          enum:
                            - agent
                            - status
                            - tool
                            - model
                            - span
                            - error_status
                            - service
                            - attribute_key
                        values:
                          type: array
                          items:
                            type: object
                            properties:
                              value:
                                type: string
                              count:
                                type:
                                  - number
                                  - 'null'
                            required:
                              - value
                              - count
                            additionalProperties: false
                        count_kind:
                          type: string
                          enum:
                            - traces
                            - spans
                        enumeration:
                          type: string
                          enum:
                            - complete
                            - bounded
                            - not_enumerable
                        searchable:
                          type: boolean
                      required:
                        - field
                        - values
                        - count_kind
                        - enumeration
                        - searchable
                      additionalProperties: false
                  attribute_fields:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        trace_count:
                          type: integer
                          minimum: 0
                        values:
                          type: array
                          items:
                            type: object
                            properties:
                              value:
                                type: string
                              count:
                                type:
                                  - number
                                  - 'null'
                            required:
                              - value
                              - count
                            additionalProperties: false
                        enumeration:
                          type: string
                          enum:
                            - complete
                            - bounded
                            - not_enumerable
                        searchable:
                          type: boolean
                          const: true
                      required:
                        - path
                        - trace_count
                        - values
                        - enumeration
                        - searchable
                      additionalProperties: false
                  meta:
                    type: object
                    properties:
                      scoped_trace_count:
                        type: integer
                        minimum: 0
                      sampled_trace_count:
                        type: integer
                        minimum: 0
                      count_relation:
                        type: string
                        enum:
                          - exact
                          - lower_bound
                      completeness:
                        type: string
                        enum:
                          - complete
                          - partial
                      applied_time_range:
                        type: object
                        properties:
                          start:
                            type:
                              - string
                              - 'null'
                          end:
                            type:
                              - string
                              - 'null'
                        required:
                          - start
                          - end
                        additionalProperties: false
                    required:
                      - scoped_trace_count
                      - sampled_trace_count
                      - count_relation
                      - completeness
                      - applied_time_range
                    additionalProperties: false
                  next_request:
                    type:
                      - object
                      - 'null'
                    properties:
                      operation:
                        type: string
                        minLength: 1
                      arguments:
                        type: object
                        properties:
                          project_id:
                            type: string
                            minLength: 1
                          match:
                            oneOf:
                              - type: object
                                properties:
                                  kind:
                                    type: string
                                    const: none
                                required:
                                  - kind
                                additionalProperties: false
                              - type: object
                                properties:
                                  kind:
                                    type: string
                                    const: trace_input
                                  query:
                                    type: string
                                    minLength: 1
                                    maxLength: 4096
                                required:
                                  - kind
                                  - query
                                additionalProperties: false
                              - type: object
                                properties:
                                  kind:
                                    type: string
                                    const: span_content
                                  query:
                                    type: string
                                    maxLength: 4096
                                  trace_id:
                                    type: string
                                    format: uuid
                                required:
                                  - kind
                                  - query
                                additionalProperties: false
                          start_inclusive:
                            type: string
                            format: date-time
                          end_exclusive:
                            type: string
                            format: date-time
                          filters:
                            type: object
                            properties:
                              agent_name:
                                type:
                                  - string
                                  - 'null'
                              has_error:
                                type: boolean
                              has_issues:
                                type: boolean
                              tool:
                                anyOf:
                                  - type: object
                                    properties:
                                      name:
                                        type: 'null'
                                    required:
                                      - name
                                    additionalProperties: false
                                  - type: object
                                    properties:
                                      name:
                                        type: string
                                        minLength: 1
                                      errors_only:
                                        type: boolean
                                    required:
                                      - name
                                    additionalProperties: false
                              model:
                                type:
                                  - string
                                  - 'null'
                              thread_id:
                                type:
                                  - string
                                  - 'null'
                                minLength: 1
                              attribute_filters:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    path:
                                      type: string
                                      minLength: 1
                                      maxLength: 256
                                    op:
                                      type: string
                                      minLength: 1
                                      maxLength: 32
                                    value:
                                      anyOf:
                                        - type: string
                                        - type: number
                                        - type: boolean
                                    values:
                                      type: array
                                      items:
                                        anyOf:
                                          - type: string
                                          - type: number
                                          - type: boolean
                                      minItems: 1
                                      maxItems: 20
                                  required:
                                    - path
                                    - op
                                  additionalProperties: false
                                maxItems: 20
                              min_spans:
                                type: integer
                                minimum: 0
                              max_spans:
                                type: integer
                                minimum: 0
                              min_duration_ms:
                                type: number
                                minimum: 0
                              max_duration_ms:
                                type: number
                                minimum: 0
                              min_tokens:
                                type: integer
                                minimum: 0
                              min_thread_traces:
                                type: integer
                                minimum: 1
                              max_thread_traces:
                                type: integer
                                minimum: 1
                            additionalProperties: false
                          requested_facets:
                            type: array
                            items:
                              type: string
                              enum:
                                - agent
                                - status
                                - tool
                                - model
                                - span
                                - error_status
                                - service
                                - attribute_key
                            minItems: 1
                            maxItems: 8
                          facet_max_values:
                            type: integer
                            minimum: 1
                            maximum: 200
                          cursor:
                            type: string
                            minLength: 1
                            maxLength: 16384
                        additionalProperties: false
                    required:
                      - operation
                      - arguments
                    additionalProperties: false
                required:
                  - facets
                  - attribute_fields
                  - meta
                  - next_request
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
                required:
                  - detail
                additionalProperties: false
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
                required:
                  - detail
                additionalProperties: false
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
                required:
                  - detail
                additionalProperties: false
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
                required:
                  - detail
                additionalProperties: false
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.