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 the monitor:read scope, and monitor:write for create / update / archive.
  • The monitor analytics operators (monitor_*) need monitor: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)

  • Creating a monitor is a background job. create_monitor returns 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_monitor return backfill_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 after backfill_in_progress turns false, and might need to be revisited later — by re-querying and watching sentiment fill in from null.
  • 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, freetext and insight_types (positive_impact, negative_impact, toplist_mentions). Organizations without insights have no tagged mentions, so insight_types returns 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 returns episode_count and mention_count), and most metrics can be measured either way.
  • Resolve the UUID first. When the user names a monitor, call list_monitors and match on title before 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_count is distinct content items, mention_count is 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 one metric: reach, pr_value, episode_count or mention_count. For the same number over time, use monitor_time_series with 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 value for the requested metric, stated with its window (and currency for pr_value). Reach is summed once per distinct episode, so an episode mentioned many times counts its audience once.
  • Limitations: value is null for metric: "pr_value" when your plan lacks PR value or no matched episode is in a PR-value-enabled market — render "—", not 0.
  • Won't tell you: the breakdown behind the number — use monitor_top_sources (by channel) or monitor_distribution (by channel type) for that, or monitor_time_series for 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. Returns channel_count: unique channel ids with at least one matching mention (irrelevant mentions are excluded). For which channels, use monitor_top_sources; for episode / mention volume use monitor_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_count for 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_sources for 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. granularity is hour, day (default), week or month.

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 points sum to the Volume count for the same monitor/window/metric. Optionally split_by: "channel_type" for one series per channel type (the response then adds a series list of {key, points} next to the overall points; not available together with reach / pr_value / sentiment).
  • Sentiment over time: metric: "sentiment" makes each point {date, value, positive, neutral, negative, unknown} — value is the mean scored sentiment in −1…+1 (same scale as monitor_sentiment_distribution.net_sentiment), the counts are mentions per label (very_positive folds into positive, very_negative into negative, unknown is not scored yet and excluded from value). Empty buckets fill as 0.
  • 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-score first), each with the bucket value, its score, and the expected baseline rate so the reader can judge significance. points equals monitor_time_series over the same window.
  • Limitations: daily data gets weekly seasonality by default (period: 7), so a regular weekly cycle is not flagged. Raise min_value to 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 on reach / pr_value too, but min_value is 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 (null when a window has no scored mentions); change_pct is then movement as a percent of that −1…+1 range, not a ratio of the prior mean. The same response also carries positive / neutral / negative mention-count deltas, each {value, previous_value, delta, change_pct} (very_positive folds into positive, very_negative into negative; a bucket's change_pct is null when its previous count is 0).
  • Limitations: change_pct is null when 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 value in the requested metric — distinct episodes (episodes, default), passages (mentions), summed audience (reach) or summed PR value (pr_value; reach / pr_value count each episode once). With details: true every row also carries episode_count and a sentiment split (same six labels as monitor_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. The total equals the Volume count for the same monitor/window/metric — this is one monitor's volume split by channel type. Split by metric: "mention_count" (per-passage), "reach" or "pr_value" as well as the default episode_count.
  • Limitations: channel_type is 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_sources with details: 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 unknown from the denominator) + net sentiment in −1…+1. State how many were scored vs total.
  • Limitations: on a freshly created monitor, sentiment is unknown until backfill finishes. For net sentiment over time use monitor_time_series with metric: "sentiment"; for the period-over-period change use monitor_growth_rate with metric: "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_sources with details: 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_count is how many distinct mentions contained the term — a frequency, not the ranking key. bg_count is always null on 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-based get_mentions (with page / 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 text with its channel / episode context and a link (url_with_timing). Use include_related: false to drop the episode / channel / transcript sub-objects (and pr_value) for a smaller payload.
  • Paging: omit after on the first call. Take next_cursor from the response and pass it as the after argument of the next call; stop when has_more is false. next_cursor is a response field, not an argument — the tool has no next_cursor or cursor parameter. 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_field at its default ("created", the detection date), set start_date to your last watermark (leave end_date unset → now), page with after as above until has_more is false, then store the newest row's created as the next watermark. This reliably picks up everything ingested since your last run, regardless of when the content was originally published.
  • Limitations: pr_value is null when unavailable for your plan / market. Rows carry reach and PR value but not a per-mention sentiment label — for that, use the page-based get_mentions, or aggregate with monitor_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 except monitor_get_mentions, with a comma-separated UUID list (max 20). The response switches to a results list, 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's backfill_in_progress turns 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".