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

# Search Traces

> 
Query traces using advanced filters. Use to find specific trace
executions, filter by metadata, or analyze trace patterns.

Supports pagination and optional inclusion of all child traces and
completions within the session, using the `include_children` parameter.

`page_size` defaults to 30, maximum 100.

For filter operators and examples, see: https://docs.freeplay.ai/openapi/search-api-operators



## OpenAPI

````yaml https://app.freeplay.ai/openapi.json post /api/v2/projects/{project_id}/search/traces
openapi: 3.1.0
info:
  title: Freeplay API
  version: 0.1.0
servers: []
security:
  - BearerAuth: []
paths:
  /api/v2/projects/{project_id}/search/traces:
    post:
      tags:
        - Search & Analytics
      summary: Search Traces
      description: >-

        Query traces using advanced filters. Use to find specific trace

        executions, filter by metadata, or analyze trace patterns.


        Supports pagination and optional inclusion of all child traces and

        completions within the session, using the `include_children` parameter.


        `page_size` defaults to 30, maximum 100.


        For filter operators and examples, see:
        https://docs.freeplay.ai/openapi/search-api-operators
      operationId: post_search_traces
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            default: 1
            title: Page
            type: integer
        - name: page_size
          in: query
          schema:
            default: 30
            title: Page Size
            type: integer
        - name: include_children
          in: query
          schema:
            default: false
            title: Include Children
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              properties:
                filters:
                  anyOf:
                    - $ref: '#/components/schemas/FieldFilter'
                    - $ref: '#/components/schemas/AndFilter'
                    - $ref: '#/components/schemas/OrFilter'
                    - $ref: '#/components/schemas/NotFilter'
                    - $ref: '#/components/schemas/EmptyFilter'
                  title: Filters
              required:
                - filters
              title: SearchRequest
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    anyOf:
                      - items:
                          $ref: '#/components/schemas/TraceSearchInfo'
                        type: array
                      - items:
                          $ref: '#/components/schemas/TraceSearchInfoWithChildren'
                        type: array
                    title: Data
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
                required:
                  - data
                  - pagination
                title: TraceSearchResponse
                type: object
          description: >-
            TraceSearchResponse(data:
            Union[List[server.search_api.types.TraceSearchInfo],
            List[server.search_api.types.TraceSearchInfoWithChildren]],
            pagination: server.api_routes.api_v2_common.PaginationInfo)
