API & MCP — What's New ====================== Customer-facing updates to the All Ears API and MCP tools. Newest first. ## 2026-11-18 - Fixed: `PATCH /api/v1/monitor/{uuid}/` and `update_monitor` count social keywords against the plan limit when a query id is written without hyphens or in capital letters. - Changed: an MCP connection stays signed in as long as you use it at least once every 30 days. Sign in again after 30 days without use. ## 2026-11-17 - Fixed: `PATCH /api/v1/monitor/{uuid}/` no longer rejects an edit that keeps an ended monitor's `end_date`, or sets another `end_date` that is still in the past, when the account is at its monitor limit. - Changed: `POST /api/v1/monitor/`, `PATCH /api/v1/monitor/{uuid}/`, `create_monitor` and `update_monitor` reject a monitor that is over the account's monitor limit or query-block limit, including an end date of today or later on an ended monitor when the account is already at its monitor limit. - Changed: `POST /api/v1/monitor/`, `PATCH /api/v1/monitor/{uuid}/`, `create_monitor` and `update_monitor` reject a monitor whose social-media keywords together exceed the account's social keyword limit. ## 2026-11-13 - Fixed: an MCP connection no longer shows the keyword search tools (`search_episode_count`, `search_time_series`, `search_top_terms`, `search_top_sources`, `search_distribution`, `search_growth_rate`, `search_detect_peaks`, `search_get_mentions`) for an account that does not have Search or Live Search. A connection made before this change keeps those tools until you connect again. ## 2026-11-04 - Added: a monitor now reports `backfill_in_progress`, so you can tell when its historical data has finished loading. - Changed: TikTok mentions from the monitor mentions list, search, `stream/mentions`, `get_mentions` and `monitor_get_mentions` no longer include episode artwork, while every other source still does. ## 2026-10-29 - Fixed: a `channel_name` filter matches an outlet whose name contains a comma. Wrap that name in double quotes on the API. MCP tools take the name as one list item. ## 2026-10-07 - Added: monitor tools, including `monitor_get_mentions`, `monitor_episode_count`, `get_mentions` and `get_metrics`, accept an `insight_types` filter (`positive_impact`, `negative_impact` or `toplist_mentions`). ## 2026-10-06 - Changed: a keyword search that finds few related terms explains that only terms which stand out from the rest of the index are returned. - Fixed: keyword-search source lists and mention rows include the channel id, so two feeds with the same name stay separate. - Fixed: daily metrics include every date in the requested window. A day with no mentions is zeros. - Fixed: spike detection no longer treats an ordinary weekday as a spike when that day was counted twice at the start of the window. - Fixed: keyword-search charts count a calendar day in local time. A search that starts on a date no longer picks up the previous day's evening. - Changed: the monitor analytics tools are no longer marked as a preview. - Changed: each tool now says whether it only reads data, creates a monitor, or changes an existing one. - Changed: the documentation covers monitors and links to https://mcp.allears.ai/docs with full URLs. - Fixed: looking up a monitor that does not exist, or one that has been archived, now says so in English. `update_monitor` says that each query needs the id from `get_monitor`. - Changed: `list_monitors` returns one page of monitor summaries. Pass `page` and `page_size` for the next page, and `get_monitor` for a monitor's full query. `monitor_get_mentions` and `search_get_mentions` return at most 100 mentions per page, without episode and channel details unless `include_related` is true. - Changed: the MCP reference describes what each tool returns. Sentiment on a new monitor stays unknown until scoring finishes. ## 2026-10-02 - Fixed: archiving a monitor (`archive_monitor`, or DELETE on the monitor) now stops it from continuing to add historical mentions. ## 2026-10-01 - Changed: `create_monitor` and `update_monitor` now allow the same number of keywords per query as the web app. A plan with no web app keyword cap has no cap on these tools either. ## 2026-09-30 - Changed: every organization can now use the monitor tools over MCP (`list_monitors`, `get_monitor`, `create_monitor`, `update_monitor`, `archive_monitor`, `get_mentions`, `get_metrics`); no separate API product is needed, and the `monitor:write` permission is offered to everyone at sign-in. - Changed: the descriptions of `list_organizations`, `monitor_top_terms` and `monitor_sentiment_distribution` no longer refer to an ad-hoc search. `list_organizations` still returns `has_search`; ignore it. - Changed: an assistant connected to the All Ears MCP is now guided to answer with your monitors (`list_monitors`, `create_monitor`, and the `monitor_*` tools) rather than being offered a separate ad-hoc search. - Changed: the MCP docs at `mcp.allears.ai/docs` now cover the Monitor tools only, and `/docs/monitors` has a worked example for every `monitor_*` tool (volume, trend, spikes, growth, top channels, share of voice, sentiment, terms, export). `get_documentation` accepts `auto`, `overview` or `monitors`. ## 2026-09-29 - Added: sentiment over time from `monitor_time_series` now also reports how many mentions are not scored yet, as an `unknown` count per period. ## 2026-09-25 - Added: `create_monitor` accepts `start_date` so you can set how far back the monitor collects historical mentions. - Fixed: a date-only `compare_end_date` on `monitor_growth_rate` and `search_growth_rate` now includes that full day, the same as `end_date`. ## 2026-09-23 - Changed: the `monitor_*` analytics operators are available to every organization. Creating and editing monitors still needs Monitor API access. ## 2026-09-17 - Fixed: `monitor_time_series` with `metric=sentiment` and `granularity=hour` now keeps each hour's positive, neutral, and negative counts with that hour. - Added: `monitor_time_series` accepts `metric=sentiment` for mean sentiment over time, with positive, neutral, and negative mention counts per day. ## 2026-09-16 - Added: `monitor_channel_count` returns how many unique channels have mentions on a monitor, using the same filters as the other monitor analytics tools. ## 2026-09-15 - Added: `monitor_growth_rate` with `metric=sentiment` now also returns how many mentions were positive, neutral, and negative in each window, with percent change per bucket. - Fixed: `monitor_growth_rate` with `metric=sentiment` now reports `change_pct` as movement on the −1…+1 scale, so a prior mean of 0 or a negative mean no longer hides or reverses the direction. ## 2026-09-11 - Added: `monitor_top_sources` can return the number of episodes and the sentiment split for each channel in the same answer — pass `details`. ## 2026-09-14 - Added: `monitor_growth_rate` accepts `metric=sentiment` for period-over-period mean sentiment of scored mentions. ## 2026-09-10 - Fixed: ChatGPT can reconnect to All Ears when its saved OAuth client registration is no longer available. ## 2026-09-03 - Fixed: `monitor_top_sources` now returns `channel_artwork_url` for news and social sources, which previously came back empty even when the matching mentions showed an image. ## 2026-08-11 - Fixed: live `search_episode_count` (and the other live count/trend tools) now include news articles and social posts when you pass `medium: "text"`. Previously a text count could return 0 even though `search_get_mentions` showed matching Facebook/news hits for the same query and window. ## 2026-07-16 - Added: `list_organizations` lists every organization your account can access, with each org's uuid, name, and which sources, languages, and products (live search / monitors) it supports — so agents can pick the right org before searching or creating a monitor. - Added: live search tools (`search_episode_count`, `search_time_series`, `search_distribution`, `search_top_terms`, `search_get_mentions`, `search_growth_rate`, `search_top_sources`, `search_detect_peaks`) and `create_monitor` accept an optional `organization` uuid. Results echo which org was used. If your account has more than one organization you must pass it; single-org accounts keep working without it. ## 2026-07-02 - Added: Reach and PR value for monitors. New `monitor_totals` tool returns a single headline number (reach, PR value, episode or mention count) for a window. `monitor_time_series` now supports `metric=reach` and `metric=pr_value` for over-time graphs, and `monitor_top_sources`, `monitor_distribution`, `monitor_growth_rate` and `monitor_detect_peaks` all accept the same reach / PR-value metrics. `monitor_get_mentions` rows now include each mention's `pr_value` alongside `reach_at_creation`. Pass an optional `currency` for PR value — one of `SEK` (default), `USD`, `EUR` or `NOK`; it returns null when PR value isn't available for your plan. (Monitor-only for now — not on the live firehose.) - Changed: the separate `monitor_mention_count` tool has been removed — use `monitor_episode_count`, which returns both `episode_count` and `mention_count` in one call (or `monitor_totals` with `metric=mention_count`). - Added: `monitor_get_mentions` now takes an optional `date_filter_field`. Because it's the export/streaming tool, its date window defaults to when the monitor *detected* each mention (`created`) — ideal for "export everything ingested since my last sync", which also catches older content found recently. Set it to `published_date` to window on when content was published instead (so the list reconciles with the analytics). All other monitor analytics always use the publish date so their numbers stay comparable. To stream a monitor incrementally: call with `start_date` = your last watermark, page on `next_cursor` until `has_more` is false, then save the newest detection time as the next watermark. ## 2026-06-30 - Added: a use-case guide for the MCP tools at `mcp.allears.ai/docs/use-cases`, showing which tool answers which question, example calls and responses, and what each answer does and doesn't mean. Split by product (Live Search and Monitors), with an agent-readable version at `/docs/use-cases.md`. This now covers `search_distribution` / `monitor_distribution` — share of voice by channel type (podcast vs YouTube vs TV …) for a query or monitor. - Improved: peak detection (`search_detect_peaks`, `monitor_detect_peaks`) now uses a deeper warm-up history, so the peaks reported near the start of your requested range are stable. Previously, peaks within roughly the first window of the range could change depending on how far back the range started; the same query now returns the same early peaks regardless of range length. ## 2026-06-29 - Changed: peak detection (`search_detect_peaks`, `monitor_detect_peaks`) is now time-series aware. It accounts for trends and recurring weekly patterns, so regular weekday cycles are no longer reported as spikes, and it adapts to the level of coverage over time. New optional `period` and `window` settings let you tune how the baseline is built. - Fixed: weekly time series and peak detection now line up exactly. For weekly views starting mid-week, the first week is labelled consistently (by its Monday) and no longer duplicated, so `detect_peaks` and `time_series` return the same buckets. - Fixed: the live search tools (`search_get_mentions`, `search_episode_count`, `search_time_series`, `search_top_terms`, `search_top_sources`, `search_distribution`, `search_growth_rate`, `search_detect_peaks`) no longer fail with an output validation error and now return results as expected. ## 2026-06-25 - Changed: tool inputs that only accept a fixed set of values (channel type, language, medium, sentiment, granularity, metric, etc.) now advertise those values directly to your assistant, so it picks a valid one instead of guessing. `create_monitor` / `update_monitor` queries are now a structured object — keywords, sources and languages are required — so a bad or incomplete query is caught immediately with a clear message instead of failing on our side. - Fixed: `search_distribution` and channel-type splits in `search_time_series` no longer error out for live searches — they now return the channel-type breakdown as expected. ## 2026-06-24 - Added: All `monitor_*` tools now accept the same filters as your dashboard — `channel_type`, `channel_name`, `medium` (audio/text/all), `language`, `sentiment`, `min_reach`, and `freetext` — so every number and chart updates to match, not just the mention list. - Changed: `search_*` tools now use the filter names `channel_type`, `language`, and `medium` (`audio`/`text`/`all`), and added `channel_name` to narrow to specific shows or outlets. If you used `sources`, `languages`, or `mention_types` before, switch to the new names. ## 2026-06-23 - Added: New `search_distribution` and `monitor_distribution` tools break results down by channel type (podcast, news, YouTube, TV, radio, social) so you can see share of voice. Live supports episode counts; monitors also support mention counts and reach. - Added: `search_time_series` and `monitor_time_series` now take a `split_by` option (`channel_type`) to break a trend line out per channel type. ## 2026-06-18 - Changed: `search_top_terms` now highlights the most distinctive words around your topic instead of just the most frequent ones, and no longer returns your own search terms, so results are more relevant. ## 2026-06-17 - Added: `search_top_sources` and `monitor_top_sources` now include channel artwork (`channel_artwork_url`) for each source. - Fixed: `search_time_series` and `monitor_time_series` now return every period in the selected range, including correct full-month buckets.