List mentions
list_mentionsRead everything your keywords caught, newest first, across every Source and every keyword on the account, with the sentiment, intent, relevance, bucket and agent readings you have switched on. relevance says whether a mention is really about its keyword (high, medium, low) with one sentence why. This is the tool for questions like "what did Reddit say about us this week?", "any complaints since Friday?" or "show me negative mentions I have not answered". To count (how many, per day, per Source, per sentiment, per author or term), call mentions_stats instead: one free call, where paging here would read the window a hundred rows at a time. Each mention carries matchedTerms, the keyword terms that caught it, when they were recorded: say why a mention is there rather than guessing it. Free in the default text mode — these are your own rows. mode="semantic" asks the embedding index and charges 1 credit per question, then answers the same question free for 10 minutes, paging included. Do not set it to filter by keyword: that is what q= in text mode already does, for nothing. Scoped to one keyword instead? Use get_keyword_results, which also carries each mention's bucket. Cursor-paged: pass nextCursor back unchanged.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search text, matched per mode= (default: free substring search) | |
| run | No | One kept Explore run: the run.id explore returned. Reads that run's mentions only, free, instead of running it again. since still bounds it, so widen since for an older run. | |
| kind | No | Which producer. "polling" is what your keywords catch on their own; "runs" is a kept one-off Explore run. Absent means both. | |
| mode | No | How q= is matched. "text" (the default) scans the window for the substring and is free. "semantic" asks the embedding index — it finds "this thing keeps crashing" for q="reliability complaints" — and charges. Never set it to do a keyword filter. | |
| type | No | Only this kind of event — usually narrower than you need; prefer source. | |
| limit | No | How many mentions to return, 1-100. Defaults to 25 here, a page a model can actually read. Never page to count: mentions_stats counts the whole window in one free call. | |
| since | No | ISO 8601 instant. Only mentions after it; defaults to the last 24 hours. | |
| until | No | ISO 8601 instant, inclusive. Only mentions before it. Use with since= to ask about a closed interval — a single day, or the week of a launch — instead of everything since a date. Absent means up to now. | |
| 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. | |
| cursor | No | The previous response's nextCursor, passed back unchanged, for the next page. Its absence from a response means that was the last page. | |
| 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. | |
| 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. | |
| opportunity | No | true keeps only opportunities: mentions of a topic or competitor keyword that are highly relevant to it and whose author is someone to answer (the keyword's agent step says problem_fit true, or, without that field, the intent is purchase_intent, comparison or question). Use it for "who should I answer today?". An own keyword has none. Free. | |
| 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. |