components:
  schemas:
    FieldFilter:
      properties:
        field:
          title: Field
          type: string
        op:
          $ref: '#/components/schemas/FilterOperators'
        value:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - items:
                anyOf:
                  - type: integer
                  - type: number
              type: array
          title: Value
      required:
        - field
        - op
        - value
      title: FieldFilter
      type: object
    AndFilter:
      properties:
        and:
          items:
            anyOf:
              - $ref: '#/components/schemas/FieldFilter'
              - $ref: '#/components/schemas/AndFilter'
              - $ref: '#/components/schemas/OrFilter'
              - $ref: '#/components/schemas/NotFilter'
              - $ref: '#/components/schemas/EmptyFilter'
          title: And
          type: array
      required:
        - and
      title: AndFilter
      type: object
    OrFilter:
      properties:
        or:
          items:
            anyOf:
              - $ref: '#/components/schemas/FieldFilter'
              - $ref: '#/components/schemas/AndFilter'
              - $ref: '#/components/schemas/OrFilter'
              - $ref: '#/components/schemas/NotFilter'
              - $ref: '#/components/schemas/EmptyFilter'
          title: Or
          type: array
      required:
        - or
      title: OrFilter
      type: object
    NotFilter:
      properties:
        not:
          anyOf:
            - $ref: '#/components/schemas/FieldFilter'
            - $ref: '#/components/schemas/AndFilter'
            - $ref: '#/components/schemas/OrFilter'
            - $ref: '#/components/schemas/NotFilter'
            - $ref: '#/components/schemas/EmptyFilter'
          title: Not
      required:
        - not
      title: NotFilter
      type: object
    EmptyFilter:
      properties: {}
      title: EmptyFilter
      type: object
    TraceSearchInfo:
      properties:
        session_id:
          format: uuid
          title: Session Id
          type: string
        trace_id:
          format: uuid
          title: Trace Id
          type: string
        review_queue_id:
          title: Review Queue Id
          format: uuid
          type:
            - string
            - 'null'
        trace_metadata:
          oneOf:
            - $ref: '#/components/schemas/TraceMetadataInfo'
            - type: 'null'
        custom_metadata:
          title: Custom Metadata
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
          type:
            - object
            - 'null'
        customer_feedback:
          title: Customer Feedback
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
          type:
            - object
            - 'null'
        input:
          oneOf:
            - $ref: '#/components/schemas/JSONValue'
            - type: 'null'
        output:
          oneOf:
            - $ref: '#/components/schemas/JSONValue'
            - type: 'null'
        evaluation_results:
          $ref: '#/components/schemas/EvaluationResultsInfo'
      required:
        - session_id
        - trace_id
        - review_queue_id
        - trace_metadata
        - custom_metadata
        - customer_feedback
        - input
        - output
        - evaluation_results
      title: TraceSearchInfo
      type: object
    TraceSearchInfoWithChildren:
      properties:
        session_id:
          format: uuid
          title: Session Id
          type: string
        trace_id:
          format: uuid
          title: Trace Id
          type: string
        review_queue_id:
          title: Review Queue Id
          format: uuid
          type:
            - string
            - 'null'
        trace_metadata:
          oneOf:
            - $ref: '#/components/schemas/TraceMetadataInfo'
            - type: 'null'
        custom_metadata:
          title: Custom Metadata
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
          type:
            - object
            - 'null'
        customer_feedback:
          title: Customer Feedback
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
          type:
            - object
            - 'null'
        input:
          oneOf:
            - $ref: '#/components/schemas/JSONValue'
            - type: 'null'
        output:
          oneOf:
            - $ref: '#/components/schemas/JSONValue'
            - type: 'null'
        evaluation_results:
          $ref: '#/components/schemas/EvaluationResultsInfo'
        children:
          items:
            anyOf:
              - $ref: '#/components/schemas/CompletionSearchInfoWithChildren'
              - $ref: '#/components/schemas/TraceSearchInfoWithChildren'
          title: Children
          type: array
      required:
        - session_id
        - trace_id
        - review_queue_id
        - trace_metadata
        - custom_metadata
        - customer_feedback
        - input
        - output
        - evaluation_results
      title: TraceSearchInfoWithChildren
      type: object
    PaginationInfo:
      properties:
        page:
          title: Page
          type: integer
        page_size:
          title: Page Size
          type: integer
        has_next:
          title: Has Next
          type: boolean
      required:
        - page
        - page_size
        - has_next
      title: PaginationInfo
      type: object
    FilterOperators:
      enum:
        - eq
        - gt
        - gte
        - lt
        - lte
        - contains
        - between
      title: FilterOperators
      type: string
    TraceMetadataInfo:
      properties:
        agent_name:
          title: Agent Name
          type:
            - string
            - 'null'
        start_time:
          title: Start Time
          type:
            - string
            - 'null'
        end_time:
          title: End Time
          type:
            - string
            - 'null'
        assignee:
          title: Assignee
          type:
            - string
            - 'null'
      required:
        - agent_name
        - start_time
        - end_time
        - assignee
      title: TraceMetadataInfo
      type: object
    JSONValue:
      anyOf:
        - type: boolean
        - type: integer
        - type: number
        - type: string
        - additionalProperties:
            $ref: '#/components/schemas/JSONValue'
          type: object
        - items:
            $ref: '#/components/schemas/JSONValue'
          type: array
        - type: 'null'
    EvaluationResultsInfo:
      properties:
        auto_evaluations:
          additionalProperties:
            $ref: '#/components/schemas/AutoEvaluationInfo'
          title: Auto Evaluations
          type: object
        human_labels:
          additionalProperties:
            $ref: '#/components/schemas/HumanLabelInfo'
          title: Human Labels
          type: object
        client_evaluations:
          additionalProperties:
            anyOf:
              - type: boolean
              - type: number
          title: Client Evaluations
          type: object
      required:
        - auto_evaluations
        - human_labels
        - client_evaluations
      title: EvaluationResultsInfo
      type: object
    CompletionSearchInfoWithChildren:
      properties:
        completion_id:
          format: uuid
          title: Completion Id
          type: string
        session_id:
          format: uuid
          title: Session Id
          type: string
        review_queue_id:
          title: Review Queue Id
          format: uuid
          type:
            - string
            - 'null'
        evaluation_results:
          $ref: '#/components/schemas/EvaluationResultsInfo'
        completion_metadata:
          $ref: '#/components/schemas/CompletionMetadataInfo'
        customer_feedback:
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
          title: Customer Feedback
          type: object
        usage:
          $ref: '#/components/schemas/UsageInfo'
        messages:
          items:
            discriminator:
              mapping:
                assistant:
                  $ref: '#/components/schemas/AssistantMessage'
                developer:
                  $ref: '#/components/schemas/DeveloperMessage'
                system:
                  $ref: '#/components/schemas/SystemMessage'
                user:
                  $ref: '#/components/schemas/UserMessage'
              propertyName: role
            oneOf:
              - $ref: '#/components/schemas/UserMessage'
              - $ref: '#/components/schemas/SystemMessage'
              - $ref: '#/components/schemas/DeveloperMessage'
              - $ref: '#/components/schemas/AssistantMessage'
          title: Messages
          type: array
        input_variables:
          additionalProperties:
            $ref: '#/components/schemas/InputVariable'
          title: Input Variables
          type: object
        children:
          items:
            anyOf:
              - $ref: '#/components/schemas/CompletionSearchInfoWithChildren'
              - $ref: '#/components/schemas/TraceSearchInfoWithChildren'
          title: Children
          type: array
      required:
        - completion_id
        - session_id
        - review_queue_id
        - evaluation_results
        - completion_metadata
        - customer_feedback
        - usage
        - messages
        - input_variables
      title: CompletionSearchInfoWithChildren
      type: object
    AutoEvaluationInfo:
      properties:
        name:
          title: Name
          type: string
        auto_score:
          anyOf:
            - type: integer
            - type: string
            - type: 'null'
          title: Auto Score
        auto_explanation:
          title: Auto Explanation
          type:
            - string
            - 'null'
        manual_score:
          anyOf:
            - type: integer
            - type: string
            - type: 'null'
          title: Manual Score
      required:
        - name
        - auto_score
        - auto_explanation
        - manual_score
      title: AutoEvaluationInfo
      type: object
    HumanLabelInfo:
      properties:
        name:
          title: Name
          type: string
        manual_score:
          anyOf:
            - type: integer
            - type: string
            - type: 'null'
          title: Manual Score
      required:
        - name
        - manual_score
      title: HumanLabelInfo
      type: object
    CompletionMetadataInfo:
      properties:
        environment:
          title: Environment
          type:
            - string
            - 'null'
        start_time:
          title: Start Time
          type:
            - string
            - 'null'
        end_time:
          title: End Time
          type:
            - string
            - 'null'
        model:
          title: Model
          type:
            - string
            - 'null'
        provider:
          title: Provider
          type:
            - string
            - 'null'
        prompt_template:
          title: Prompt Template
          additionalProperties:
            anyOf:
              - type: string
              - format: uuid
                type: string
          type:
            - object
            - 'null'
        prompt_template_version_id:
          title: Prompt Template Version Id
          format: uuid
          type:
            - string
            - 'null'
        assignee:
          title: Assignee
          type:
            - string
            - 'null'
        prompt_version_name:
          title: Prompt Version Name
          type:
            - string
            - 'null'
        prompt_version_description:
          title: Prompt Version Description
          type:
            - string
            - 'null'
      required:
        - environment
        - start_time
        - end_time
        - model
        - provider
        - prompt_template
        - prompt_template_version_id
        - assignee
        - prompt_version_name
        - prompt_version_description
      title: CompletionMetadataInfo
      type: object
    UsageInfo:
      properties:
        prompt_tokens:
          title: Prompt Tokens
          type: integer
        completion_tokens:
          title: Completion Tokens
          type: integer
      required:
        - prompt_tokens
        - completion_tokens
      title: UsageInfo
      type: object
    AssistantMessage:
      properties:
        content:
          anyOf:
            - type: string
            - items:
                discriminator:
                  mapping:
                    audio:
                      $ref: '#/components/schemas/AudioBlock'
                    file:
                      $ref: '#/components/schemas/FileBlock'
                    image:
                      $ref: '#/components/schemas/ImageBlock'
                    text:
                      $ref: '#/components/schemas/TextBlock'
                    tool_call:
                      $ref: '#/components/schemas/ToolCallBlock'
                    tool_result:
                      $ref: '#/components/schemas/ToolResultBlock'
                  propertyName: type
                oneOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/ToolResultBlock'
                  - $ref: '#/components/schemas/ToolCallBlock'
                  - $ref: '#/components/schemas/ImageBlock'
                  - $ref: '#/components/schemas/AudioBlock'
                  - $ref: '#/components/schemas/FileBlock'
              type: array
          title: Content
        role:
          const: assistant
          default: assistant
          title: Role
          type: string
      required:
        - content
      title: AssistantMessage
      type: object
    DeveloperMessage:
      properties:
        content:
          title: Content
          type: string
        role:
          const: developer
          default: developer
          title: Role
          type: string
      required:
        - content
      title: DeveloperMessage
      type: object
    SystemMessage:
      properties:
        content:
          title: Content
          type: string
        role:
          const: system
          default: system
          title: Role
          type: string
      required:
        - content
      title: SystemMessage
      type: object
    UserMessage:
      properties:
        content:
          anyOf:
            - type: string
            - items:
                discriminator:
                  mapping:
                    audio:
                      $ref: '#/components/schemas/AudioBlock'
                    file:
                      $ref: '#/components/schemas/FileBlock'
                    image:
                      $ref: '#/components/schemas/ImageBlock'
                    text:
                      $ref: '#/components/schemas/TextBlock'
                    tool_call:
                      $ref: '#/components/schemas/ToolCallBlock'
                    tool_result:
                      $ref: '#/components/schemas/ToolResultBlock'
                  propertyName: type
                oneOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/ToolResultBlock'
                  - $ref: '#/components/schemas/ToolCallBlock'
                  - $ref: '#/components/schemas/ImageBlock'
                  - $ref: '#/components/schemas/AudioBlock'
                  - $ref: '#/components/schemas/FileBlock'
              type: array
          title: Content
        role:
          const: user
          default: user
          title: Role
          type: string
      required:
        - content
      title: UserMessage
      type: object
    InputVariable:
      anyOf:
        - type: string
        - type: integer
        - type: boolean
        - type: number
        - additionalProperties:
            $ref: '#/components/schemas/InputVariable'
          type: object
        - items:
            $ref: '#/components/schemas/InputVariable'
          type: array
    AudioBlock:
      properties:
        media_id:
          format: uuid
          title: Media Id
          type: string
        type:
          const: audio
          default: audio
          title: Type
          type: string
      required:
        - media_id
      title: AudioBlock
      type: object
    FileBlock:
      properties:
        media_id:
          format: uuid
          title: Media Id
          type: string
        filename:
          default: null
          title: Filename
          type:
            - string
            - 'null'
        type:
          const: file
          default: file
          title: Type
          type: string
      required:
        - media_id
      title: FileBlock
      type: object
    ImageBlock:
      properties:
        media_id:
          format: uuid
          title: Media Id
          type: string
        type:
          const: image
          default: image
          title: Type
          type: string
      required:
        - media_id
      title: ImageBlock
      type: object
    TextBlock:
      properties:
        text:
          title: Text
          type: string
        type:
          const: text
          default: text
          title: Type
          type: string
      required:
        - text
      title: TextBlock
      type: object
    ToolCallBlock:
      properties:
        id:
          title: Id
          type: string
        name:
          title: Name
          type: string
        arguments:
          $ref: '#/components/schemas/JSONValue'
        thought_signature:
          default: null
          title: Thought Signature
          type:
            - string
            - 'null'
        type:
          const: tool_call
          default: tool_call
          title: Type
          type: string
      required:
        - id
        - name
        - arguments
      title: ToolCallBlock
      type: object
    ToolResultBlock:
      properties:
        tool_call_id:
          title: Tool Call Id
          type: string
        content:
          anyOf:
            - type: string
            - items:
                discriminator:
                  mapping:
                    audio:
                      $ref: '#/components/schemas/AudioBlock'
                    file:
                      $ref: '#/components/schemas/FileBlock'
                    image:
                      $ref: '#/components/schemas/ImageBlock'
                    text:
                      $ref: '#/components/schemas/TextBlock'
                    tool_call:
                      $ref: '#/components/schemas/ToolCallBlock'
                    tool_result:
                      $ref: '#/components/schemas/ToolResultBlock'
                  propertyName: type
                oneOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/ToolResultBlock'
                  - $ref: '#/components/schemas/ToolCallBlock'
                  - $ref: '#/components/schemas/ImageBlock'
                  - $ref: '#/components/schemas/AudioBlock'
                  - $ref: '#/components/schemas/FileBlock'
              type: array
          title: Content
        type:
          const: tool_result
          default: tool_result
          title: Type
          type: string
      required:
        - tool_call_id
        - content
      title: ToolResultBlock
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````