Skip to main content
The Search API allows you to query your sessions, traces, and completions with flexible filtering options. All endpoints support pagination and compound filters.

​
Endpoints

  • POST /api/v2/projects/{{projectid}}/search/completions
  • POST /api/v2/projects/{{projectid}}/search/traces
  • POST /api/v2/projects/{{projectid}}/search/sessions

​
Parameters

ParameterDescription
{{project_id}}Your Freeplay project ID. Found in your project settings or URL.
{{token}}Your Freeplay API key for authentication.

​
Operators

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

​
Sessions API

curl -X POST "https://dev.freeplay.ai/api/v2/projects/{{project_id}}/search/sessions?page=1&page_size=5" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -d '{"filters": {}}'

​
Traces API

curl -X POST "https://dev.freeplay.ai/api/v2/projects/{{project_id}}/search/traces?page=1&page_size=5" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -d '{"filters": {}}'

​
Completions API

curl -X POST "https://dev.freeplay.ai/api/v2/projects/{{project_id}}/search/completions?page=1&page_size=5" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -d '{"filters": {}}'

​
Filter Reference

​
No Filters (Empty)

{"filters": {}}

​
Cost Filters

Filter completions by their cost. Operators: eq, lt, gt, lte, gte Value type: number 
{"filters": {"field": "cost", "op": "gte", "value": 0.003}}

​
Completion Output Filters

Filter by completion output (contains) 
{"filters": {"field": "completion_output", "op": "contains", "value": "sunny and windy"}}

​
Environment Filters

Filter by environment (equals) 
{"filters": {"field": "environment", "op": "eq", "value": "staging"}}

​
Prompt Template Filters

Filter by prompt template name (equals) 
{"filters": {"field": "prompt_template", "op": "eq", "value": "other-template"}}
Filter by prompt template ID (equals) 
{"filters": {"field": "prompt_template_id", "op": "eq", "value": "YOUR_TEMPLATE_ID_HERE"}}

​
Model Filters

Filter by model (equals) 
{"filters": {"field": "model", "op": "eq", "value": "YOUR_MODEL_NAME_HERE"}}

​
Provider Filters

Filter by provider (equals) 
{"filters": {"field": "provider", "op": "eq", "value": "azure"}}

​
Review Status Filters

Filter by review status (equals) 
{"filters": {"field": "review_status", "op": "eq", "value": "review_complete"}}

​
Completion Feedback Filters

Filter by completion feedback rating (contains) 
{"filters": {"field": "completion_feedback.rating", "op": "contains", "value": "positive"}}

​
Completion Inputs Filters

Filter by completion inputs (contains) 
{"filters": {"field": "completion_inputs.topic", "op": "contains", "value": "weather"}}

​
Trace Custom Metadata Filters

Filter by trace custom metadata (contains) 
{"filters": {"field": "trace_custom_metadata.workflow", "op": "contains", "value": "onboarding"}}

​
Session Custom Metadata Filters

Filter by session custom metadata (contains) 
{"filters": {"field": "session_custom_metadata.user_type", "op": "contains", "value": "premium"}}

​
Start Time Filters

Filter by start time (greater than or equal) 
{"filters": {"field": "start_time", "op": "gte", "value": "2024-06-01 00:00:00"}}
Filter by start time (greater than) 
{"filters": {"field": "start_time", "op": "gt", "value": "2024-06-01 00:00:00"}}
Filter by start time (less than or equal) 
{"filters": {"field": "start_time", "op": "lte", "value": "2024-06-01 00:00:00"}}
Filter by start time (less than) 
{"filters": {"field": "start_time", "op": "lt", "value": "2024-06-01 00:00:00"}}
Filter by start time (equals) 
{"filters": {"field": "start_time", "op": "eq", "value": "2024-06-01 00:00:00"}}

​
Agent Filters

Filter by agent name (equals) 
{"filters": {"field": "agent_name", "op": "eq", "value": "support-agent"}}

​
API Key Filters

Filter by API key (equals) 
{"filters": {"field": "api_key", "op": "eq", "value": "production-key"}}

