All Ears MCP — Monitor use cases
A monitor is a saved query whose matching mentions are continuously collected and enriched — sentiment, reach and PR value that a raw keyword match does not carry. Every analytics tool below runs against a saved monitor by UUID.
Entitlement: every monitor tool is available to every organization.
- The monitor CRUD/read tools (
list_monitors,get_monitor,create_monitor,update_monitor,archive_monitor,get_mentions,get_metrics) need themonitor:readscope, andmonitor:writefor create / update / archive.- The monitor analytics operators (
monitor_*) needmonitor:read.A tool returns a permission error if the token lacks the scope, or if you are a read-only user.
Example numbers below are illustrative. Tool names, arguments, and response shape are the contract; the specific values are not.
Contents
- How monitors work (read first)
- Monitor basics (CRUD/read)
- Monitor analytics operators
- Volume: how much coverage did this monitor get?
- Headline totals: one number for reach / PR value
- Unique channels: how many outlets mentioned this?
- Trend: how is it moving over time?
- Spikes: when did it blow up?
- Growth: up or down vs the previous period?
- Top channels: where does this live?
- Share of voice: how is a monitor's coverage split across channel types?
- Sentiment: how do they feel?
- Conversation terms: what are they saying around this?
- Evidence & export: show me the actual mentions
- Compare several monitors at once
How monitors work (read first)
- Creating a monitor is a background job.
create_monitorreturns immediately, but historical mentions are backfilled asynchronously and sentiment is computed by separate workers after mentions land. For large datasets this takes minutes to hours.get_monitor/create_monitor/update_monitorreturnbackfill_in_progress: true while the historical pass is still running, false once it finishes. It does not track sentiment scoring, which is a separate queue — sentiment-dependent analysis may be incomplete even afterbackfill_in_progressturns false, and might need to be revisited later — by re-querying and watching sentiment fill in fromnull. - Mentions are enriched. Each mention carries sentiment, reach and PR
value. Every analytics operator accepts the same dashboard filters:
channel_type,channel_name,medium,language,sentiment,min_reach,freetextandinsight_types(positive_impact,negative_impact,toplist_mentions). Organizations without insights have no tagged mentions, soinsight_typesreturns an empty set. - Mentions vs episodes. A monitor distinguishes distinct episodes (one
content item — a podcast episode, video, article, post) from individual
mention passages inside them (one episode can yield many). Both counts come
from
monitor_episode_count(it returnsepisode_countandmention_count), and most metrics can be measured either way. - Resolve the UUID first. When the user names a monitor, call
list_monitorsand match ontitlebefore calling any analytics operator.
Monitor basics (CRUD/read)
| Tool | What it does |
|---|---|
list_monitors |
List your monitors. Call this first to resolve a monitor's UUID. |
get_monitor |
Inspect one monitor's configured keywords/queries by UUID. |
create_monitor |
Create a new keyword monitor (kicks off the async backfill). |
update_monitor |
Edit an existing monitor's title or query blocks in place. |
archive_monitor |
Soft-delete a monitor. |
get_mentions |
Page-based enriched mention rows (interactive "show me a few"). |
get_metrics |
Aggregated daily metrics: mentions, reach, net sentiment, PR value. |
Creating a monitor — each query block needs non-empty keywords, sources
(media types; use news for online news, and the individual platforms for
social — there is no online_news or social_media value), and languages.
Pass optional start_date (YYYY-MM-DD) to set how far back the historical
backfill collects; omit it and the monitor starts from the creation date:
{
"tool": "create_monitor",
"arguments": {
"title": "Climate Change",
"start_date": "2025-01-01",
"queries": [
{"keywords": ["climate change", "global warming"],
"sources": ["podcast", "news"],
"languages": ["en"]}
]
}
}
If you belong to more than one organization, add an organization argument (an
org uuid from list_organizations) naming the org to create the monitor in —
otherwise the call returns a 400 listing your orgs. A single-org user can omit
it. The query blocks' sources / languages are validated against that org, so
pick one whose entitlements cover them. update_monitor needs no organization:
an update always stays on the monitor's existing org.
Monitor analytics operators
Each operator runs against a monitor UUID (with mode: "monitor" echoed in the
response) and accepts the dashboard filters (channel_type, channel_name,
medium, language, sentiment, min_reach, freetext, insight_types) plus an optional
start_date / end_date window.
| Operator | Use case | Metrics / extras |
|---|---|---|
monitor_episode_count |
Volume (episodes and per-passage mentions) | returns both episode_count and mention_count |
monitor_totals |
Headline number | metric: "reach" / "pr_value" / "episode_count" / "mention_count" |
monitor_channel_count |
Unique channels | distinct channel count |
monitor_time_series |
Trend | metric: "episode_count" / "mention_count" / "reach" / "pr_value" / "sentiment"; split_by: "channel_type" |
monitor_detect_peaks |
Spikes | metric: "episode_count" / "mention_count" / "reach" / "pr_value" |
monitor_growth_rate |
Growth | metric: "episode_count" / "mention_count" / "reach" / "pr_value" / "sentiment" |
monitor_top_sources |
Top channels | metric: "episodes" / "mentions" / "reach" / "pr_value"; details: true adds episode_count + sentiment per channel |
monitor_distribution |
Share of voice by channel type | metric: "episode_count" / "mention_count" / "reach" / "pr_value" |
monitor_sentiment_distribution |
Sentiment | counts, shares, net sentiment |
monitor_top_terms |
Conversation terms | scored vs general language |
monitor_get_mentions |
Evidence / full export | enriched rows (each with reach_at_creation + pr_value), cursor-paginated |
Medium. The medium filter narrows to audio (transcribed speech in
podcasts, video and broadcast) or text (episode titles & descriptions, online
news articles, social posts). The default all covers both — you do not
need to run a tool twice to get the whole monitor.
Reach & PR value. Every operator above that takes a metric also accepts
reach (summed audience of the distinct matched episodes) and pr_value
(advertising-equivalent value derived from that reach), plus the headline
monitor_totals. pr_value is returned as null (not 0) when your plan
doesn't include PR value or no matched episode falls in a PR-value-enabled
market — show the user "—" rather than a misleading zero. Pass an optional
currency to select the PR-value currency — one of "SEK" (base, default),
"USD", "EUR" or "NOK" (the tool schema lists exactly these, so don't
invent other codes).
Window date basis. Every analytic windows on the mention's
published_date (when the content was published) — the same basis as the
dashboard, so the numbers are comparable across tools. The one exception is
monitor_get_mentions, the export/streaming primitive, which takes an optional
date_filter_field and defaults to "created" (when the monitor detected
the mention) — the right basis for incremental export ("give me everything
ingested since my last sync"), which also catches back-catalogue episodes
published long before they were found. Pass "published_date" when you instead
want the list to reconcile with the analytics. The aggregation tools
intentionally don't offer this switch.
Volume: how much coverage did this monitor get?
- Question: How many episodes and how many mention passages did the monitor collect in a window?
- Who: Analyst / comms / agent sizing a tracked topic.
- Tool:
monitor_episode_count.
Example call
{
"tool": "monitor_episode_count",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"start_date": "2026-05-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "episode_count",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"episode_count": 412,
"mention_count": 988,
"start_date": "2026-05-01T00:00:00",
"end_date": "2026-05-31T00:00:00"
}
- A good answer: both numbers, labelled —
episode_countis distinct content items,mention_countis passages inside them (one episode can contribute many). Say which one you are quoting. - Limitations: counts only what the monitor's query matched; a keyword the
monitor doesn't track is invisible here (edit it with
update_monitor). - Won't tell you: how it moved over time (Trend), who said it, or the audience behind it (Headline totals).
Headline totals: one number for reach / PR value
- Question: What's the total reach or PR value of a monitor's coverage in a window (the big number above the graph)? How many episodes or mentions in all?
- Who: Comms / analyst / agent reporting headline impact.
- Tool:
monitor_totals. Pick onemetric:reach,pr_value,episode_countormention_count. For the same number over time, usemonitor_time_serieswith the matching metric.
Example call
{
"tool": "monitor_totals",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"metric": "pr_value",
"currency": "USD",
"start_date": "2026-05-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "totals",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"metric": "pr_value",
"value": 128400,
"start_date": "2026-05-01T00:00:00",
"end_date": "2026-05-31T00:00:00"
}
- A good answer: the single
valuefor the requestedmetric, stated with its window (and currency forpr_value). Reach is summed once per distinct episode, so an episode mentioned many times counts its audience once. - Limitations:
valueisnullformetric: "pr_value"when your plan lacks PR value or no matched episode is in a PR-value-enabled market — render "—", not0. - Won't tell you: the breakdown behind the number — use
monitor_top_sources(by channel) ormonitor_distribution(by channel type) for that, ormonitor_time_seriesfor the trend.
Unique channels: how many outlets mentioned this?
- Question: How many distinct shows / outlets / channels have mentions on this monitor in a window?
- Who: Comms / analyst / agent reporting breadth of coverage.
- Tool:
monitor_channel_count. Returnschannel_count: unique channel ids with at least one matching mention (irrelevant mentions are excluded). For which channels, usemonitor_top_sources; for episode / mention volume usemonitor_episode_count.
Example call
{
"tool": "monitor_channel_count",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"start_date": "2026-05-01",
"end_date": "2026-05-31",
"channel_type": ["podcast"]
}
}
Example response
{
"operator": "channel_count",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"channel_count": 47,
"start_date": "2026-05-01T00:00:00",
"end_date": "2026-05-31T00:00:00"
}
- A good answer: the single
channel_countfor the requested window (and filters). Several mentions on the same show still count as one channel. - Limitations: same dashboard filters as the other monitor analytics
(
channel_type,channel_name,medium,language,sentiment,min_reach,freetext,insight_types). - Won't tell you: the ranked list of those channels — use
monitor_top_sourcesfor that.
Trend: how is it moving over time?
- Question: What does the volume (or reach / PR value / sentiment) curve look like over a window?
- Who: Comms / analyst / agent building a trend line.
- Tool:
monitor_time_series.granularityishour,day(default),weekormonth.
Example call
{
"tool": "monitor_time_series",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"metric": "episode_count",
"granularity": "week",
"start_date": "2026-01-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "time_series",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"granularity": "week",
"metric": "episode_count",
"split_by": null,
"start_date": "2026-01-01T00:00:00",
"end_date": "2026-05-31T00:00:00",
"points": [
{"date": "2026-01-05", "value": 71},
{"date": "2026-01-12", "value": 88}
]
}
- A good answer: the bucketed series; its
pointssum to the Volume count for the same monitor/window/metric. Optionallysplit_by: "channel_type"for one series per channel type (the response then adds aserieslist of{key, points}next to the overallpoints; not available together withreach/pr_value/sentiment). - Sentiment over time:
metric: "sentiment"makes each point{date, value, positive, neutral, negative, unknown}—valueis the mean scored sentiment in −1…+1 (same scale asmonitor_sentiment_distribution.net_sentiment), the counts are mentions per label (very_positivefolds intopositive,very_negativeintonegative,unknownis not scored yet and excluded fromvalue). Empty buckets fill as0. - Limitations: the most recent bucket can be partial (ingest lag) — flag or drop it. Prefer recent windows; very old windows are less reliable.
- Won't tell you: why it moved — read the mentions (Evidence) or the Conversation terms.
Spikes: when did it blow up?
- Question: Which buckets exceeded the monitor's normal baseline?
- Who: Comms / agent investigating a surge.
- Tool:
monitor_detect_peaks.
Example call
{
"tool": "monitor_detect_peaks",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"granularity": "day",
"threshold": 2.5,
"min_value": 5,
"start_date": "2026-04-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "detect_peaks",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"metric": "episode_count",
"granularity": "day",
"threshold": 2.5,
"min_value": 5,
"period": 7,
"window": 28,
"points": [
{"date": "2026-04-01", "value": 4},
{"date": "2026-05-14", "value": 63}
],
"peaks": [
{"date": "2026-05-14", "value": 63, "score": 4.1, "expected": 7.2}
],
"baseline": {"method": "causal-seasonal-rolling", "period": 7, "window": 28},
"start_date": "2026-04-01T00:00:00",
"end_date": "2026-05-31T00:00:00"
}
- A good answer: peak buckets (already sorted largest-
scorefirst), each with the bucket value, itsscore, and theexpectedbaseline rate so the reader can judge significance.pointsequalsmonitor_time_seriesover the same window. - Limitations: daily data gets weekly seasonality by default (
period: 7), so a regular weekly cycle is not flagged. Raisemin_valueto suppress "2 instead of 1" noise. A freshly created monitor has no history to build a baseline from, so its first busy day is reported as a peak. Works onreach/pr_valuetoo, butmin_valueis then an absolute reach / PR-value floor. - Won't tell you: what caused the spike (read the mentions — see Evidence).
Growth: up or down vs the previous period?
- Question: What's the period-over-period change (WoW / MoM / YoY)?
- Who: Analyst / agent producing a headline delta.
- Tool:
monitor_growth_rate.
Example call
{
"tool": "monitor_growth_rate",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"metric": "episode_count",
"start_date": "2026-05-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "growth_rate",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"metric": "episode_count",
"value": 412,
"previous_value": 350,
"delta": 62,
"change_pct": 17.7,
"start_date": "2026-05-01T00:00:00",
"end_date": "2026-05-31T00:00:00",
"compare_start_date": "2026-03-31T00:00:00",
"compare_end_date": "2026-04-30T00:00:00"
}
- A good answer: current vs previous with the delta and percent. The default
comparison window is the immediately preceding window of equal length
(override with
compare_start_date/compare_end_date, passed together). - Sentiment growth:
metric: "sentiment"returns the mean scored sentiment in −1…+1 per window (nullwhen a window has no scored mentions);change_pctis then movement as a percent of that −1…+1 range, not a ratio of the prior mean. The same response also carriespositive/neutral/negativemention-count deltas, each{value, previous_value, delta, change_pct}(very_positivefolds intopositive,very_negativeintonegative; a bucket'schange_pctisnullwhen its previous count is 0). - Limitations:
change_pctisnullwhen the previous window was 0. - Won't tell you: what drove the change.
Top channels: where does this live?
- Question: Which shows/feeds/outlets carry the most coverage on a monitor?
- Who: Comms / analyst / agent mapping where to listen or pitch.
- Tool:
monitor_top_sources.
Example call
{
"tool": "monitor_top_sources",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"metric": "episodes",
"size": 10,
"details": true,
"start_date": "2026-05-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "top_sources",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"size": 10,
"metric": "episodes",
"sources": [
{"channel_id": 3141, "channel_name": "The EV Show", "channel_type": "podcast",
"channel_artwork_url": "https://...", "value": 28,
"episode_count": 28,
"sentiment": {"very_positive": 2, "positive": 11, "neutral": 20,
"negative": 6, "very_negative": 0, "unknown": 1}},
{"channel_id": 9020, "channel_name": "Auto Weekly", "channel_type": "youtube",
"channel_artwork_url": null, "value": 19,
"episode_count": 19,
"sentiment": {"very_positive": 0, "positive": 7, "neutral": 15,
"negative": 3, "very_negative": 1, "unknown": 0}}
],
"start_date": "2026-05-01T00:00:00",
"end_date": "2026-05-31T00:00:00"
}
- A good answer: a ranked, human-readable channel list (names + types, not
opaque ids), each with its
valuein the requestedmetric— distinct episodes (episodes, default), passages (mentions), summed audience (reach) or summed PR value (pr_value;reach/pr_valuecount each episode once). Withdetails: trueevery row also carriesepisode_countand asentimentsplit (same six labels asmonitor_sentiment_distribution). - Limitations: ranks channels, not individual people (hosts, guests, creators).
- Won't tell you: which host/guest is talking.
Share of voice: how is a monitor's coverage split across channel types?
- Question: What share of a monitor's coverage is podcast vs YouTube vs TV vs radio vs news?
- Who: Comms / analyst / agent profiling where a tracked topic lives.
- Tool:
monitor_distribution.
Example call
{
"tool": "monitor_distribution",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"dimension": "channel_type",
"metric": "episode_count",
"start_date": "2026-05-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "distribution",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"dimension": "channel_type",
"metric": "episode_count",
"counts": {"podcast": 240, "youtube": 96, "tv": 41, "radio": 23, "news": 12},
"shares": {"podcast": 0.581, "youtube": 0.233, "tv": 0.099, "radio": 0.056, "news": 0.031},
"total": 412,
"start_date": "2026-05-01T00:00:00",
"end_date": "2026-05-31T00:00:00"
}
- A good answer: per-channel-type
counts+shares(sum ~1) +total. Thetotalequals the Volume count for the same monitor/window/metric — this is one monitor's volume split by channel type. Split bymetric: "mention_count"(per-passage),"reach"or"pr_value"as well as the defaultepisode_count. - Limitations:
channel_typeis the only dimension. This is share of voice by channel type for one monitor, not cross-monitor/brand share of voice — for that, run it per monitor (or use the multi-monitor compare, below) and combine client-side. - Won't tell you: how several monitors split a shared market in one call;
sentiment per channel type. For sentiment per channel, call
monitor_top_sourceswithdetails: true.
Sentiment: how do they feel?
- Question: What's the positive/negative/neutral split and net sentiment?
- Who: Comms / analyst / agent reporting tone.
- Tool:
monitor_sentiment_distribution. Requires a saved monitor; if none exists, create one (create_monitor) and warn that sentiment backfills asynchronously.
Example call
{
"tool": "monitor_sentiment_distribution",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"start_date": "2026-05-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "sentiment_distribution",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"counts": {
"very_positive": 12, "positive": 88, "neutral": 140,
"negative": 53, "very_negative": 9, "unknown": 21
},
"shares": {
"very_positive": 0.04, "positive": 0.29, "neutral": 0.46,
"negative": 0.18, "very_negative": 0.03, "unknown": null
},
"scored": 302,
"total": 323,
"net_sentiment": 0.11,
"start_date": "2026-05-01T00:00:00",
"end_date": "2026-05-31T00:00:00"
}
- A good answer: counts + shares (shares exclude
unknownfrom the denominator) + net sentiment in −1…+1. State how many werescoredvstotal. - Limitations: on a freshly created monitor, sentiment is
unknownuntil backfill finishes. For net sentiment over time usemonitor_time_serieswithmetric: "sentiment"; for the period-over-period change usemonitor_growth_ratewithmetric: "sentiment"(both described under Trend and Growth above). - Won't tell you: discrete emotions (joy/anger/…), or why the sentiment is
what it is. Sentiment per channel is on
monitor_top_sourceswithdetails: true.
Conversation terms: what are they saying around this?
- Question: Which terms are statistically over-represented in the monitor's mentions?
- Who: Analyst / journalist / agent wanting the shape of the conversation (word cloud).
- Tool:
monitor_top_terms.
Example call
{
"tool": "monitor_top_terms",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"size": 25,
"start_date": "2026-05-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "top_terms",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"size": 25,
"terms": [
{"term": "rate cut", "doc_count": 140, "score": 0.81, "bg_count": null},
{"term": "inflation", "doc_count": 95, "score": 0.64, "bg_count": null}
],
"start_date": "2026-05-01T00:00:00",
"end_date": "2026-05-31T00:00:00"
}
- A good answer: terms over-represented versus everyday language (not
generic stopwords, not the monitor's own keywords), ranked by
score(significance).doc_countis how many distinct mentions contained the term — a frequency, not the ranking key.bg_countis alwaysnullon a monitor (the baseline is a general-language model, not a countable corpus). - Limitations: these are lexical co-occurring terms, not semantic topics or named entities. A low-volume monitor legitimately returns few terms — significance can't be established from a handful of mentions.
- Won't tell you: topic clusters, entities, or meaning-based grouping.
Evidence & export: show me the actual mentions
- Question: What are the real passages behind the numbers? / Give me every mention since my last sync.
- Who: Journalist / agent needing quotes; integrations exporting a monitor's dataset.
- Tool:
monitor_get_mentions(cursor-paginated). For an interactive "show me a few", the page-basedget_mentions(withpage/page_size) is also fine.
Example call
{
"tool": "monitor_get_mentions",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"page_size": 50,
"include_related": true,
"date_filter_field": "published_date",
"start_date": "2026-05-10",
"end_date": "2026-05-17"
}
}
Example response
{
"operator": "get_mentions",
"mode": "monitor",
"monitor_uuid": "8f3c0a21-...-e21",
"results": [
{
"uuid": "1c9d3e70-...-4a2",
"text": "...we switched to our brand last year and never looked back...",
"context": "...the whole segment on rebranding...",
"timing": 1843,
"language": "en",
"url_with_timing": "https://allears.ai/...#t=1843",
"reach_at_creation": 18400,
"pr_value": 2100,
"created": "2026-05-12T09:14:03",
"episode": {"uuid": "e7b1...", "title": "Rebranding in 2026",
"published_date": "2026-05-12T06:00:00"},
"channel": {"uuid": "c0a4...", "name": "Marketing Today", "channel_type": "podcast"}
}
],
"next_cursor": "eyJ0cyI6...",
"has_more": true
}
- A good answer: the matched
textwith itschannel/episodecontext and a link (url_with_timing). Useinclude_related: falseto drop theepisode/channel/transcriptsub-objects (andpr_value) for a smaller payload. - Paging: omit
afteron the first call. Takenext_cursorfrom the response and pass it as theafterargument of the next call; stop whenhas_moreis false.next_cursoris a response field, not an argument — the tool has nonext_cursororcursorparameter. For the example above the second page is:
{
"tool": "monitor_get_mentions",
"arguments": {
"uuid": "8f3c0a21-...-e21",
"after": "eyJ0cyI6...",
"page_size": 50,
"include_related": true,
"date_filter_field": "published_date",
"start_date": "2026-05-10",
"end_date": "2026-05-17"
}
}
- Streaming a monitor incrementally: leave
date_filter_fieldat its default ("created", the detection date), setstart_dateto your last watermark (leaveend_dateunset → now), page withafteras above untilhas_moreis false, then store the newest row'screatedas the next watermark. This reliably picks up everything ingested since your last run, regardless of when the content was originally published. - Limitations:
pr_valueisnullwhen unavailable for your plan / market. Rows carry reach and PR value but not a per-mention sentiment label — for that, use the page-basedget_mentions, or aggregate withmonitor_sentiment_distribution. - Won't tell you: a summary or explanation — the tool returns the passages; reading them is the agent's job.
Compare several monitors at once
- Question: Same metric across N saved monitors (e.g. us vs 5 competitors).
- Who: Analyst benchmarking saved trackers.
- Tool: any
monitor_*analytics operator exceptmonitor_get_mentions, with a comma-separated UUID list (max 20). The response switches to aresultslist, one row per monitor.
Example call
{
"tool": "monitor_episode_count",
"arguments": {
"uuid": "8f3c0a21-...-e21,a0127f3b-...-77b,c4d90011-...-100",
"start_date": "2026-05-01",
"end_date": "2026-05-31"
}
}
Example response
{
"operator": "episode_count",
"mode": "monitor",
"results": [
{"monitor_uuid": "8f3c0a21-...-e21", "episode_count": 412, "mention_count": 988,
"start_date": "2026-05-01T00:00:00", "end_date": "2026-05-31T00:00:00"},
{"monitor_uuid": "a0127f3b-...-77b", "episode_count": 220, "mention_count": 471,
"start_date": "2026-05-01T00:00:00", "end_date": "2026-05-31T00:00:00"}
]
}
- A good answer: one row per monitor, same window, ready to rank.
- Limitations: capped at 20 monitors per call. With a single UUID the
per-monitor fields are returned flattened at the top level instead of inside
results. Each monitor must already exist — to compare topics nobody tracks yet, create the monitors first and wait for the backfill (get_monitor'sbackfill_in_progressturns false when it's done). - Won't tell you: a cross-monitor share — divide the rows client-side if you need "us vs the market".