Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.freeplay.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

EndpointDescriptionAPI Reference
POST /search/sessionsSearch sessionsSearch Sessions
POST /search/tracesSearch tracesSearch Traces
POST /search/completionsSearch 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..."
completion_ideq"uuid..."
session_ideq"uuid..."
test_run_ideq"uuid..."
review_queue_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"
insight_nameeq"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"}
      }
    ]
  }
}