​
Assignee Filters

Filter by assignee (equals) 
{"filters": {"field": "assignee", "op": "eq", "value": "user@example.com"}}

​
Latency Filters

Filter by latency (greater than or equal) 
{"filters": {"field": "latency", "op": "gte", "value": 8}}
Filter by latency (greater than) 
{"filters": {"field": "latency", "op": "gt", "value": 8}}
Filter by latency (less than) 
{"filters": {"field": "latency", "op": "lt", "value": 3}}
Filter by latency (less than or equal) 
{"filters": {"field": "latency", "op": "lte", "value": 3}}
Filter by latency (equals) 
{"filters": {"field": "latency", "op": "eq", "value": 8}}

​
Evaluation Notes Filters

Filter by evaluation notes content (contains) 
{"filters": {"field": "evaluation_notes.content", "op": "contains", "value": "needs review"}}
Filter by evaluation notes author (equals) 
{"filters": {"field": "evaluation_notes.author", "op": "eq", "value": "user@example.com"}}
Filter by evaluation notes created at (greater than) 
{"filters": {"field": "evaluation_notes.created_at", "op": "gt", "value": "2024-06-01 00:00:00"}}

​
Review Theme Filters

Filter by review theme (equals) 
{"filters": {"field": "review_theme", "op": "eq", "value": "Response Quality Issues"}}

​
Trace Input/Output/Feedback Filters

Filter by trace input (contains) 
{"filters": {"field": "trace_input.query", "op": "contains", "value": "weather"}}
Filter by trace output (contains) 
{"filters": {"field": "trace_output.response", "op": "contains", "value": "sunny"}}
Filter by trace feedback (contains) 
{"filters": {"field": "trace_feedback.rating", "op": "contains", "value": "positive"}}

​
Evaluation Results Filters

Filter by completion evaluation results (equals) 
{"filters": {"field": "completion_evaluation_results.Response Quality", "op": "eq", "value": "4"}}
Filter by completion client evaluation results (equals) 
{"filters": {"field": "completion_client_evaluation_results.response_quality", "op": "eq", "value": "85"}}
Filter by trace evaluation results (equals) 
{"filters": {"field": "trace_evaluation_results.Quality Score", "op": "eq", "value": 5}}
Filter by trace evaluation results (contains) 
{"filters": {"field": "trace_evaluation_results.Is Helpful", "op": "contains", "value": "Yes"}}
Filter by trace evaluation results (greater than) 
{"filters": {"field": "trace_evaluation_results.Quality Score", "op": "gt", "value": 3}}
Filter by trace evaluation results (less than) 
{"filters": {"field": "trace_evaluation_results.Quality Score", "op": "lt", "value": 3}}
Filter by trace evaluation results (greater than or equal) 
{"filters": {"field": "trace_evaluation_results.Quality Score", "op": "gte", "value": 3}}
Filter by trace evaluation results (less than or equal) 
{"filters": {"field": "trace_evaluation_results.Quality Score", "op": "lte", "value": 3}}
Filter by trace client evaluation results (equals) 
{"filters": {"field": "trace_client_eval_results.confidence_score", "op": "eq", "value": 0.95}}
Filter by trace client evaluation results (contains) 
{"filters": {"field": "trace_client_eval_results.sentiment", "op": "contains", "value": "positive"}}

​
Trace Agent Name Filters

Filter by trace agent name (equals) 
{"filters": {"field": "trace_agent_name", "op": "eq", "value": "exact-match-agent"}}

​
Compound Filters

Combine multiple filters using and, or, and not logic operators. 
{
  "filters": {
    "and": [
      {
        "field": "cost",
        "op": "gte",
        "value": 0.0001
      },
      {
        "or": [
          {
            "field": "completion_output",
            "op": "contains",
            "value": "the"
          },
          {
            "field": "completion_output",
            "op": "contains",
            "value": "this"
          }
        ]
      },
      {
        "not": {
          "field": "environment",
          "op": "eq",
          "value": "prod"
        }
      }
    ]
  }
}