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

> 
Query sessions using advanced filters. Use to find specific
conversations or filter by metadata.

Supports pagination and optional inclusion of all 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/sessions
openapi: 3.1.0
info:
  title: Freeplay API
  version: 0.1.0
servers: []
security:
  - BearerAuth: []
paths:
  /api/v2/projects/{project_id}/search/sessions:
    post:
      tags:
        - Search & Analytics
      summary: Search Sessions
      description: >-

        Query sessions using advanced filters. Use to find specific

        conversations or filter by metadata.


        Supports pagination and optional inclusion of all 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_sessions
      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/SessionSearchInfo'
                        type: array
                      - items:
                          $ref: '#/components/schemas/SessionSearchInfoWithChildren'
                        type: array
                    title: Data
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
                required:
                  - data
                  - pagination
                title: SessionSearchResponse
                type: object
          description: >-
            SessionSearchResponse(data:
            Union[List[server.search_api.types.SessionSearchInfo],
            List[server.search_api.types.SessionSearchInfoWithChildren]],
            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
    SessionSearchInfo:
      properties:
        session_id:
          format: uuid
          title: Session Id
          type: string
        review_queue_id:
          title: Review Queue Id
          format: uuid
          type:
            - string
            - 'null'
        session_metadata:
          $ref: '#/components/schemas/SessionMetadataInfo'
        usage:
          $ref: '#/components/schemas/UsageInfo'
        custom_metadata:
          title: Custom Metadata
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
          type:
            - object
            - 'null'
        test_run_id:
          title: Test Run Id
          format: uuid
          type:
            - string
            - 'null'
      required:
        - session_id
        - review_queue_id
        - session_metadata
        - usage
        - custom_metadata
        - test_run_id
      title: SessionSearchInfo
      type: object
    SessionSearchInfoWithChildren:
      properties:
        session_id:
          format: uuid
          title: Session Id
          type: string
        review_queue_id:
          title: Review Queue Id
          format: uuid
          type:
            - string
            - 'null'
        session_metadata:
          $ref: '#/components/schemas/SessionMetadataInfo'
        usage:
          $ref: '#/components/schemas/UsageInfo'
        custom_metadata:
          title: Custom Metadata
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
          type:
            - object
            - 'null'
        test_run_id:
          title: Test Run Id
          format: uuid
          type:
            - string
            - 'null'
        children:
          items:
            anyOf:
              - $ref: '#/components/schemas/CompletionSearchInfoWithChildren'
              - $ref: '#/components/schemas/TraceSearchInfoWithChildren'
          title: Children
          type: array
      required:
        - session_id
        - review_queue_id
        - session_metadata
        - usage
        - custom_metadata
        - test_run_id
      title: SessionSearchInfoWithChildren
      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
    SessionMetadataInfo:
      properties:
        start_time:
          title: Start Time
          type:
            - string
            - 'null'
        end_time:
          title: End Time
          type:
            - string
            - 'null'
      required:
        - start_time
        - end_time
      title: SessionMetadataInfo
      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
    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
    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
    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
    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
    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
    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'
    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
    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

````