Filtering

Filters select a subset of mentions from a project. They are used by both Mention Search (POST /projects/{project_id}/mentions/_search) and Mention Analyze (POST /projects/{project_id}/mentions/_analyze).

This page is a guide on how to use filters. For a complete reference of all supported filter types and the format of their values, see the Filters reference.

Empty filterset#

The simplest valid filterset is the empty one:

{}

This filterset does not impose any constraints, so it matches all mentions in the project. In order to filter mentions, you need to add one or more filters.

Example#

Here is a simple filterset with three filters:

{
    "language": {
        "values": ["eng"]
    },
    "synql": {
        "values": "pizza OR pasta"
    },
    "date": {
        "values": {
            "gte": "2026-01-01T00:00:00Z",
            "lt": "2027-01-01T00:00:00Z"
        }
    }
}

This filterset selects mentions where all of the following conditions are met:

• the mention is in English
• its text contains the word "pizza" or "pasta"
• it was published in 2026

Each filter has a "values" field that specifies the values to match, the type of which (list, string or object) is dictated by the filter itself, as described in the Filters reference.

The field is always called "values" (plural) even if it contains a single value. For filters that have a list-typed "values" (as language), it should always be an array, even if it contains only one element.

Operators#

As seen above, by default all filters must match (logical AND) for a mention to be kept. It is possible to change this behavior using the operator field within each filter.

Think of must / must_not as hard rules, and should as “any of these is enough”.

A mention is kept only if all of the following conditions are met:

1. it satisfies every must filter,
2. it is not caught by any must_not filter,
3. it matches at least one of the should filters.

Example

{
    "filters": {
        "hashtag": {
            "values": ["pizza"],
            "operator": "must"
        },
        "sentiment": {
            "values": ["negative"],
            "operator": "must_not"
        },
        "country": {
            "values": ["USA"],
            "operator": "should"
        },
        "language": {
            "values": ["eng"],
            "operator": "should"
        }
    }
}

A mention matches if and only if:

• it has the "pizza" hashtag,
• AND its sentiment is NOT negative,
• AND it is either (or both):
  • in the US,
  • OR in English.

Matching several values#

On a list filter, several values are combined with OR by default ("strict": false). A mention matches if it has any of the values.

{
    "language": {"values": ["eng", "fra"]}
}

This matches mentions that are either in English or in French.

Strict matching

Use "strict": true when the mention must have every value, not just one.

{
    "collections": {
        "values": ["c1a2b3d4e5f6g7h8i9j0", "c9z8y7x6w5v4u3t2s1r0"],
        "strict": true
    }
}

A mention matches only if it has both classifiers. Without strict, one would be enough.

strict only applies to list filters, and only on mention fields that can hold several values at once (classifiers, hashtags, topics). On fields that can only hold a single value (language, sentiment...), it does not make sense.

For example, setting strict on the ["eng", "fra"] language filter above would only match mentions that are simultaneously in English and French, which is impossible since mentions have a single language. Such a filter would be guaranteed to match nothing.

Document kind filter#

document_kind is a special filter that selects the type of document to retrieve:

• clipping is the usual mention type: social posts, blog posts, news articles, etc.
• survey and multiwave_survey for survey documents.
• search_data for Search data, i.e. keyword volumes on search engines.

If you do not specify the document_kind filter, the API implicitly adds one that selects only clipping mentions for you. To query another kind, set document_kind explicitly.

This filter only accepts the must operator.

{
    "document_kind": {"values": ["survey"]}
}

Examples#

SynQL query

The synql filter expects a string values (not a list), in SynQL (Synthesio Query Language) syntax.

Use OR, AND, and NOT to combine terms. Wrap a phrase in double quotes for an exact match (note that in JSON they must be escaped with a backslash).

{
    "synql": {"values": "\"ice cream\" OR gelato"}
}

This filter is equivalent to the "Query" filter of the project's filter bar and uses the same syntax. It is a good idea to try out queries in the project's "Query" filter to benefit from syntax highlighting and validation.

Publication date

date is a range. Use ISO-8601 timestamps, or Elasticsearch date math such as now-30d.

{
    "date": {
        "values": {
            "gte": "2026-01-01T00:00:00Z",
            "lt": "2026-07-01T00:00:00Z"
        }
    }
}

Using a single bound is allowed and represents a half-open range starting or ending at the specified bound:

{
    "date": {
        "values": {
            "lt": "now-7d"
        }
    }
}

See also#

• Analytics complete example for how to include filters in an analytics request
• Filters reference for every filter key.