# Query syntax (/docs/developer/query-syntax)

Choose the filter format for the surface you call. MCP uses structured filters. The web search bar and some REST fields accept filter text.

## At a glance [#at-a-glance]

| Surface | Filter input |
| --- | --- |
| Web Search | Operations DSL text in the search bar or `?f=` |
| REST action list | `fullFilter` for the complete Operations DSL |
| REST conversation search | `filter` for the Advanced Search DSL |
| REST action-list legacy fields | `filter` / `filterJson`: responded flag only |
| MCP search and analytics | Structured `filter` tree; no DSL string |
| Organization-specific fields | Discover before use |

## What you're looking at [#what-youre-looking-at]

A filter selects records. Its field vocabulary depends on the data source.
Do not copy a REST field into MCP or assume one source accepts another source's filter.

## Filter text [#filter-text]

| Pattern | Meaning |
| --- | --- |
| `field=value`, `field!=value` | Equals or not equals |
| `field>value`, `field>=value`, `field<value`, `field<=value` | Comparison |
| `field~value`, `field!~value` | Contains or does not contain |
| `field^=value`, `field$=value` | Starts with or ends with |
| `field=min..max` | Range |
| `field=v1,v2` | Any listed value |
| `expr1+expr2` | AND |
| `expr1\|expr2` | OR |
| `(expr)` | Group |

Use these patterns only where that endpoint accepts the grammar.
An X example for the REST action list is `fullFilter=src=TWITTER+kw~refund`.
Use URL encoding to preserve operators and literal text. `--data-urlencode` handles this in curl.

## Legacy action-list filters [#legacy-action-list-filters]

`GET /v0/action/list?filter=ro=true` selects responded actions.
`filter=ro=false` removes that responded restriction. The default is responded actions.
Legacy `filter` and `filterJson` do not apply platform, queue, status, or other conditions.
Use `fullFilter` for those conditions. Do not combine it with a legacy filter field.

In the full Operations DSL, `ro` means root record, not responded.
Use the declared responded field when you mean an agent response.

## Structured MCP filters [#structured-mcp-filters]

Read `sift.spec("query.search.actions")` before a new search.
Send a tree in the operation's `filter` field:

```json
{
  "filterType": "and",
  "filters": [
    { "filterType": "source", "operator": "in", "value": ["TWITTER"] },
    { "filterType": "status", "operator": "in", "value": ["OPEN"] }
  ]
}
```

Groups use `filterType` (`and` or `or`) and `filters`.
Leaves use a supported `filterType`, `operator`, and a correctly typed `value`.
For example, list comparisons use arrays; boolean comparisons use booleans.
A custom-field leaf also names its registered field.

## Dates and field discovery [#dates-and-field-discovery]

Set `dateRange` and `time.timezone` explicitly when the task depends on dates.
Use the field reference for the surface's inclusive or exclusive end-date rules.
For a custom field, call `query.search.custom_fields` through `execute`; for an unknown dimension, read `sift.spec("query.analytics.<source>")`.
Use the returned field name and operators. Read the values from the field's value list (`query.search.<list>`). Do not guess a custom field from a display label.

## Tips [#tips]

- Keep filters fixed while following a cursor.
- An invalid query fails with every problem and the closest valid values. An empty first page carries `emptyReason`.
- Check empty results before removing a filter.
- Use analytics for totals instead of counting search pages.

Read the [Record field dictionary](/docs/developer/record-fields) for `pmid`, `prid`, other short keys, and nested result fields.

## Related [#related]

<Cards>
  <Card href="/docs/developer/mcp-reference" title="MCP field reference">Source filters, dates, and empty results.</Card>
  <Card href="/docs/developer/api-reference" title="API field reference">REST query fields and pagination.</Card>
  <Card href="/docs/developer/agent-guide" title="Agent guide">Use filters in practical recipes.</Card>
</Cards>