Dimensions

Dimensions split mentions into buckets.

This page lists every accepted type. To nest dimensions and set interval, size, or include, see Using dimensions.

Object types#

Type names below match the Category column in the catalog.

type is required on every object. name is optional on Date, Terms, and Semantics.

Date

Calendar intervals on the publication date.

Field Required Default Description
interval no week Calendar interval: day, week, month, year.

Terms

Top values of a field.

Field Required Default Description
size no 10 Maximum number of buckets (the most frequent values).
include no Keep only these bucket ids.
exclude no Drop these bucket ids.
min_doc_count no 1 Hide buckets with fewer mentions than this.
missing no If set, mentions with no value go into a bucket with this id. Otherwise they are omitted.

Semantics

Like Terms, with project exclusion lists (named_entity, part_of_speech).

Field Required Default Description
size no 10 Maximum number of buckets (the most frequent values).
include no Keep only these bucket ids.
exclude no Drop these bucket ids.
min_doc_count no 1 Hide buckets with fewer mentions than this.
missing no If set, mentions with no value go into a bucket with this id. Otherwise they are omitted.
ignore_excluded_terms no false false: hide values from the project list. true: ignore that list and only apply request exclude.

Filters

A predefined set of buckets. They do not accept name, min_doc_count, or missing.

Field Required Default Description
size no 10 Maximum number of buckets.
include no Keep only these bucket ids.
exclude no Drop these bucket ids.

Exact string means the bucket id is the value as stored on the mention, not as a keyword query. A string that never appears in the data yields no bucket.

Catalog#

Unknown type values are rejected (HTTP 400). Open Example on a row for a dimensions snippet.

Content

Dimension Category Accepted values Description Example
hashtag Terms Exact string, without # Hashtags {"type": "hashtag", "include": ["pizza"]}
mention Terms Exact string @-mentions {"type": "mention", "include": ["ipsos"]}
url Terms URLs Mention URLs {"type": "url", "include": ["https://example.com/p/1"]}
token Terms Exact string Tokens in the text {"type": "token", "include": ["chocolate"]}
emoji Terms Emoji Emojis in the mention {"type": "emoji", "include": ["🍕"]}
media_type Terms Exact string Site type {"type": "media_type", "include": ["forum"]}
attachment Terms Exact string Attachment types {"type": "attachment", "include": ["image"]}
named_entity Semantics Exact string Named entities {"type": "named_entity", "include": ["Ipsos"]}
named_entity_category Filters Exact string Named-entity categories {"type": "named_entity_category", "include": ["ORG"]}
part_of_speech Semantics Exact string Parts of speech {"type": "part_of_speech", "include": ["ice cream"]}
part_of_speech_meta_category Filters Exact string Part-of-speech meta-categories {"type": "part_of_speech_meta_category", "include": ["ENTITY"]}
scene Terms Exact string Visual scenes in attachments {"type": "scene", "include": ["indoor"]}

People and location

Dimension Category Accepted values Description Example
language Terms ISO 639-3 (eng, fra, …) Mention language {"type": "language", "include": ["eng", "fra"]}
country Terms ISO 3166-1 alpha-3 Mention country {"type": "country", "include": ["USA"]}
city Terms Exact string Author city {"type": "city", "include": ["Paris"]}
state Terms Exact string Author state {"type": "state", "include": ["California"]}
author Terms Author IDs Authors {"type": "author", "include": ["123456789"]}
author_bio Terms Exact string Tokens in the author biography {"type": "author_bio", "include": ["journalist"]}
gender Terms male, female, unknown Inferred from the author name / bio {"type": "gender", "include": ["female"]}
age Terms Exact string Age bucket inferred from the bio {"type": "age", "include": ["18-29years"]}
age_range Filters <18, 18-24, 25-34, 35-44, 45-54, 55-64, 65+ Age ranges inferred from year of birth {"type": "age_range", "include": ["25-34"]}
job Terms Exact string Job field inferred from the bio {"type": "job", "include": ["Tech jobs"]}
family_status Terms Children, unknown Inferred from the author bio {"type": "family_status", "include": ["Children"]}
marital_status Terms Single, Couple, unknown Inferred from the author bio {"type": "marital_status", "include": ["Couple"]}
follower_count Terms Numeric, as stored Follower count {"type": "follower_count", "size": 10}
affinities Terms Exact string Interests inferred from the bio {"type": "affinities", "include": ["Sports"]}
brand Terms Exact string Brands detected in attachments {"type": "brand", "include": ["acme"]}

Source

Dimension Category Accepted values Description Example
site Terms Site IDs from mention site.id Social network or publisher. No list endpoint. {"type": "site", "include": ["1650630"]}
source Terms Source IDs Sources {"type": "source", "include": ["456"]}
channel Terms Exact string Channel {"type": "channel", "include": ["owned"]}
publisher_category Filters Exact string Publisher category {"type": "publisher_category", "include": ["news"]}
publisher_meta_category Filters Exact string Publisher meta-category {"type": "publisher_meta_category"}
private_source Terms Source IDs Private sources {"type": "private_source", "include": ["456"]}
license Terms Exact string License {"type": "license", "include": ["editorial"]}
social_vs_mainstream Filters Exact string Social platforms vs mainstream media {"type": "social_vs_mainstream", "include": ["social"]}
twitter_type Terms Exact string X / Twitter post type {"type": "twitter_type", "include": ["tweet"]}
type Terms Exact string Mention type {"type": "type", "include": ["post"]}
mention_type Terms Exact string Mention type {"type": "mention_type", "include": ["comment"]}

Time

Dimension Category Accepted values Description Example
date Date ISO-8601 timestamps (start of each interval) Publication date {"type": "date", "interval": "month"}
date_list Terms Date values Publication dates as a list {"type": "date_list", "include": ["2026-01-01T00:00:00Z"]}
weekday Terms Exact string Weekday of publication {"type": "weekday", "include": ["monday"]}

Identity

Dimension Category Accepted values Description Example
parent_id Terms Mention IDs Direct parent in a thread (the post or comment being replied to) {"type": "parent_id", "include": ["bnp97h0a95b99en9vdr0"]}
root_id Terms Mention IDs Top-level mention of the thread {"type": "root_id", "include": ["bnp97h0a95b99en9vdr0"]}

Sentiment and scoring

Dimension Category Accepted values Description Example
sentiment Terms positive, negative, neutral, unassigned Mention sentiment {"type": "sentiment", "include": ["positive"]}
emotion Terms joy, sadness, anger, fear, surprise, disgust, neutral, unassigned Mention emotion {"type": "emotion", "include": ["joy"]}
ratings Terms Normalized ratings, as stored Normalized ratings {"type": "ratings", "size": 10}
noise_reducer Filters Exact string Noise-reducer scores {"type": "noise_reducer", "include": ["spam"]}
review_status Terms unreviewed, reviewed, deleted Human review status {"type": "review_status", "include": ["reviewed"]}

Surveys, search data, and reviews

Dimension Category Accepted values Description Example
document_kind Terms clipping, survey, multiwave_survey, search_data Document kind. clipping is social posts, comments, and editorial articles. {"type": "document_kind", "include": ["survey"]}
report_product_review Terms Exact string Report product reviews {"type": "report_product_review", "include": ["123"]}