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

# List Sessions

> 
Retrieve sessions with their completions, ordered by most recent first. Use to display conversation history or analyze LLM usage patterns. Traces are referenced by ID but not expanded.

Filter by custom metadata using query parameters prefixed with `custom_metadata.` (e.g., `custom_metadata.user_id=123`).

`page_size` defaults to 10, maximum 100.

Prefer using the `/search/sessions` endpoint for more advanced filtering.



## OpenAPI

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

        Retrieve sessions with their completions, ordered by most recent first.
        Use to display conversation history or analyze LLM usage patterns.
        Traces are referenced by ID but not expanded.


        Filter by custom metadata using query parameters prefixed with
        `custom_metadata.` (e.g., `custom_metadata.user_id=123`).


        `page_size` defaults to 10, maximum 100.


        Prefer using the `/search/sessions` endpoint for more advanced
        filtering.
      operationId: get_get_sessions_filtered
      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: 10
            title: Page Size
            type: integer
        - name: to_date
          in: query
          schema:
            default: null
            title: To Date
            type:
              - string
              - 'null'
        - name: from_date
          in: query
          schema:
            default: null
            title: From Date
            type:
              - string
              - 'null'
        - name: test_list
          in: query
          schema:
            default: null
            title: Test List
            type:
              - string
              - 'null'
        - name: test_run_id
          in: query
          schema:
            default: null
            title: Test Run Id
            type:
              - string
              - 'null'
        - name: prompt_name
          in: query
          schema:
            default: null
            title: Prompt Name
            type:
              - string
              - 'null'
        - name: review_queue_id
          in: query
          schema:
            default: null
            title: Review Queue Id
            type:
              - string
              - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DetailedSessionInfo'
                type: array
          description: >-
            The type of parameterized generics.


            That is, for example, `type(List[int])` is `_GenericAlias`.


            Objects which are instances of this class include:

            * Parameterized container types, e.g. `Tuple[int]`, `List[int]`.
             * Note that native container types, e.g. `tuple`, `list`, use
               `types.GenericAlias` instead.
            * Parameterized classes:
                class C[T]: pass
                # C[int] is a _GenericAlias
            * `Callable` aliases, generic `Callable` aliases, and
              parameterized `Callable` aliases:
                T = TypeVar('T')
                # _CallableGenericAlias inherits from _GenericAlias.
                A = Callable[[], None]  # _CallableGenericAlias
                B = Callable[[T], None]  # _CallableGenericAlias
                C = B[int]  # _CallableGenericAlias
            * Parameterized `Final`, `ClassVar`, `TypeForm`, `TypeGuard`, and
            `TypeIs`:
                # All _GenericAlias
                Final[int]
                ClassVar[float]
                TypeForm[bytearray]
                TypeGuard[bool]
                TypeIs[range]

            Note that instances of this class are not classes (e.g by
            `inspect.isclass`),

            even though they behave like them.
components:
  schemas:
    DetailedSessionInfo:
      properties:
        session_id:
          format: uuid
          title: Session Id
          type: string
        start_time:
          title: Start Time
          type: string
        custom_metadata:
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
          title: Custom Metadata
          type: object
        messages:
          items:
            $ref: '#/components/schemas/SessionCompletionInfo'
          title: Messages
          type: array
      required:
        - session_id
        - start_time
        - custom_metadata
        - messages
      title: DetailedSessionInfo
      type: object
    SessionCompletionInfo:
      properties:
        message_type:
          title: Message Type
          type: string
        completion_id:
          format: uuid
          title: Completion Id
          type: string
        environment:
          title: Environment
          type:
            - string
            - 'null'
        provider_name:
          title: Provider Name
          type:
            - string
            - 'null'
        model_name:
          title: Model Name
          type:
            - string
            - 'null'
        input_variables:
          additionalProperties:
            $ref: '#/components/schemas/InputVariable'
          title: Input Variables
          type: object
        prompt:
          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: Prompt
          type: array
        prompt_template_name:
          title: Prompt Template Name
          type:
            - string
            - 'null'
        response:
          title: Response
          type:
            - string
            - 'null'
        customer_feedback:
          additionalProperties:
            anyOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
          title: Customer Feedback
          type: object
        evaluation_results:
          items:
            $ref: '#/components/schemas/EvaluationResultInfo'
          title: Evaluation Results
          type: array
        client_evaluation_results:
          items:
            $ref: '#/components/schemas/ClientEvaluationResultInfo'
          title: Client Evaluation Results
          type: array
        notes:
          title: Notes
          items:
            $ref: '#/components/schemas/EvaluationNoteExportInfo'
          type:
            - array
            - 'null'
        trace_id:
          title: Trace Id
          format: uuid
          type:
            - string
            - 'null'
        format_version:
          title: Format Version
          type:
            - integer
            - 'null'
        start_time:
          title: Start Time
          type:
            - string
            - 'null'
        end_time:
          title: End Time
          type:
            - string
            - 'null'
      required:
        - message_type
        - completion_id
        - environment
        - provider_name
        - model_name
        - input_variables
        - prompt
        - prompt_template_name
        - response
        - customer_feedback
        - evaluation_results
        - client_evaluation_results
        - notes
        - trace_id
        - format_version
        - start_time
        - end_time
      title: SessionCompletionInfo
      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
    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
    EvaluationResultInfo:
      properties:
        name:
          title: Name
          type: string
        manual_score:
          $ref: '#/components/schemas/JSONValue'
        auto_eval_score:
          $ref: '#/components/schemas/JSONValue'
      required:
        - name
        - manual_score
        - auto_eval_score
      title: EvaluationResultInfo
      type: object
    ClientEvaluationResultInfo:
      properties:
        name:
          title: Name
          type: string
        value:
          $ref: '#/components/schemas/JSONValue'
      required:
        - name
        - value
      title: ClientEvaluationResultInfo
      type: object
    EvaluationNoteExportInfo:
      properties:
        id:
          format: uuid
          title: Id
          type: string
        content:
          title: Content
          type: string
        created_at:
          title: Created At
          type: string
        created_by:
          $ref: '#/components/schemas/UserAPIInfo'
      required:
        - id
        - content
        - created_at
        - created_by
      title: EvaluationNoteExportInfo
      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
    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'
    UserAPIInfo:
      properties:
        id:
          format: uuid
          title: Id
          type: string
        email_address:
          title: Email Address
          type: string
        first_name:
          title: First Name
          type: string
        last_name:
          title: Last Name
          type: string
      required:
        - id
        - email_address
        - first_name
        - last_name
      title: UserAPIInfo
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````