Filters

Filters select a subset of mentions.

This page lists every available filter and the shape of its values. For an introduction on how to use filters and combine them into full filtersets, see the Filtering guide.

Filter object#

Each filter is an object with the following fields:

Field Required Default Description
values yes Values to match. The type (list, string, or object) depends on the filter, see below.
operator no must How the filter is applied within the filter set: must, must_not, or should.
strict no false For list filters: false matches any value (logical OR), true matches all values (logical AND).

The values field is always plural, even for types that contain a single value such as a string or object. For example:

  • "synql": {"values": "this OR that"}, not "value": "this OR that"
  • "interactions_total": {"values": {"gte": 1000}}, not "value": {"gte": 1000}.

Value formats#

Type names below match the Type column in the catalog.

Type values shape Used by
List ["eng", "fra"] Most filters (language, sentiment, hashtag, …)
Query string "chocolate OR cacao" synql
Date range {"gte": "...", "lt": "..."} date
Numeric range {"from": 0, "to": 1000} follower_count, ratings
Numeric bounds {"gte": 10, "lt": 100} interactions_total, interactions_total_active
Origin {"site": ["..."], "source": ["..."], "author": ["..."]} origin

For filters where values is a list, always send it as an array, even if it contains only one element. For example: "language": {"values": ["eng"]}, not "values": "eng".

At least one bound is required for date and numeric-bound filters. Do not set both gt and gte (or both lt and lte) on the same range.

Bound Meaning
gte Greater than or equal (inclusive)
gt Greater than (exclusive)
lte Less than or equal (inclusive)
lt Less than (exclusive)

Date bounds accept ISO-8601 timestamps or Elasticsearch date math (now-30d).

Catalog#

Unknown filter names are rejected (HTTP 400). Open Example on a row for a filters snippet.

Content

Filter Type Accepted values Description Example
synql Query string SynQL (OR, AND, NOT, quotes) Full-text query on title and content {"synql": {"values": "\"ice cream\" OR gelato"}}
hashtag List Exact string, without # Hashtags {"hashtag": {"values": ["pizza"]}}
mention List Exact string @-mentions {"mention": {"values": ["ipsos"]}}
url List URLs Mention URLs {"url": {"values": ["https://example.com/p/1"]}}
token List Exact string Tokens in the text {"token": {"values": ["chocolate"]}}
emoji List Emoji Emojis in the mention {"emoji": {"values": ["🍕"]}}
media_type List Exact string Site type {"media_type": {"values": ["forum"]}}
attachment List Exact string Attachment types {"attachment": {"values": ["image"]}}
named_entity List Exact string Named entities {"named_entity": {"values": ["Ipsos"]}}
named_entity_category List Exact string Named-entity categories {"named_entity_category": {"values": ["ORG"]}}
part_of_speech List Exact string Parts of speech {"part_of_speech": {"values": ["ice cream"]}}
part_of_speech_category List Exact string Part-of-speech categories {"part_of_speech_category": {"values": ["NOUN"]}}
part_of_speech_meta_category List Exact string Part-of-speech meta-categories {"part_of_speech_meta_category": {"values": ["ENTITY"]}}
scene List Exact string Visual scenes in attachments {"scene": {"values": ["indoor"]}}

People and location

Filter Type Accepted values Description Example
language List ISO 639-3 (eng, fra, …) Mention language {"language": {"values": ["eng", "fra"]}}
country List ISO 3166-1 alpha-3 Mention country {"country": {"values": ["USA"]}}
city List Exact string Author city {"city": {"values": ["Paris"]}}
state List Exact string Author state {"state": {"values": ["California"]}}
author List Author IDs Authors {"author": {"values": ["123456789"]}}
author_bio List Exact string Tokens in the author biography {"author_bio": {"values": ["journalist"]}}
gender List male, female, unknown Inferred from the author name / bio {"gender": {"values": ["female"]}}
age List Exact string Age bucket inferred from the bio {"age": {"values": ["18-29years"]}}
job List Exact string Job field inferred from the bio {"job": {"values": ["Tech jobs"]}}
family_status List Children, unknown Inferred from the author bio {"family_status": {"values": ["Children"]}}
marital_status List Single, Couple, unknown Inferred from the author bio {"marital_status": {"values": ["Couple"]}}
follower_count Numeric range from / to Follower count {"follower_count": {"values": {"from": 0, "to": 1000}}}
affinities List Exact string Interests inferred from the bio {"affinities": {"values": ["Sports"]}}
brand List Exact string Brands detected in attachments {"brand": {"values": ["acme"]}}

Source

Filter Type Accepted values Description Example
site List Site IDs from mention site.id Social network or publisher {"site": {"values": ["1650630"]}}
source List Source IDs Sources {"source": {"values": ["456"]}}
channel List Exact string Channel {"channel": {"values": ["owned"]}}
origin Origin site, source, and author lists Combined origin {"origin": {"values": {"site": ["1650630"], "source": ["456"], "author": ["123"]}}}
publisher_category List Exact string Publisher category {"publisher_category": {"values": ["news"]}}
publisher_list List Setup IDs Publisher lists on the project {"publisher_list": {"values": ["bnp97h0a95b99en9vdr0"]}}
private_source List Source IDs Private sources {"private_source": {"values": ["456"]}}
license List Exact string License {"license": {"values": ["editorial"]}}
social_vs_mainstream List Exact string Social vs mainstream {"social_vs_mainstream": {"values": ["social"]}}
twitter_type List Exact string X / Twitter post type {"twitter_type": {"values": ["tweet"]}}
type List Exact string Mention type {"type": {"values": ["post"]}}
mention_type List Exact string Mention type {"mention_type": {"values": ["comment"]}}

