---
title: "List Sessions"
method: GET
path: "/api/v2/projects/{project_id}/sessions"
tags: ["Search & Analytics"]
---

# List Sessions

`GET /api/v2/projects/{project_id}/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.

## Path parameters

- `project_id` string, required

## Query parameters

- `page` integer
- `page_size` integer
- `to_date` string, nullable
- `from_date` string, nullable
- `test_list` string, nullable
- `test_run_id` string, nullable
- `prompt_name` string, nullable
- `review_queue_id` string, nullable

## Response `200`

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.

- DetailedSessionInfo[]
  - `session_id` string, uuid, required
  - `start_time` string, required
  - `custom_metadata` object, required
  - `messages` SessionCompletionInfo[], required
    - `message_type` string, required
    - `completion_id` string, uuid, required
    - `environment` string, nullable, required
    - `provider_name` string, nullable, required
    - `model_name` string, nullable, required
    - `input_variables` object, required
    - `prompt` union[], required
      - union
        - UserMessage
          - `content` union, required
            - string
            - union[]
              - …
          - `role` 'user'
        - SystemMessage
          - `content` string, required
          - `role` 'system'
        - DeveloperMessage
          - `content` string, required
          - `role` 'developer'
        - AssistantMessage
          - `content` union, required
            - string
            - union[]
              - …
          - `role` 'assistant'
    - `prompt_template_name` string, nullable, required
    - `response` string, nullable, required
    - `customer_feedback` object, required
    - `evaluation_results` EvaluationResultInfo[], required
      - `name` string, required
      - `manual_score` union, required
        - boolean
        - integer
        - number
        - string
        - object
        - JSONValue[]
      - `auto_eval_score` union, required
        - boolean
        - integer
        - number
        - string
        - object
        - JSONValue[]
    - `client_evaluation_results` ClientEvaluationResultInfo[], required
      - `name` string, required
      - `value` union, required
        - boolean
        - integer
        - number
        - string
        - object
        - JSONValue[]
    - `notes` EvaluationNoteExportInfo[], nullable, required
      - `id` string, uuid, required
      - `content` string, required
      - `created_at` string, required
      - `created_by` UserAPIInfo, required
        - `id` string, uuid, required
        - `email_address` string, required
        - `first_name` string, required
        - `last_name` string, required
    - `trace_id` string, uuid, nullable, required
    - `format_version` integer, nullable, required
    - `start_time` string, nullable, required
    - `end_time` string, nullable, required

---

[API](https://skmtc.net/freeplay/apis/freeplay-api.md) · [All operations](https://skmtc.net/freeplay/apis/freeplay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/freeplay/freeplay-api/revisions/69c553220183/schema)