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

> Search a project’s traces.



## OpenAPI

````yaml https://api.uselemma.ai/openapi.json post /traces/query
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/query:
    post:
      tags:
        - Traces
      summary: Query traces
      description: Search a project’s traces.
      operationId: query_traces
      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
                        sort:
                          type: string
                          enum:
                            - timestamp_desc
                            - timestamp_asc
                            - duration_desc
                            - duration_asc
                            - spans_desc
                            - spans_asc
                        fields:
                          type: array
                          items:
                            type: string
                            enum:
                              - otel_trace_id
                              - timestamp
                              - agent_name
                              - thread_id
                              - total_duration_ms
                              - span_count
                              - has_error
                              - score
                              - root_span
                          minItems: 1
                      required:
                        - kind
                        - fields
                      additionalProperties: false
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: trace_input
                        query:
                          type: string
                          minLength: 1
                          maxLength: 4096
                        sort:
                          type: string
                          enum:
                            - timestamp_desc
                            - timestamp_asc
                            - duration_desc
                            - duration_asc
                            - spans_desc
                            - spans_asc
                        fields:
                          type: array
                          items:
                            type: string
                            enum:
                              - otel_trace_id
                              - timestamp
                              - agent_name
                              - thread_id
                              - total_duration_ms
                              - span_count
                              - has_error
                              - score
                              - root_span
                          minItems: 1
                      required:
                        - kind
                        - query
                        - fields
                      additionalProperties: false
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: span_content
                        query:
                          type: string
                          maxLength: 4096
                        trace_id:
                          type: string
                          format: uuid
                        sort:
                          type: string
                          enum:
                            - relevance
                            - timestamp_desc
                            - timestamp_asc
                            - duration_desc
                            - duration_asc
                            - spans_desc
                            - spans_asc
                        fields:
                          type: array
                          items:
                            type: string
                            enum:
                              - otel_trace_id
                              - timestamp
                              - agent_name
                              - thread_id
                              - total_duration_ms
                              - span_count
                              - has_error
                              - score
                              - root_span
                              - matching_spans
                          minItems: 1
                      required:
                        - kind
                        - query
                        - fields
                      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
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                cursor:
                  type: string
                  minLength: 1
                  maxLength: 16384
              required:
                - project_id
                - match
              additionalProperties: false
      responses:
        '200':
          description: Query traces
          content:
            application/json:
              schema:
                type: object
                properties:
                  traces:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        otel_trace_id:
                          type:
                            - string
                            - 'null'
                        timestamp:
                          type:
                            - string
                            - 'null'
                          format: date-time
                        agent_name:
                          type:
                            - string
                            - 'null'
                        thread_id:
                          type:
                            - string
                            - 'null'
                        total_duration_ms:
                          type:
                            - number
                            - 'null'
                        span_count:
                          type: integer
                          minimum: 0
                        has_error:
                          type: boolean
                        score:
                          type:
                            - number
                            - 'null'
                        matching_spans:
                          type: array
                          items:
                            type: object
                            properties:
                              match_id:
                                type: string
                              span_id:
                                type:
                                  - string
                                  - 'null'
                              span_name:
                                type:
                                  - string
                                  - 'null'
                              field:
                                type: string
                              attribute_path:
                                type:
                                  - string
                                  - 'null'
                              snippet:
                                type: string
                              rank:
                                type: number
                              span:
                                anyOf:
                                  - type: object
                                    properties:
                                      kind:
                                        type:
                                          - string
                                          - 'null'
                                      status_code:
                                        type:
                                          - string
                                          - 'null'
                                      attributes:
                                        type: object
                                        additionalProperties: {}
                                    required:
                                      - kind
                                      - status_code
                                      - attributes
                                    additionalProperties: false
                                  - type: object
                                    properties:
                                      kind:
                                        type:
                                          - string
                                          - 'null'
                                      status_code:
                                        type:
                                          - string
                                          - 'null'
                                      attributes_omitted:
                                        type: boolean
                                        const: true
                                    required:
                                      - kind
                                      - status_code
                                      - attributes_omitted
                                    additionalProperties: false
                            required:
                              - match_id
                              - span_id
                              - span_name
                              - field
                              - attribute_path
                              - snippet
                              - rank
                            additionalProperties: false
                        root_span:
                          anyOf:
                            - type: object
                              properties:
                                attributes:
                                  type: object
                                  additionalProperties:
                                    anyOf:
                                      - type: string
                                      - type: number
                                      - type: boolean
                                attributes_truncated:
                                  type: boolean
                              required:
                                - attributes
                                - attributes_truncated
                              additionalProperties: false
                            - type: object
                              properties:
                                attributes_omitted:
                                  type: boolean
                                  const: true
                              required:
                                - attributes_omitted
                              additionalProperties: false
                      required:
                        - id
                      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
                                  sort:
                                    type: string
                                    enum:
                                      - timestamp_desc
                                      - timestamp_asc
                                      - duration_desc
                                      - duration_asc
                                      - spans_desc
                                      - spans_asc
                                  fields:
                                    type: array
                                    items:
                                      type: string
                                      enum:
                                        - otel_trace_id
                                        - timestamp
                                        - agent_name
                                        - thread_id
                                        - total_duration_ms
                                        - span_count
                                        - has_error
                                        - score
                                        - root_span
                                    minItems: 1
                                required:
                                  - kind
                                  - fields
                                additionalProperties: false
                              - type: object
                                properties:
                                  kind:
                                    type: string
                                    const: trace_input
                                  query:
                                    type: string
                                    minLength: 1
                                    maxLength: 4096
                                  sort:
                                    type: string
                                    enum:
                                      - timestamp_desc
                                      - timestamp_asc
                                      - duration_desc
                                      - duration_asc
                                      - spans_desc
                                      - spans_asc
                                  fields:
                                    type: array
                                    items:
                                      type: string
                                      enum:
                                        - otel_trace_id
                                        - timestamp
                                        - agent_name
                                        - thread_id
                                        - total_duration_ms
                                        - span_count
                                        - has_error
                                        - score
                                        - root_span
                                    minItems: 1
                                required:
                                  - kind
                                  - query
                                  - fields
                                additionalProperties: false
                              - type: object
                                properties:
                                  kind:
                                    type: string
                                    const: span_content
                                  query:
                                    type: string
                                    maxLength: 4096
                                  trace_id:
                                    type: string
                                    format: uuid
                                  sort:
                                    type: string
                                    enum:
                                      - relevance
                                      - timestamp_desc
                                      - timestamp_asc
                                      - duration_desc
                                      - duration_asc
                                      - spans_desc
                                      - spans_asc
                                  fields:
                                    type: array
                                    items:
                                      type: string
                                      enum:
                                        - otel_trace_id
                                        - timestamp
                                        - agent_name
                                        - thread_id
                                        - total_duration_ms
                                        - span_count
                                        - has_error
                                        - score
                                        - root_span
                                        - matching_spans
                                    minItems: 1
                                required:
                                  - kind
                                  - query
                                  - fields
                                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
                          limit:
                            type: integer
                            minimum: 1
                            maximum: 100
                          cursor:
                            type: string
                            minLength: 1
                            maxLength: 16384
                        additionalProperties: false
                    required:
                      - operation
                      - arguments
                    additionalProperties: false
                required:
                  - traces
                  - 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.