Search API Operators

Filter operators and query syntax for the Search API endpoints

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 from the OpenAPI specification. While the 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.

Endpoints

Endpoint	Description	API Reference
POST /search/sessions	Search sessions	Search Sessions
POST /search/traces	Search traces	Search Traces
POST /search/completions	Search completions	Search 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

Operator	Description
eq	Equals
lt	Less than
gt	Greater than
lte	Less than or equal
gte	Greater than or equal
contains	Contains substring
between	Within 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.

Field	Supported Operators	Example Value
cost	eq, lt, gt, lte, gte	0.003
latency	eq, lt, gt, lte, gte	8
start_time	eq, lt, gt, lte, gte	"2024-06-01 00:00:00"
environment	eq	"staging"
prompt_template	eq	"my-prompt"
prompt_template_id	eq	"uuid..."
completion_id	eq	"uuid..."
session_id	eq	"uuid..."
test_run_id	eq	"uuid..."
review_queue_id	eq	"uuid..."
model	eq	"gpt-4o"
provider	eq	"openai"
review_status	eq	"review_complete"
agent_name	eq	"support-agent"
trace_agent_name	eq	"my-agent"
api_key	eq	"production-key"
assignee	eq	"[e-mail]"
insight_name	eq	"Response Quality Issues"
completion_output	contains	"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.content	contains	"needs review"
evaluation_notes.author	eq	"[e-mail]"
evaluation_notes.created_at	gt, 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"}
      }
    ]
  }
}