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

POST /api/v2/projects/{project_id}/search/traces

Search Traces

cURL

curl --request POST \
  --url https://api.example.com/api/v2/projects/{project_id}/search/traces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "field": "<string>",
    "value": "<string>"
  }
}
'

200

{
  "data": [
    {
      "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "trace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "review_queue_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "trace_metadata": {
        "agent_name": "<string>",
        "start_time": "<string>",
        "end_time": "<string>",
        "assignee": "<string>"
      },
      "custom_metadata": {},
      "customer_feedback": {},
      "input": true,
      "output": true,
      "evaluation_results": {
        "auto_evaluations": {},
        "human_labels": {},
        "client_evaluations": {}
      }
    }
  ],
  "pagination": {
    "page": 123,
    "page_size": 123,
    "has_next": true
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

project_id · string · required

Query Parameters

page · integer · default: 1

page_size · integer · default: 30

include_children · boolean · default: false

Body

application/json

filters · FieldFilter · object · required

FieldFilter

AndFilter

OrFilter

NotFilter

EmptyFilter

Show child attributes

Response

200 - application/json

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

data · TraceSearchInfo · object · required

TraceSearchInfo · object[]

TraceSearchInfoWithChildren · object[]

Show child attributes

pagination · PaginationInfo · object · required

Show child attributes