Count mentions
mentions_statsCount mentions instead of reading them: how many, when, where, by whom and on which terms, over up to 90 days, in one call. Call it before list_mentions for any question that starts with "how many", and for questions like "how did this week compare with last week?" (one call per window, group_by ["day"]), "which Source carries the complaints?" (group_by ["source", "sentiment"]) or "which terms catch the most?" (group_by ["term"]). rows holds one count per combination and leaves out the empty ones, so a quiet day is a missing row. total counts the whole window whatever top kept, truncated says an open axis was cut, and unread says how many mentions nothing has read when sentiment, intent or relevance is an axis. A mention caught by two terms counts under each term. Dates are publication dates, and the counts are the ones the dashboard Insights shows: they include mentions a mute rule or a hide keeps out of list_mentions, which can therefore return fewer. Page list_mentions afterwards only to quote. Free — does not charge credits.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | How many authors, terms or keywords to keep, busiest first. Defaults to 10. | |
| since | No | ISO 8601 instant. Counts mentions published after it (collection date where the Source gives none). Defaults to 7 days before until. | |
| until | No | ISO 8601 instant, inclusive. Defaults to now. The window covers 90 days at most; for a longer period, count it in parts. | |
| author | No | Only mentions from these accounts — several are OR'd, so ["alice", "bob"] is both in one call. Matched exactly, as the Source writes the handle and without a leading "@": this is a filter, not a search (use q to search text). A handle the account has never seen returns an empty page, and a mention with no author never matches. | |
| intent | No | Only mentions read as one of these intents — several are OR'd, so ["purchase_intent", "comparison"] is the leads view in one call. "unread" is what nothing has classified yet. | |
| source | No | Only these Sources — several are OR'd, so ["reddit", "hackernews"] is both in one call. Absent means every Source the account polls. | |
| keyword | No | Only this keyword's mentions, by id from list_keywords, including what its searches caught before they last changed. An id that is not one of the account's keywords is an error. | |
| group_by | Yes | One or two axes to count along: ["source", "sentiment"] is one count per Source and sentiment. day and hour cannot be combined. author, term and keyword are open lists, cut at top. | |
| relevance | No | Only mentions read as this relevant to their keyword — several are OR'd, so ["high", "medium"] leaves out what matched by accident (another meaning, a handle, spam). "unread" is what nothing has read yet. | |
| sentiment | No | Only mentions read as one of these sentiments — several are OR'd, so ["negative", "question"] is "what needs an answer" in one call. "unread" is what nothing has classified yet. | |
| engagement | No | A per-Source rule, repeatable: "<source|*>:<metric><operator><number>" — ["x:likes>=100", "reddit:score>50"] is "what landed, judged by what landing means where it was posted". Metrics are likes, replies, reposts, comments, score, views, plus total for the same interaction sum engagement_min reads. Operators are >=, >, =, <, <=; the number is whole and may be negative (Reddit and Lemmy net downvotes out). A Source no rule names PASSES — ["x:likes>=100"] narrows X and leaves Hacker News alone — a named rule overrides * for its own Source, and several rules on one Source are ANDed; use source to ask for one Source. A metric that was never counted satisfies NOTHING, < included: YouTube reports no likes, RSS and AI answers report no audience, and mentions recorded before 2026-09-04 predate the field, so ["youtube:likes<10"] returns none of them rather than all of them. Send this or engagement_min, never both. | |
| engagement_min | No | Only mentions with at least this many interactions — likes, replies, reposts, comments or score, depending on the Source. Never counts views. Mentions with no counters at all (RSS, AI answers, anything recorded before 2026-09-04) are left out rather than treated as zero. Counters are captured when the item is collected and never refreshed, so a threshold reads against recent mentions. For a threshold on one metric on one Source, use engagement instead. |