Time

Filter Type Accepted values Description Example
date Date range ISO-8601 or date math (now-30d) Publication date {"date": {"values": {"gte": "now-30d"}}}
date_list List Date values Publication dates as a list {"date_list": {"values": ["2026-01-01T00:00:00Z"]}}
weekday List Exact string Weekday of publication {"weekday": {"values": ["monday"]}}

Identity

Filter Type Accepted values Description Example
id List Mention IDs Mention IDs {"id": {"values": ["bnp97h0a95b99en9vdr0"]}}
parent_id List Mention IDs Direct parent in a thread (the post or comment being replied to) {"parent_id": {"values": ["bnp97h0a95b99en9vdr0"]}}
root_id List Mention IDs Top-level mention of the thread {"root_id": {"values": ["bnp97h0a95b99en9vdr0"]}}

Sentiment and scoring

Filter Type Accepted values Description Example
sentiment List positive, negative, neutral, unassigned Mention sentiment {"sentiment": {"values": ["positive"]}}
emotion List joy, sadness, anger, fear, surprise, disgust, neutral, unassigned Mention emotion {"emotion": {"values": ["joy"]}}
ratings Numeric range from / to Normalized ratings {"ratings": {"values": {"from": 0, "to": 5}}}
interactions_total Numeric bounds gte / gt / lte / lt Total interactions {"interactions_total": {"values": {"gte": 10}}}
interactions_total_active Numeric bounds gte / gt / lte / lt Active interactions {"interactions_total_active": {"values": {"gte": 10}}}
noise_reducer List Exact string Noise-reducer scores {"noise_reducer": {"values": ["spam"]}}
review_status List unreviewed, reviewed, deleted Human review status {"review_status": {"values": ["reviewed"]}}

Project setup

These keys are resolved against the current project.

Filter Type Accepted values Description Example
topic List Topic IDs from GET /projects/{project_id}/setup/social/topics First-level topics {"topic": {"values": ["bnp97h0a95b99en9vdr0"]}}
subtopic List Topic IDs from the same setup endpoint Children of a topic {"subtopic": {"values": ["bnp97h0a95b99en9vdr0"]}}
subtopic_grouped List Exact string Grouped subtopics {"subtopic_grouped": {"values": ["pizza"]}}
collections List Classifier IDs from GET /projects/{project_id}/setup/classifiers Classifiers {"collections": {"values": ["c1a2b3d4e5f6g7h8i9j0"]}}
collection_tags List Tag IDs from the same setup endpoint Classifier tags {"collection_tags": {"values": ["c1a2b3d4e5f6g7h8i9j0"]}}
topic_modeling List Exact string Topic-modeling clusters {"topic_modeling": {"values": ["cluster-1"]}}
topic_modeling_groups List Exact string Topic-modeling groups {"topic_modeling_groups": {"values": ["group-1"]}}
fragment_sentiment List positive, negative, neutral, unassigned Fragment sentiment. Requires fragments. {"fragment_sentiment": {"values": ["positive"]}}
fragment_emotion List joy, sadness, anger, fear, surprise, disgust, neutral, unassigned Fragment emotion. Requires fragments. {"fragment_emotion": {"values": ["joy"]}}
fragment_collections List Classifier IDs Fragment classifiers. Requires fragments. {"fragment_collections": {"values": ["c1a2b3d4e5f6g7h8i9j0"]}}
fragment_collection_tags List Tag IDs Fragment classifier tags. Requires fragments. {"fragment_collection_tags": {"values": ["c1a2b3d4e5f6g7h8i9j0"]}}

Surveys, search data, and reviews

Filter Type Accepted values Description Example
document_kind List clipping, survey, multiwave_survey, search_data Document kind. Defaults to clipping. Operator must be must. {"document_kind": {"values": ["survey"]}}
search_topic_ids List Search topic IDs Search topics {"search_topic_ids": {"values": ["123"]}}
search_term List Exact string Search query stored on the mention {"search_term": {"values": ["ice cream"]}}
search_term_english List Exact string Search query in English {"search_term_english": {"values": ["ice cream"]}}
related_search List Exact string Related search stored on the mention {"related_search": {"values": ["gelato"]}}
related_search_english List Exact string Related search in English {"related_search_english": {"values": ["gelato"]}}
search_data_platform List Exact string Platform stored on the mention {"search_data_platform": {"values": ["google"]}}
search_data_explore_kinds List Exact string Search-data explore kinds {"search_data_explore_kinds": {"values": ["query"]}}
search_data_export_type List Exact string Search-data export type {"search_data_export_type": {"values": ["csv"]}}
search_data_keyword List Exact string Search-data keyword {"search_data_keyword": {"values": ["pizza"]}}
search_import_id List Import IDs Search-data import {"search_import_id": {"values": ["123"]}}
snp_search_topic_ids List Search topic IDs SnP search topics {"snp_search_topic_ids": {"values": ["123"]}}
snp_product_review List Exact string SnP product reviews {"snp_product_review": {"values": ["123"]}}
report_product_review List Exact string Report product reviews {"report_product_review": {"values": ["123"]}}
survey_id List Survey IDs Surveys {"survey_id": {"values": ["123"]}}
survey_question List Question IDs Survey questions {"survey_question": {"values": ["123"]}}
survey_simple_answer List Exact string Survey answers {"survey_simple_answer": {"values": ["yes"]}}
multiwave_survey_id List Survey IDs Multiwave surveys {"multiwave_survey_id": {"values": ["123"]}}
multiwave_survey_wave_label List Exact string Multiwave survey waves {"multiwave_survey_wave_label": {"values": ["wave-1"]}}