> ## 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.

# 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](/developer-resources/api-reference#search-api)    |
| `POST /search/traces`      | Search traces      | [Search Traces](/developer-resources/api-reference#search-api)      |
| `POST /search/completions` | Search completions | [Search Completions](/developer-resources/api-reference#search-api) |

All endpoints support pagination via `page` and `page_size` query parameters.

```bash theme={null}
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`                                       | `"user@example.com"`        |
| `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`                                       | `"user@example.com"`        |
| `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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "filters": {
    "or": [
      {"field": "model", "op": "eq", "value": "gpt-4o"},
      {"field": "model", "op": "eq", "value": "claude-3-opus"}
    ]
  }
}
```

### Using `not`

Negates a condition:

```json theme={null}
{
  "filters": {
    "not": {"field": "environment", "op": "eq", "value": "prod"}
  }
}
```

### Combined Example

Find expensive completions using either GPT-4o or Claude 3 Opus, excluding production:

```json theme={null}
{
  "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"}
      }
    ]
  }
}
```