Skip to main content
Use Search endpoints to build complex queries and retrieve your data via API. The operators below can be used to build filters that help you find relevant sessions, traces, and completions based on cost, latency, metadata, online evaluation results, human labels or notes, and more. This guide supplements the Search API endpoints (POST /search/sessions, POST /search/traces, POST /search/completions) from the OpenAPI specification. While the OpenAPI spec defines the endpoint structure and request/response schemas, this page provides detailed documentation on all available filter operators and how to construct complex queries to search your observability data effectively.

​
Endpoints

EndpointDescription
POST /search/sessionsSearch sessions
POST /search/tracesSearch traces
POST /search/completionsSearch completions
All endpoints support pagination via page and page_size query parameters. 
curl -X POST \
  -H "Authorization: Bearer $FREEPLAY_API_KEY" \
  -H "Content-Type: application/json" \
  "https://app.freeplay.ai/api/v2/projects/$PROJECT_ID/search/completions?page=1&page_size=20" \
  -d '{"filters": {"field": "cost", "op": "gte", "value": 0.01}}'

​
Filter Operators

OperatorDescription
eqEquals
ltLess than
gtGreater than
lteLess than or equal
gteGreater than or equal
containsContains substring
betweenWithin numeric range

​
Available Filters

The table below lists all available filter fields, their supported operators, and example values. Fields ending in .* support filtering on nested JSON properties.
FieldSupported OperatorsExample Value
costeq, lt, gt, lte, gte0.003
latencyeq, lt, gt, lte, gte8
start_timeeq, lt, gt, lte, gte"2024-06-01 00:00:00"
environmenteq"staging"
prompt_templateeq"my-prompt"
prompt_template_ideq"uuid..."
modeleq"gpt-4o"
providereq"openai"
review_statuseq"review_complete"
agent_nameeq"support-agent"
trace_agent_nameeq"my-agent"
api_keyeq"production-key"
assigneeeq"user@example.com"
review_themeeq"Response Quality Issues"
completion_outputcontains"weather"
completion_inputs.*contains"topic": "weather"
completion_feedback.*contains"rating": "positive"
session_custom_metadata.*contains"user_type": "premium"
trace_custom_metadata.*contains"workflow": "onboarding"
trace_input.*contains"query": "weather"
trace_output.*contains"response": "sunny"
trace_feedback.*contains"rating": "positive"
completion_evaluation_results.*eq"Response Quality": "4"
completion_client_evaluation_results.*eq"score": "85"
trace_evaluation_results.*eq, gt, lt, gte, lte, contains"Quality Score": 5
trace_client_eval_results.*eq, contains"confidence_score": 0.95
evaluation_notes.contentcontains"needs review"
evaluation_notes.authoreq"user@example.com"
evaluation_notes.created_atgt, lt, gte, lte"2024-06-01 00:00:00"

​
Compound Filters

Combine multiple filters using logical operators (and, or, not) to build complex queries. These operators can be nested to any depth.

​
Using and

All conditions must be true: 
{
  "filters": {
    "and": [
      {"field": "cost", "op": "gte", "value": 0.001},
      {"field": "model", "op": "eq", "value": "gpt-4o"}
    ]
  }
}

​
Using or

At least one condition must be true: 
{
  "filters": {
    "or": [
      {"field": "model", "op": "eq", "value": "gpt-4o"},
      {"field": "model", "op": "eq", "value": "claude-3-opus"}
    ]
  }
}

​
Using not

Negates a condition: 
{
  "filters": {
    "not": {"field": "environment", "op": "eq", "value": "prod"}
  }
}

​
Combined Example

Find expensive completions using either GPT-4o or Claude 3 Opus, excluding production: 
{
  "filters": {
    "and": [
      {"field": "cost", "op": "gte", "value": 0.001},
      {
        "or": [
          {"field": "model", "op": "eq", "value": "gpt-4o"},
          {"field": "model", "op": "eq", "value": "claude-3-opus"}
        ]
      },
      {
        "not": {"field": "environment", "op": "eq", "value": "prod"}
      }
    ]
  }
}