---
title: "Search Traces"
method: POST
path: "/api/v2/projects/{project_id}/search/traces"
tags: ["Search & Analytics"]
---

# Search Traces

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

## Path parameters

- `project_id` string, required

## Query parameters

- `page` integer
- `page_size` integer
- `include_children` boolean

## Request body

- object
  - `filters` union, required
    - FieldFilter
      - `field` string, required
      - `op` 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'between', required
      - `value` union, required
        - string
        - integer
        - number
        - union[]
          - union
            - integer
            - number
    - AndFilter
      - `and` union[], required
        - union
          - FieldFilter
            - `field` string, required
            - `op` 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'between', required
            - `value` union, required
              - …
          - AndFilter — recursive
          - OrFilter
            - `or` union[], required
              - …
          - NotFilter
            - `not` union, required
              - …
          - EmptyFilter
    - OrFilter
      - `or` union[], required
        - union
          - FieldFilter
            - `field` string, required
            - `op` 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'between', required
            - `value` union, required
              - …
          - AndFilter
            - `and` union[], required
              - …
          - OrFilter — recursive
          - NotFilter
            - `not` union, required
              - …
          - EmptyFilter
    - NotFilter
      - `not` union, required
        - FieldFilter
          - `field` string, required
          - `op` 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'between', required
          - `value` union, required
            - string
            - integer
            - number
            - union[]
              - …
        - AndFilter
          - `and` union[], required
            - union
              - …
        - OrFilter
          - `or` union[], required
            - union
              - …
        - NotFilter — recursive
        - EmptyFilter
    - EmptyFilter

## Response `200`

TraceSearchResponse(data: Union[List[server.search_api.types.TraceSearchInfo], List[server.search_api.types.TraceSearchInfoWithChildren]], pagination: server.api_routes.api_v2_common.PaginationInfo)

- object
  - `data` union, required
    - TraceSearchInfo[]
      - `session_id` string, uuid, required
      - `trace_id` string, uuid, required
      - `review_queue_id` string, uuid, nullable, required
      - `trace_metadata` TraceMetadataInfo, required
        - `agent_name` string, nullable, required
        - `start_time` string, nullable, required
        - `end_time` string, nullable, required
        - `assignee` string, nullable, required
      - `custom_metadata` object, nullable, required
      - `customer_feedback` object, nullable, required
      - `input` union, required
        - boolean
        - integer
        - number
        - string
        - object
        - JSONValue[]
      - `output` union, required
        - boolean
        - integer
        - number
        - string
        - object
        - JSONValue[]
      - `evaluation_results` EvaluationResultsInfo, required
        - `auto_evaluations` object, required
        - `human_labels` object, required
        - `client_evaluations` object, required
    - TraceSearchInfoWithChildren[]
      - `session_id` string, uuid, required
      - `trace_id` string, uuid, required
      - `review_queue_id` string, uuid, nullable, required
      - `trace_metadata` TraceMetadataInfo, required
        - `agent_name` string, nullable, required
        - `start_time` string, nullable, required
        - `end_time` string, nullable, required
        - `assignee` string, nullable, required
      - `custom_metadata` object, nullable, required
      - `customer_feedback` object, nullable, required
      - `input` union, required
        - boolean
        - integer
        - number
        - string
        - object
        - JSONValue[]
      - `output` union, required
        - boolean
        - integer
        - number
        - string
        - object
        - JSONValue[]
      - `evaluation_results` EvaluationResultsInfo, required
        - `auto_evaluations` object, required
        - `human_labels` object, required
        - `client_evaluations` object, required
      - `children` union[]
        - union
          - CompletionSearchInfoWithChildren
            - `completion_id` string, uuid, required
            - `session_id` string, uuid, required
            - `review_queue_id` string, uuid, nullable, required
            - `evaluation_results` EvaluationResultsInfo, required
              - …
            - `completion_metadata` CompletionMetadataInfo, required
              - …
            - `customer_feedback` object, required
            - `usage` UsageInfo, required
              - …
            - `messages` union[], required
              - …
            - `input_variables` object, required
            - `children` union[]
              - …
          - TraceSearchInfoWithChildren — recursive
  - `pagination` PaginationInfo, required
    - `page` integer, required
    - `page_size` integer, required
    - `has_next` boolean, 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)