- 2026-11-13: An ecommerce report’s
shopping.productsaddsappearances: your products’ appearances in organic product cards and each maker’s, most first, counted over every product shown rather than the cappedproductsandshown_insteadlists. It is null on sections written before it was counted. - 2026-11-13: New Products reads for ecommerce brands.
GET /v1/brands/{brand_id}/productslists your products with the period’s product card figures, complete product data and revenue from AI, which is null without a Google Analytics read of purchases. Revenue from AI comes by assistant and by landing page, each page with the topics and questions whose answers cite it, and with one trend point per weekly read./products/{product_id}reads one product’s trend, engines, questions, products shown instead, facts, cited pages and work./products/sellers,/products/google-shoppingand/products/readinessread the sellers shown, your Google Shopping positions and your product pages against Google’s and OpenAI’s standards. The MCP toolget_productsreads the same. - 2026-11-13: An ecommerce brand’s work adds the
retailer_distributionkind, work to get your products sold by a seller AI shows beside other brands’ products, and a product page’s markup fix, asite_fixon a page whose fix kit returns the Product markup to paste.GET /v1/brands/{brand_id}/evidenceandlist_evidenceadd theecommercemodule, with the kindsproduct_markup,markup_input,product_page,seller_opportunityandseller_exposure. Seller exposure and a markup field the catalogue holds no value for file no work, so handle evidence kinds you do not know. - 2026-11-12: A figure trend point’s instrument
keyaddsshopping_pack_version: the version of the reading that judged an ecommerce report’s product cards, or null where the report read none. It is also a new value of a break’sparts, which only product card figures carry, so handlepartsvalues you do not know. - 2026-11-12: Page types add
product_detail, one item a shop sells, andcollection, a shop’s listing of items for sale.GET /v1/brands/{brand_id}/audit/pagesandGET /v1/scans/{scan_id}/audit/pagesaccept both aspage_typeand can return them on a page. - 2026-11-12: A report’s
bodyaddsproductsfor a brand that sells products online, and null for any other: the shopping figuresanswers_with_cards,in_product_cards,seller_ownandprice_matches, thealertsthe report saw on your products, andevidence, whether the shop’s catalogue and Google Shopping were read incomplete,partialorunavailableform. Reports issued earlier return null. - 2026-11-12: Brands and scans say what they are measured as:
modeisb2b_tech, orecommercefor a brand selling goods to shoppers.GET /v1/brandsreturns it on each brand,GET /v1/brands/{brand_id}/profileand theget_brand_profileMCP tool on the profile,GET /v1/scans/{scan_id}on the scan, and theget_shared_snapshotMCP tool on the shared Snapshot. An ecommerce brand’s profile has nocustomer_sizeorservice_area, and a change of mode is themodepart of a trend’s instrumentkey, which starts a new baseline. - 2026-11-11: Service Quick and Full audit reads include
stack, with each detected tool’s name, category and page or DNS evidence. Stack detection does not change audit scores. - 2026-11-11: Service Quick and Full audit reads include
screenshots: full-pagedesktop(1440 pixels wide) andphone(390) images of the audited URL, taken with JavaScript on and known consent banners declined, each with itsurl,widthandheight. - 2026-11-11:
POST /v1/service/quick-auditsandPOST /v1/service/auditstake an optionalurl, a full page address kept with its path and token, andpreview, which leaves the indexing checks out of a draft’s score.GET /v1/service/audits/{scan_id}returnsmetricsonce the audit completes:lcp_ms,page_weight_bytes,requests,performance_score,pages_read,ai_readable_pagesandtrackers_before_consent. - 2026-11-10: Editing a Snapshot’s profile with
POST /v1/scans/{scan_id}/profileor theedit_snapshottool no longer stops a run that is waiting:run_request.statestaysrequested, and the run starts on the profile as saved. A Snapshot writes its questions once Run is requested, so a profile nobody runs drafts none. - 2026-11-10:
share_cardsinGET /v1/shared/scans/{share_id}addspreview, the 1200 by 630 image a pasted report link shows. It appears with the other cards once a one-time Snapshot is final. The other cards stay 1200 by 1200. - 2026-11-09: Snapshot Your market figures carry
gap, an estimate of how many more searches a month would show the brand in Google’s AI summary if it were named as often as its most-named competitor, with that competitor’s range. When the brand isn’t named, the verdict now lists the competitors that are. A sentence never names a brand the report hides. See Your market. - 2026-11-09: The Snapshot Your market figures in
GET /v1/shared/scans/{share_id}carryllm_estimate, the search-like questions a month buyers ask ChatGPT, Gemini and Google AI Mode, with each engine’s ratio, andad_value, what Google Ads would charge for the clicks the top result gets across those questions and the category’s Google searches, with the share of that demand AI answers.panels.llmsshows whom those LLMs recommend, each engine weighed by its share of the questions, andsearches_by_meaninggroups the top searches that mean one thing into one row. Panels list only the report’s competitors.chatgpt_estimate,panels.openai,top_searchesanddemand.ad_value_usd/ad_value_eurstay until the report’s section reads the new fields. - 2026-11-09: The Snapshot Your market figures in
GET /v1/shared/scans/{share_id}carrycapture: what the brand holds today of the Google searches (google.clicks), the LLM questions (llms.questions) and the ad value (ad_value.usd/eur), each with itsshareof what the top spot would get. Each ofsearches_by_meaningcarriesyour_rank, the brand’s best organic position, andranks_read. The market constants move tov3, with the per-position click-through rates on pages with and without an AI answer. - 2026-11-09: In the Snapshot Your market figures, a top search whose Google AI summary names the brand shares the top spot evenly with the competitors the same summary names, in
capture.googleandcapture.ad_value. The market constants move tov5. - 2026-11-09: In the Snapshot Your market figures,
capture.googlecounts a top search whose Google AI summary names the brand as holding the top spot, ascapture.llmscounts a recommendation. Every checked AI summary is graded for who it names. Searches that name the report’s competitors leave the demand, the ad value and the top searches. The market constants move tov4. - 2026-11-09: Service audit reads include
completed_at. Website findings includepassed, true when a measured check passed and false when it failed or could not be measured. Passing Lighthouse checks say what the homepage does well. See Service audits and Website audits. - 2026-11-08: Weekly full Snapshots store Your market figures for your brand’s original market and All buyers audience, using existing research and tracked keyword checks. Market figures identify searches as
toportrackedwithsearches_kind, and keep an unknown tracked search volume asnull. - 2026-11-08: Full-access API keys and assistants run Snapshots.
POST /v1/scansand MCPstart_snapshotstart one and return its drafted profile,POST /v1/scans/{scan_id}/profileandedit_snapshotcorrect it,/runandrun_snapshotrun it on your free Snapshot or a workspace credit, and/stopandstop_snapshotcancel a waiting run.GET /v1/scans/{scan_id}andget_scanaddprofile,run_requestandpayer, and there a Snapshot never run readsstate: expiredinstead offailedwithbrief_abandoned. A write whose member cannot run work answers403 forbiddenwith no scope challenge, and MCP refusals carryresets_at. See Run Snapshots. - 2026-11-08: Snapshot profiles returned by REST and MCP now include the category, buyer and competitors drafted so far. Competitors remain read-only. Scan reads and lists add
report_url, a delivered Snapshot’s or weekly scan’s report page. Assistants are prompted to share the Snapshot page and expected run time, report live answer progress, and return the Heralded Score and report link when complete. See Run Snapshots and Connect an MCP client. - 2026-11-08: Signed-in Snapshot owners can edit, run and stop their waiting Snapshot from its profile link in another browser.
- 2026-11-08: The shared Snapshot API and
get_shared_snapshotassistant tool return the report’s stored Your market figures, with measured or estimated labels, ranges, top searches and the constants version. - 2026-11-08: Since 12 October, public leaderboards and MCP
get_leaderboardsreturn every source through position 20 and withhold all cited-page rows. Source rankings exclude brand sites by default;include_brand_sites=trueincludes them on filtered reads.GET /v1/leaderboards/hall-of-fame/sourcesand MCPget_leaderboardswithresource=sources_hall_of_famereturn source medals. See Leaderboards. - 2026-11-08: Added: Keywords, on Keywords and MCP
get_keywords, addai_overview_names_youandai_overview_names_rivals: whether the latest check’s AI Overview names you, and which of your tracked rivals it names. Both arenullwhere the page shows no AI Overview or its reading did not complete. - 2026-11-08: Changed: topic keywords no longer include one-off tasks with a provider, such as paying a phone or electricity bill or logging in, and two searches count as one only when they are close variants, not when their volumes match. Topic search demand drops where such searches were counted, so some Heralded Scores move from the next weekly report; issued reports keep their frozen weights. See Keywords.
- 2026-11-08: API keys and assistant connections support Read only and Full access, with
heralded:readandheralded:writescopes. Existing credentials stay read-only, and write refusals return an HTTPinsufficient_scopechallenge. - 2026-11-07: Studio removes legacy statement controls and review-fix undo. New pieces keep claim findings, passage highlights, comments and confirmations. Older drafts remain available for editing and approval.
- 2026-11-06: Content reports include resolved questions. Answering a writer question posts one comment for that question; dismissing it leaves the draft unchanged. Page improvement orders accept an optional writer note.
- 2026-11-06: Content language previews accept a page address. New pieces started from a bigger-change comment keep the original piece’s format and language, with Undo before the credit is spent.
- 2026-11-06: New Snapshots, daily updates and weekly reports ask ChatGPT, Gemini, Google AI Overviews and Google AI Mode. Weekly reports can also ask Claude outside Europe where your plan includes it. Perplexity and Microsoft Copilot are retired; earlier reports keep their answers and history.
- 2026-11-06: Content pieces in REST and MCP use
ordering,researching_and_writing,applying_comments,your_review,approved,publishing,published,stopped,failedandpaused. Brief and rewrite stages are removed. Older drafts remain readable and can still be approved.has_briefstays deprecated and is false on new pieces. - 2026-11-06: Content drafts show sentences the claim report could not confirm in Notes. Confirm a sentence for the current version, then choose whether to save it as a brand fact.
- 2026-11-06: A topic’s Work list follows the topic pane’s selected period and filters. The Work page filtered to a topic keeps its four-report window.
- 2026-11-06: Insight reads use topics, markets and audiences for every caller. Removed segment reads, Segment and Language filters,
topic_market,tracked_topics, and subject IDs and segment fields from topic, question, keyword and source references. Question, question-fit and keyword writes accepttracked_topic_id. Measured language markers and Europe country breakdowns remain available. - 2026-11-06: Pooled Europe figures stay Calibrating when the earlier comparison window has no answers before the current window, instead of marking an existing brand as a first report.
- 2026-11-06: Content pieces in REST and MCP support
researching_and_writingandapplying_commentsstages and a report of questions, sources and references. Studio stages can also include the writer’s turn count without spend.has_briefis deprecated. - 2026-11-05: Work rows return
focus: nullwhen a brand has no starred topic or competitor; suggestions outside a configured focus still return the outside tag. See actions. - 2026-11-05: Understood is read part by part once a brand’s profile statements are split. In
GET /v1/brands/{brand_id}/perceptionand/reputation, their claim reads and MCPget_perceptionandget_reputation, each profile claim row addsparts, each with itskey,wording,quote, verdict counts andtrend.facts_summarycounts a split claim’s parts in its place. A figure trend point’s instrumentkeyaddsunderstood_measure, and Understood’s first report read part by part carries it inbreak.parts. See Understood. - 2026-11-05: Topic suggestions identify the suggestion and tracked topic to replace, and topic details include their selected engines. Market reads include Focus choices and Focus rows carry their market and audience. Keyword and Search comparison reads accept
countryseparately from the topic’smarket. - 2026-11-05: The Command Center assigns questions and keywords by tracked topic, preserving the topic’s market and audience.
- 2026-11-05:
GET /v1/brands/{brand_id}/topicsand MCPget_topicsreturn one item per tracked topic with its ownid,market,audienceandaudience_id;topic_idkeeps the shared subject. Insightmarketfilters select the topic’s market, so a Romania selection excludes Romanian answers from Europe topics.audienceselects an audience UUID orall_buyers.GET /v1/brands/{brand_id}/marketsand/audiences, with MCPget_marketsandget_audiences, replace public segment reads and MCPget_segments. See topics. - 2026-11-05:
sites_totalonGET /v1/brands/{brand_id}/cited-pagescounts the sites AI cites, the sites whose pages it lists.found_via=ai_citationonGET /v1/brands/{brand_id}/sourceskeeps sites cited only in the baseline in its comparisons, andfound_viaapplies to cited sites as well as uncited ones. - 2026-11-05: Shared Snapshot answers have unique positions within each engine across pages and pooled runs. Engine sites and citation counts are available through
GET /v1/shared/scans/{share_id}/engines/{engine_id}/sitesand MCPlist_shared_engine_sites, with hidden competitors omitted. - 2026-11-05: Shared Snapshot answers return full Markdown in
text, withtext_highlightsindexing that source. Hidden brands stay masked in text and links. Failing site checks include available fix steps. - 2026-11-05: Shared answers remove links to hidden brands while keeping safe labels readable. Understanding rows omit incomplete quotes, and competitor changes read Calibrating when your brand has earlier reports but no comparison score.
- 2026-11-05: Scan list rows now include the Snapshot report’s market label. The Command Center shows it when a domain has runs in multiple markets.
- 2026-11-05: Weekly report headlines describe the week behind; work counts appear under Next week. Work details and evidence return quoted AI passages as plain text.
- 2026-11-05: Perception shows each profile statement’s parts, their agreement counts and gaps. Understood names the new measure on its trend, and the first weekly report using it carries a note.
- 2026-11-05: List a managed brand’s Snapshots and their issued figures through
GET /v1/brands/{brand_id}/snapshotswithmanaged:read. Usemanaged:shareonPOST /v1/brands/{brand_id}/snapshots/{share_id}/shareto get an unlisted link; revoked Snapshots stay revoked. See Managed Snapshots. - 2026-11-05: Topic previews and copies can select a market and audience from brand lists. Each tracked topic has its own name, star and tracking status. Topic focus IDs identify the tracked topic in its market and audience;
topic_ididentifies its shared subject. Europe reads topics with fewer than ten questions. - 2026-11-05: Plans count topics across your workspace and set a separate brand limit. Extra topics apply across brands after payment. Active topics keep reading above a limit. Organisation usage requires workspace settings or billing access. Manager allocation reads and writes use brands with 15 topics each; Usage and Billing show both capacities. Pending topic purchases keep their invoice link on Billing after a reload.
- 2026-11-04: Weekly reports expose their own full Snapshot through
scan_idon REST and MCP. Shared Snapshot reads includepdf_enabled; weekly runs start restricted to your brand’s report readers and can be made public from Share. - 2026-11-04: Shared question answers in REST and MCP include full masked
text,text_highlights, and question-widebrandsandpagescounts. Cited links omit tracking parameters and combine matching URLs. Readability checks includegroupand plain labels. Snapshot positioning engine passages, flag titles and passages, and understanding-row quotes, values and gap notes mask hidden names and aliases. Flags exposing hidden names through their URL or domain are omitted, with matching flag counts. Robots.txt exclusions on query-string URLs do not produce blocked-page findings or actions. - 2026-11-04: Fact rows in the perception and reputation reads and MCP
get_reputationsplit their counts intoorigins.probe, the answers to the fact’s own question, andorigins.prompt, the answers to tracked prompts. They also name thedefinition_versionthey count and flagcurrent_version_pending, and a claim trend setsdefinition_changedwhen its comparison would cross a change of meaning. A fact definition listsearlier_wordings, the wordings a typo fix replaced, and a fact’s trend is a new baseline while its comparison spans the first report that asked the fact its own question. - 2026-11-04: Review separate brand facts, their questions and agreement checks before saving in Strategy. Conflicting facts offer Keep both, Replace or Keep the existing one; replacements preserve identity and start a new definition. Perception fact reads include the current definition, author and next check date.
- 2026-11-04: Brand profile facts and reputation fact definitions now include kind, comparison, probe question, definition version and author name. MCP
get_reputationreturns the same definitions and stays read-only. - 2026-11-04: Existing brand facts gain checks and questions without changing your wording. Compound facts offer a confirmed split in Strategy. Brand fact reads include
split_candidatesandinterpretation_failedthrough the API and MCP. - 2026-11-04: The Command Center uses Question and Change consistently across tables and panels. Topic labels preserve AI, CRM and SEO, and Website findings spell out Total Blocking Time. The API uses question wording for low-quality tracking work and unmeasured topic reasons.
- 2026-11-03: Action reads add
job.failure, why a failed piece stopped, withjob.stopped_atnaming the step it reached.note.why_it_mattersis one sentence that names the brand and the expected gain. An action’stitleis its piece’s headline once the piece holds a draft. A pitch to a source is one action whichever segments cite it. REST,list_actionsandget_actionreturn the same. Withwith_viewer=true, the action’svieweraddsassigned_to_you. - 2026-11-03: List a workspace’s Snapshots with
organization_idinGET /v1/scansor MCPget_scan. Snapshot owners can restrict or revoke report links from the share pane. - 2026-11-03: Brand look keeps default assets when a website logo or font cannot be fetched. Failed uploads still report a file error.
- 2026-11-03: Setup starts with suggested competitors from your website and refuses your own brand or an owned website when you add a competitor.
- 2026-11-03: Topic score sorts keep unscored topics last in either direction. Profile statements use Category, Audience, Offer and Difference, and Sources headlines distinguish cited sites from all discovered sites.
- 2026-11-03: Competitor ranks, default leaderboard order and share of voice follow the selected side. Source panes count distinct read pages, answer summaries use Visibility’s measured population and pooled-market exclusions, and opinion changes compare the selected reports with their baseline. REST and MCP return the same figures, including
mentioned_since, nullable unmeasured ranks and opinionchange_detail. - 2026-11-03: Changing plans during a trial keeps its end date and charges nothing today. The expired founding offer is unavailable, and checkout status includes the number of credits added.
- 2026-11-03: Setup links in the API read Automation and open the brand’s Automation settings page directly.
- 2026-11-02: Each opinion quote from an AI answer carries
answer_read_idandprompt_uid, in REST and MCP’sget_reputation, so the quote opens the answer and question it came from. Both are null for a quote from a page. - 2026-11-02: Topic, keyword, figure, engine and competitor panels open as full pages with paged sections, small figure trends and related Work. REST and MCP reads support compact previews and section paging; competitor-page Work targets the page’s exact URL.
- 2026-11-02: Work panes show their evidence and steps, and long assets open in the full work page. The Assets view lists pieces, drafts and site changes by type, state and owner, also available through
GET /v1/brands/{brand_id}/assetsand thelist_assetsMCP tool. Action reads support compact previews and paged sections. - 2026-11-01: Question reads support compact previews with
with_details=falseand per-figure trends. Markets, Google searches, cited sites and leading brands have separate paging parameters. - 2026-11-01: The Home read and MCP
get_weekly_briefinclude today’s decisions, team reviews, Heralded’s running work and suggestions with their reason and cost. - 2026-11-01: The week timeline API and MCP tool add daily summaries and a
dayfilter for reading each day’s changes in lead order. - 2026-11-01: Competitor site moves read new and removed pages from each competitor’s own sitemap, and report a homepage or pricing change only when its headline or plans differ from the previous week’s. Moves from the vendor site map and key page hash changes no longer appear, and
key_page_changedis no longer returned. - 2026-11-01: Sources uses the same listed-site total for its Sites tab and pagination, including after switching tabs. Perception’s facts summary includes profile claims. Competitor moves exclude watched-page hash changes.
- 2026-10-31: The Website map API and
get_site_maptool include citation counts for their pages. Usepageto open a page’s language whenlanguageis unset. Citation counts are null when the citation measurement is unavailable. - 2026-10-31: Shared Snapshot reports add each competitor’s winning questions, engine results and citing sources, plus positioning readings by engine. Use the new
get_shared_snapshotMCP tool to read the same evidence with a share id. See Shared report reads. - 2026-10-31: Perception and reputation headlines use a written statement when available, then the served figures.
headlineis now nullable on the Perception and reputation reads and isnullwhen Understood has no measured value; the Perception page then omits it. See Perception. - 2026-10-31: Home headlines count the work in Needs you for the current reader. The weekly timeline shows observed changes and measured results, leaving out pending or unavailable checks.
- 2026-10-31: Changed: competitor website
changesonGET /v1/brands/{brand_id}/audit/competitors,/audit/competitors/{key}, MCPget_competitor_sites, and the competitor reads withwith_detailsare the week’s moves, one per competitor and change type, each at its shallowest page. Addchangeto list each page of that type. Files such as PDFs and images no longer count as pages, inchangesor in a competitor’snew,removedand weeklyactivity. See Competitor websites. - 2026-10-31: API and MCP links open the current Command Center pages, including Work, Strategy, Visibility, Competitors and Website. Route identifiers stay unchanged, and previously shared page links redirect.
- 2026-10-31: Filter your Snapshot and Audit lists by domain with
GET /v1/scans?domain=seedblink.comandGET /v1/audits?domain=seedblink.com. - 2026-10-31: Topic keywords,
GET /v1/brands/{brand_id}/keywordsand MCPget_keywordsaddsourceandreplaced_by_next_add. The latter marks which researched keyword a member’s next add in that topic, segment and country would replace at the cap. See Keywords. - 2026-10-30: Website finding work adds
status, the customer-facing stage from its work projection.insight.workidentifies the canonical work returned by filing, including when a newer action also covers the finding. Insight filing results also carrystatus. See Website. - 2026-10-30: The brand’s Website pages read and MCP
list_site_pagesaddheadline,readable,with_findingsandcitedover the filtered population before paging. Rows addsectionandfinding_ids. A null findings count means some matching pages were not measured. A null cited count means citation measurements are unavailable. Website’sheadlinesummarizes page access and findings. See Website and Figures. - 2026-10-30: Perception and reputation reads and MCP tools add
headlineandfacts_summary, withmostly_right,measuredandinsufficient_keys. Facts need three addressing answers and strictly more than half agreeing to count as mostly right. Reputation facts addinsight, the actionable page and its existing work. Opinion evidence acceptspages_offsetto page its holders. See Perception. - 2026-10-31:
GET /v1/brands/{brand_id}/scoresand MCPget_scoresaddheadline, one sentence on how AI answers treat the brand under the read’s filters, andGET /v1/brands/{brand_id}/keywordsand MCPget_keywordsaddheadline, one sentence on the brand’s Google first-page rankings. Both come from templates with no model call, and arenullwhile nothing is measured. See Filters and groups and Keywords. - 2026-10-31: Snapshot reports add
leaderto eachscan.axes.by_promptrollup, the brand recommended in the most answers to that question. It isnullwith fewer than two recommending answers, and hidden competitor names are not returned. See Shared report reads. - 2026-10-30:
GET /v1/auditslists the Audits you ran, newest first, withid,state,domain,started_at,completed_at,progress_pct,failure_reasonand, once delivered,share_id. See Scans. - 2026-10-30:
GET /v1/shared/scans/{share_id}/questions/{query_id}/answersand MCPlist_shared_question_answersadd a shared question’s answers, 10 per page, with engine, run, strength marks, highlighted excerpts and citations. Snapshots name only their visible competitors and mask other names. See Shared report reads. - 2026-10-30: Topic and question reads and their MCP tools add
measurement_status,first_answers_atandfirst_score_on. Questions keep their trackingstatus, and topics keep their trackingstate. New topics sort first. See First answers and score. - 2026-10-30: Home adds three reads and MCP tools.
weekly-briefservesscan_id,issued_at,done,total,remaining,decisions,new_since_mondayandnew_total. Each decision servesid,action_id,job_id,kind,title,demand,href,from_last_weekanddecided.week-timelineservesweek,rowsandtotal; rows carryid,kind,event,observed_at,target,action_id,work_hrefandresult.focus-cardsservesitemswithfocusandfigures; figures carrykeyandfigure. First-party sessions also receive the brief’sheadlineandread_only, the event and focussentence, and each focus figure’slabel. All three carrymeta; the brief and timeline also carrylimit,offsetandnext_cursor. See Home fields. - 2026-10-30:
GET /v1/brands/{brand_id}/reportsandGET /v1/brands/{brand_id}/reports/{report_id}, with MCPget_reports, list and read the brand’s weekly and quarterly reports as they issued:aiandgooglestandings,moved,work_completed,competitors,next, and for a quarterly report itsweeks. Each section carries astate;focusholds the stars and a quarterly report’sgoalthe revision current at issue, andnew_pageslists the pages cited for the first time.GET /v1/brands/{brand_id}/reports/{report_id}/recipients, andget_reportswithrecipients=true, list who a report was sent to. See Reports. - 2026-10-30:
GET /v1/brands/{brand_id}/heraldand MCPget_herald_greetingaddgreeting,decisions_waiting,new_results,seen_at,addressandsuggestions. They use templates with no model call or answer charge.pageselects the suggested question, andscopecarries its active filters through the counts and returned address. The Herald answers every kind of work in one conversation. Existing conversation paths return their history; former persona conversations accept no new messages. Onboarding answers before setup confirmation do not use the monthly allowance. See The Herald and Herald greeting. - 2026-10-30:
GET /v1/brands/{brand_id}/moving-away-fromand MCPget_perceptionwithmoving_away_fromreturn, for each label the brand is moving away from, the share of answers naming it that describe it that way, the change in that share where the paired test calls it real, the newest answer’s words and the cited pages that repeat it. Moving away from maps the fields. - 2026-10-30: Action detail and MCP
get_actionadd orderedresults.steps, with each kind’s declared signals and pending, unchanged, unavailable and inconclusive states. Results rows in/v1/brands/{brand_id}/resultsand MCPlist_resultsadd the sameresultsobject. Measured steps distinguish No effect, Fell and Too early to tell. Recommended more and Paying off require verification of the targeted answer metric against untouched questions; a live site fix claims no answer gain. See Work results. - 2026-10-30:
GET /v1/organizations/{organization_id}/usageand MCPget_usageaddfirst_screen_rewritesto each brand:used,limitandresets_atfor the free first-screen rewrites it has started this calendar month.GET /v1/actions/{action_id}and MCPget_actionadd the drafttypevaluefirst_screen: a headline, subheading and call to action, one to a line. See First-screen rewrites. - 2026-10-30: Competitor list and detail reads, and MCP
list_competitorsandget_competitor, acceptwith_detailsto include weeklysitesorwebsitedata and moves with stored before and after values, and AI descriptions dated bydescription_scan_idanddescription_at. The list adds a templatedheadline, its rows addbrand_keyanddescription, leaderboard rows adddescription, and detail addsdescription,most_said_forandmost_said_against. Competitor website changes add nullablebefore,afterand currentscreenshot_url; snapshots carryweek,headline,checksandpricingas applicable. See Competitors and Competitor websites. - 2026-10-30:
GET /v1/brands/{brand_id}/strategyand MCPget_strategyreturn the brand’s goal with its revisions, baseline, current Recommended, Mentioned and Understood on the goal’s questions and target, its focus stars on topics, competitors and markets, andmoving_away_from. Actions fromGET /v1/brands/{brand_id}/actions,GET /v1/actions/{action_id}, MCPlist_actionsandget_actionaddfocus, the starred topic or competitor the work serves, oroutside.GET /v1/brands/{brand_id}/settingsand MCPget_settingsaddprofile.profile.moving_away_from. See Strategy. - 2026-10-30: Rows a kind of work can address add
insight, with a stableid, thekindsof work that fit it, each with itsplay,titleandcredits, and theworkfiled from it. They are Website findings onGET /v1/brands/{brand_id}/auditand MCPget_audit, a page’s findings and thechecksit fell short on, onGET /v1/brands/{brand_id}/pages/{page_id}and MCPget_page, contradicting pages on Perception and Reputation claims with MCPget_perceptionandget_reputation,opinionsonGET /v1/brands/{brand_id}/reputation,worth_pursuingonGET /v1/brands/{brand_id}/sourcesand MCPlist_sources, unansweredcoverage_questionsonGET /v1/brands/{brand_id}/topics/{topic_id}and MCPget_topics, competitor websitechangesonGET /v1/brands/{brand_id}/audit/competitors, MCPget_competitor_sitesand the competitor reads withwith_details, and prompts an engine leaves you out of onGET /v1/brands/{brand_id}/prompts, one prompt, and MCPlist_promptsandget_prompt. Changed: aworth_pursuingrow’stitlenames the route its outreach takes when the source has none of its own yet. See Insights and their work. - 2026-10-29:
GET /v1/actions/{action_id}and MCPget_actionaddcontent_piece.images, with featured-image state, file metadata, generations left, earlier results and the social preview’s source and style.GET /v1/actions/{action_id}/piece/images/{slot}redirects to a fresh download forfeaturedorsocial. See Content credits. - 2026-10-29:
GET /v1/brands/{brand_id}/pages/{page_id}and MCPget_pagefindings addnote, this page’s own note, andothers, the count of other affected pages. They droppoints_off_scorebecause a site-wide deduction does not describe one page. The Website findings read keepspoints_off_score. See Findings. - 2026-10-28: Actions and MCP
list_actionswithassignee=mine_or_openreturn teammate-owned asks undergroup=waitingwhen both people can start work. Theirholderiswaiting,demandnames the teammate andwaiting_sincestays unchanged.group=your_inputkeeps your own and open asks, oldest first. Omittingassignee, service tokens and readers who cannot start work keep their existing behaviour. Work includes daily updates in its newest completed scan and retains every finished group from the last 14 days. See Actions. - 2026-10-27: Topic leaders include measured discovered brands in the comparison, matching the Brands table. A discovered brand without a score does not block a lead. See Topics.
- 2026-10-26: Every figure
changein/v1and MCP, and each Overview card’schange, addscompared_engines: the engine keysdeltawas taken on. Changed: when the engines asked in the period differ from the baseline’s,deltais the move over the engines both asked, not the move the trend draws, andcompared_enginesnames them. A figure’svalue,trendand engine boxes still include every engine asked.compared_enginesisnullwhen the size is the move the trend draws, and on Search. See Change. - 2026-10-25: Changed:
GET /v1/brands/{brand_id}/keywordsand MCPget_keywordswithgroup=conceptjoin the keywords sharing one English meaning across topics as well as markets. Concept keys areg:<sha1>, and agroup=conceptcursor issued before this change returnsinvalid_cursor. Each concept addstopicsandmembers_checked, andtopic, now deprecated, repeats the first oftopics. Withtopic, a concept with a member in that topic keeps its members in other topics. A concept’smentionedis shown once any member’s check has fetched its results, and concept and marketsearches_totalcountno_datakeywords as zero. See Keywords. - 2026-10-25: Changed: A Search
changeis the move between the two points the Search trend draws, under any keyword filter, and itsbaselinedates are the baseline report’s own. A Search figure whose baseline report the trend draws as not measured readsfirst_reportwithdelta: nulland no baseline dates. Search reads the keywords you track today in every report, so archiving a keyword removes it from past points; this replaces the frozen coverage of 2026-10-24. A segment’s language policy stored as a cycle and as shares compares equal, sotrendno longer labels alanguagechange for the same mix. The words fornot_comparable, such astrend.labelon Prompts and claims, read New baseline; itsstateis unchanged. See Change. - 2026-10-25:
GET /v1/brands/{brand_id}/keywordsand MCPget_keywordsacceptmentions=mentioned|recommended, which selects the keywords whose latest check mentions or recommends you, before grouping, the summary and the totals. Changed:tracked_totalandarchived_totalare each view’stotalunder the request’s filters and grouping, sogroup=conceptcounts concepts andgroup=marketcounts markets.rankings_totaland each market row’srankingscount the selected keywords with a fetched check in the period instead of in its latest report.summaryaddschecked_top_3andchecked_top_10, those keywords in the top 3 and top 10. See Keywords. - 2026-10-25: Changed: Search detail, on Scores and MCP
get_scoreswithwith_search_detail=true, counts rankings as the keywords read does.rankings_totalis every tracked ranking, checked or not, and the newrankings_checkedthose with a fetched check in the period, of which the newrankings_checked_on_axishave a positive share on the axis.rankings_on_axisandrankingscover every ranking whose latest check has a positive share on the axis, and each ranking addsvolume_state.by_markethas one row per country, as the keywords read’smarketfilter selects it, with every tracked ranking in it and the keywords read’s summary figure under thatmarket;languageis null for a country searched in more than one.own_pages_top10,ai_overviews_citing_youandranking_pagesread each ranking’s latest check. The newbrands_ledcounts the brands below you on the axis. See Search detail. - 2026-10-25: Prompt
google_searchesentries addanswersandvolume_state. They sort by distinct answers that ran the search, then monthly Google searches, rank and text. The prompt pane readsUnder 10when Google returned no volume number. See Google searches. - 2026-10-25:
GET /v1/brands/{brand_id}/prompts/{prompt_uid}and MCPget_promptaddmentioned_countandrecommended_countto eachengine_cardsentry: the answers on that engine that mention or recommend you, over theanswersof the matching mark in itsfigures. See Prompts. - 2026-10-25: Changed: Prompt and engine panes return
answer_count: nullfor Understood, which has a graded share instead of a count of perfect matches. See Figures. - 2026-10-25: Changed: Search detail
brands, on Scores and MCPget_scoreswithwith_search_detail=true, lists every brand by the axis value, unmeasured last, instead of the first five with you in the fifth row.brands_totaland each row’s fields are unchanged. See Search detail. - 2026-10-25:
GET /v1/brands/{brand_id}/topics/{topic_id}and MCPget_topicswith atopic_idandwith_pane=trueaddai_counts: the topic’s AImentionedandrecommendedanswer counts, each withnumerator,denominatorandanswers. Withoutwith_panethe response is unchanged. See Topics. - 2026-10-25: Scores and MCP
get_scoreswithwith_panes=trueandside=aiorside=alladdbrandsandbrands_totalto the Praised pane, in the shape of the Mentioned and Recommended panes, andpaused_enginesto the Understood and Praised panes. See Brands and paused engines. - 2026-10-24: Scores and MCP
get_scoreswithwith_panes=trueandside=aiorside=alladdbrands,brands_totalandpaused_enginesto the Mentioned and Recommended panes.brandslists up to five brands by the axis, pinning you fifth when you place lower, each withbrand_key,name,domain,is_you,rank,valueandchange;paused_engineslists the engines paused for the period’s latest report. Search detailbrandsrows addbrand_key. Existing fields keep their values. See Brands and paused engines. - 2026-10-24: MCP tool descriptions no longer end with the OpenAPI link. The server instructions and
list_brandscarry it, so the tool list is about 2 KB shorter. See Connect an MCP client. - 2026-10-24: Pane and API reads name the next step; Actions can be filtered to one prompt, topic, keyword, figure, source or competitor. One prompt, topic and keyword, each axis pane in
GET /v1/brands/{brand_id}/scores?with_panes=true, one source and a competitor page’srival, with their MCP tools, addactions_total, every live action about the subject, andnext_step_action_idandnext_step, the highest-priority live action that waits on you and that you can act on. Each lists its actions highest priority first.GET /v1/brands/{brand_id}/actionsand MCPlist_actionsacceptsubject, such astopic:<id>, and addsubject_labelwhen you send it. Changed: one source’sactionsandactions_totalcover live work only, so finished and dismissed pitches leave the list. See Action fields. - 2026-10-24: Keywords and MCP
get_keywordsaddgroup=concept|market,market,position,ai_overview,q,with_summary, and sortsmarkets_top10andchange. Each keyword addsmentioned_change. Optionalconceptscarrykey,text,topic,member_ids,members, distinctmarkets,searches_total,volume_partial,best_rank,best_rank_keyword_id,best_rank_country,members_top10,ai_overviewcounts andmentioned. Optional market rows carrycountry,language,keywords,rankings, volume totals,top_3,top_10andmentioned. Grouping or requesting a summary addsconcepts_total,keyword_markets_totalandrankings_total.summaryaddsmentioned,markets,positionswithtop_3,top_4_10,not_in_top_10andunchecked, plustop_10. Grouping follows filters and precedes sorting and paging. The default list keeps its shape apart frommentioned_change. See Keywords. - 2026-10-24:
GET /v1/brands/{brand_id}/topics/{topic_id}and MCPget_topicswith atopic_idacceptwith_pane=true, which addsby_engine,search_trend,keywords_top10,brands,brands_totalandpages_total. Without it the response is unchanged. Onside=search,brandsplaces brands by Mentioned. See Topics. - 2026-10-24:
GET /v1/brands/{brand_id}/prompts/{prompt_uid}and MCPget_promptaddgoogle_searches, the prompt’s Google searches grouped by text and market, each with the engines that ran it, its monthly searches, your Google rank and the matching keyword. They also addsources_total, the number of domains the prompt’s answers cite beside the five insources, andmentioned_pcton each wording. See Google searches and Prompt AI searches. - 2026-10-24: Scores and MCP
get_scoresacceptwith_search_detail=truewithwith_panes=trueandside=search. Mentioned and Recommended addsearchwith ranking counts, your pages in Google’s top 10, AI Overviews citing you, ranked brands and their changes, rankings, market figures and related actions. The default response stays unchanged. See Search detail. - 2026-10-24:
GET /v1/brands/{brand_id}/keywords/{keyword_id}and MCPget_keywordswithkeyword_idaddrank_series: your best Google position at each weekly report thatfigures.mentioned.trendcharts, oldest first, with the sameatandbreakas that trend’s point. A point’sstateisranked,not_in_top_10orunchecked, declared open to new values, andpositionis set only when it isranked. See Keywords. - 2026-10-24: Changed: a figure’s change
deltain/v1and MCP is the shown value minus the baseline’s, in points, as the trend draws them, instead of the paired test’s estimate. The paired test still setslow,highandreal.upanddownneed a real move that has the sign ofdelta; any other move issteadywith its signeddelta. No change servescalibratingany more, leaderboards included, and a baseline with no value isfirst_report. A claim’s trend on Perception follows the same rule. One report readson the previous weekin the comparison text. See Change and Figures in the API. - 2026-10-24:
competitors_checked_7d(and its deprecated aliascompetitors_watched) on Work and the Overview counts only competitors you track now, so it never exceedscompetitors_tracked.GET /v1/brands/{brand_id}/competitorsaddspage.checked_7d, the same figure. See Competitors and Actions. - 2026-10-24: Multi-week figures in
/v1and MCP weigh each language policy by its number of answers when the policy changed inside the period. Weights within each policy stay the same, as do figures for periods covered by one policy. Stored reports, leaderboards and issued Snapshots keep their frozen values. See Mentioned and Recommended. - 2026-10-24:
GET /v1/brands/{brand_id}/answersand MCPlist_answersacceptread_since, an ISO 8601 time that keeps the answers whose run finished at or after it. Withperiod=allor withoutperiod, it reads every weekly and daily answer once, andtotalmatches the answer counts ofGET /v1/brands/{brand_id}/workand MCPget_workfor the same window. Changed:demandon delivered actions reads the result label,Paying off,CitedorDelivered, followed byresult byand the date while the verdict is pending, such asCited · result by 17 Nov. It replacesVerifyingand the words of the measured outcome. See Prompts and answers in the API and Results. - 2026-10-24: Search-side figure changes use each report’s frozen keyword checks for coverage, even if you archive a keyword later. Mentioned, Recommended, Understood and Praised on Search read First report when the baseline did not measure them. A change between the AI part and the blend on All or AI remains not comparable. See Change.
- 2026-10-24: Changed:
ai_citation_shareon each platform inGET /v1/brands/{brand_id}/reviewsand MCPget_reviewsis the share of your counted AI answers in the latest week that cite the platform, from 0 to 1, instead of the share of synced reviews also found in AI citations. It no longer moves when reviews sync. See Platform ratings. - 2026-10-24: Removed:
trend_notefrom axis panes inGET /v1/brands/{brand_id}/scores?with_panes=trueand MCPget_scores. Trends draw from the second weekly report, so no note applies. See Change. - 2026-10-24: Website reads and MCP
get_auditcountpages_with_findingsover pages read.totaliscoverage.pages_read; unread pages contribute to neither count nor total. Every trend point with a saved site map uses the same count. A report without a map keeps its recorded value and starts a break. Cut-short reads leave the sitemap-link check not measured, with no points off. New reports use findings rules version 3, breaking the Website score trend at the change. AI can read follows each page’s access checks where available. See Website page counts. - 2026-10-24: Changed:
facets.languagesonGET /v1/brands/{brand_id}/audit/pages,GET /v1/scans/{scan_id}/audit/pagesand MCPlist_site_pagescounts each language under every filter butlanguage. See Website. - 2026-10-24: Changes on
/v1and MCP use the previous comparable report for Latest and the preceding equal-length window for multi-report periods. Baselines stop at non-comparable reports. From the second report, the paired test alone calls a move real; steady changes keep their signed delta, and calibrating means no interval. Since you started also compares from two reports. The Sources Citations card change is the difference between the period’s citation count and its baseline, with direction following the sign of that difference. Trendbreakaddscomparable, true for engine or language changes alone. See Change and Sources. - 2026-10-24: Topic lists, one topic and MCP
get_topicsreturnleader_stateasmeasured,no_clear_leaderornot_measured. A leader needs a Heralded Score above Invisible, no tie and an interval’s low end above every other brand’s score. An unmeasured tracked competitor prevents a clear lead.leadingcounts your clear leads;competingcounts all topics in view where your Heralded Score is measured. The Writer meter uses the same count for the latest report. See Topics. - 2026-10-24: Understood and Praised follow
sidein overview, scores and MCPget_brand_overviewandget_scores.aireads AI answers,searchreads ranking pages, andallreads the blend. Overview adds both figures to every entry insides. Figure panes carry their selectedfigureand trend, keepyouandtopic_id, and addparts.ai_answersandparts.web_pagesfor a blend. Engines without a rendered answer are left out of pane engine lists.figure_onlyis deprecated until 2026-11-23, withDeprecationandSunsetheaders. See Figures. - 2026-10-24: Changed: the overview’s and MCP
get_brand_overview’ssources_mentioning_youcounts third-party sites with a read page naming you, out of the third-party sites with a read page, overperiod. It counted the pages of the latest report. Muted sites and competitors’ sites are left out, and the field keepscount,ofandpct. The source list and MCPlist_sourcesaddrecommending.naming, the same count. See Citations. - 2026-10-23:
listActionsand MCPlist_actionsacceptassignee=mine_or_openfor the Needs-you list and addwaiting_sinceto date the current ask. Withgroup=your_input, rows arrive oldest-waiting first and include failed first drafts handed back to you and stopped site checks. See Action metadata. - 2026-10-23: Removed: the
enginefilter fromGET /v1/leaderboardsand MCPget_leaderboards. HTTP requests that still sendengine=read the board across all engines. Each engine’s top three, brand engine figures andengine_ranksremain available. See Leaderboards. - 2026-10-22: The Heralded Score uses AI answers only. Overview, scores, competitors and topics return the Heralded Score, Mentioned and Recommended for
side=all. Search keeps its Mentioned and Recommended and returnsheralded_score.value: nullwith the new statenot_scored. Keywordscoreandtrendare null; keyword detail keeps its shares and results. Stored reports read the same way without a history break. See Sides. - 2026-10-23:
GET /v1/brands/{brand_id}/resultsand MCPlist_resultslist delivered actions with Paying off, Cited or Delivered labels, first citation, citation count and measured outcome. Page by label or newest result, with label counts and a total. Setup, prompt additions and deliveries undone by reopening are excluded. The overview’sverified_actionskeeps its verified gains and citations. See Results in the API. - 2026-10-22: Action lists and MCP
list_actionsaddfirst_citationandcitation_count. The overview and MCPget_brand_overviewinclude cited pages inverified_actions. Changes and MCPlist_changesaddfirst_citationunder the verification source, opening the action and folding its matching site-citation observation. See Action metadata. - 2026-10-22: Work
operations(GET /v1/brands/{brand_id}/work, MCPget_work) addtitle, the action or piece the work is for, andfinished_atandresulton finished work.statusaddswaiting, for work waiting on someone other than the caller, and is declared open to new states. A report’slabelnames its run, such asWeekly report, andprogressappears only while it reads answers. A delivered report isdoneeven when a step failed, and a failed read is left out once a later one finishes. See Actions. - 2026-10-22: A Website read’s
coverage(GET /v1/brands/{brand_id}/audit, MCPget_audit) addspages, the pages on your site, withpages_readandpages_ai_readable, and the site map (GET /v1/brands/{brand_id}/audit/map, MCPget_site_map) addssite_pages, the same count in every language.pages_with_findings.totalis that count, the pages read (GET /v1/brands/{brand_id}/audit/pages) list those pages, one row each, andfix_firstlists the most points off the score first.pages_in_siteon the website scope read counts Counted only sections too. See Website. - 2026-10-22: Changed:
GET /v1/brands/{brand_id}/perceptionand MCPget_perceptionserve Understood and Praised as the blend of AI answers and pages, the same figures as the overview and the reputation read. See Perception. - 2026-10-22: Each side of a topic’s
scoresinGET /v1/brands/{brand_id}/topics,/topics/{topic_id}, a prompt’stopic_detailand MCPget_topicsaddsstate:not_measuredortoo_few_answersfor an AI or All side with no value, andnot_scoredon Search. See Topics. - 2026-10-22: Changed: a daily update’s finished keyword checks no longer set
updatingon thesearch.score,search.keywordsandsourcessurfaces, because they count in the next weekly report. Pending checks still do. See Result freshness. - 2026-10-22: Figure changes add
statefor a first report, calibration, a measured move, a steady comparison or a comparison that cannot be made. Engine and language additions keep paired change. Search-side figures carrybasis: "search". REST and MCP return the same states and trend markers. See Change. - 2026-10-20: Service Snapshot and Full audit starts require the
Idempotency-Keyheader. The deprecated body aliasidempotency_keyhas been removed. See Service starts. - 2026-10-20: Removed the pre-launch
GET /v1/brands/{brand_id}/prompt-suggestions, MCPlist_prompt_suggestionsand topic detail’sbuyer_questions. Read suggested topics through/topics?view=suggestedorget_topicswithview=suggested, and prompt AI searches through/prompts,/prompts/{prompt_uid},list_promptsorget_prompt. - 2026-10-20: Service tokens can start a Quick audit through
POST /v1/service/quick-auditswithout spending a scan credit, then read it through the service audit routes. Each workspace can start 100 per UTC day; replays do not count. Website results retire 30 days after delivery. See Service Quick audits. - 2026-10-19: Answers and prompts remove the deprecated
searchparameter from REST and MCPlist_answersandlist_prompts. Useqfor text search. See Text search. - 2026-10-18: Each language in a Website read’s
coverage.languages(GET /v1/brands/{brand_id}/audit, MCPget_audit) addsread, the pages the read covered in that language. It is0for a language the site holds and the read did not cover, andnullon reads that kept no count. See Website. - 2026-10-18: Changed:
competitorsonPOST /v1/service/snapshotsis optional and deprecated. A Snapshot ranks the competitors its answers name and ignores any you send. The field goes on or after 2026-11-16. The body fieldidempotency_keyon service starts also goes on or after 2026-11-16, so send theIdempotency-Keyheader. See Developers. - 2026-10-18:
GET /v1/actions/{action_id}and MCPget_actionaddcontent_piece.fields, the settled draft’s title, summary or search details. Each field carriesname,labelandvalue. See Actions. - 2026-10-18:
/v1/organizations/{organization_id}/usageand MCPget_usageaddsegments, withused,included,extraandlimit, and each brand addssegments, its live segments withtopics:tracked,limitandblocks./v1/brands/{brand_id}/settingsand MCPget_settingsaddfeatures, withmentions_monitoring,reviewsandadvocacy, and each segment adds the sametopics, which/v1/brands/{brand_id}/segmentscarries too. Existing fields stay the same. See Usage. - 2026-10-17: MCP rejects undeclared arguments, describes every input and returns actionable JSON errors.
get_scoresuses onlytopic,list_answersonlyprompt, andget_promptonlyprompt_uid. Website and scan tools declare their required brand-or-scan selection.get_leaderboardsaddsresource=hall_of_fame. Tools omit output schemas and link to the response types in OpenAPI. Collection operationIds becomelistOrganizationBrands,listBrandSegments,listServiceAuditPages,listServiceAuditKeyPages,listAuditCompetitors,listScanAuditCompetitorsandlistConversationMessages. REST scores retainstopic_idas deprecated. These are the approved pre-adoption changes; future removals follow Versioning. - 2026-10-17: The public API and MCP return data only. Composed sentences, enum labels, menus, cards and viewer affordances remain available to the first-party Command Center. Trend points add structured
breakdata; prompt tiles addstate, includingnot_applicable; competitor-site reads addreason; change targets addfilters. Work rows addbrand_idand deprecatetracked_domain_id; organization portfolios addkind. Nested lists state their totals, and evidence addsmeta. Brands, conversations, evidence, key pages, website scope and segments now page withlimit,cursorandnext_cursor. Hall-of-fame and scan-competitor cursors are active. Both conversation message reads return newest first, remove viewer read markers and replacebefore/afterwithcursor; this changes MCPget_conversation_by_idarguments too. Answers and prompts addq, withsearchretained as a deprecated alias. Deprecated operations sendDeprecationandSunset; MCP results carrydeprecatedandsunset, and output schemas are omitted. This closes the pre-adoption exception. - 2026-10-17: Overview and MCP
get_brand_overviewadd shared workcountsand frozenreport.actions_found.open_action_countis deprecated in favour ofcounts.open. Scheduled work is separate from Proposed, and Things to do is Your turn plus Proposed. Work addscompetitors_trackedandcompetitors_checked_7d;competitors_watchedis a deprecated alias of the latter. Figures carrybasisand their own numerator and denominator. Sources count pooled answers once and apply market and language filters, so their numbers can be lower. They add site populations, one verdict from cited pages, and anopeningfilter; muted sites are excluded. Negative-source rows adddomain_citations. Topics and keywords add tab counts. Website adds achangeobject next to the score. See Actions, Sources and Figures. - 2026-10-17: REST errors link their
typeto the code’s documentation on Errors and limits. This replacesabout:blankunder the pre-adoption exception. - 2026-10-17: API limits use sliding windows and a computed
Retry-After. MCP counts tool calls only and returnsrate_limitedtool errors withretry_after. Service tokens have a 120-per-minute limit. Service starts acceptIdempotency-Key, answer201withLocationon create and200withIdempotent-Replayed: trueon replay, and refuse changed payloads with422. Service tokens can read their workspace’s Snapshot atGET /v1/service/snapshots/{scan_id}. New API and service tokens include a checksum; existing keys keep working. See Errors and limits, service starts and API keys. - 2026-10-16: Topics in
/v1and MCPget_topicsremovestatus,status_label,page,citations,search_clicks,ai_visits,action,action_label,piece,pieces,open_action_idandwhy. Lists removecovered,cited,missing,sentence,statusesand thestatusparameter; sorts for the removed columns are also removed. Cards removecovered,total,cited,missing,missing_new,covered_changeandcited_change. One topic removesproblems,wins,unmeasured,value,page_checks,top_query,questions,questions_answered,question_total,sourcesandtasks. Sources’ topic chips removestatusandstatus_label, keepingband. Scores, demand, Cited share, own pages, frozen question coverage, live actions and suggested-topic evidence remain. This follows the pre-adoption exception. See Topics. - 2026-10-16: Trials show six untouched suggestions at once.
GET /v1/brands/{brand_id}/actionsand MCPlist_actionsreturn shown actions and count the rest insuggestions_kept. Starting, dismissing or deferring a suggestion frees a place; billing shows every held-back suggestion. Home and Actions show the same count. See Proposed. - 2026-10-16: Your first report uses every engine on your plan, including Perplexity and Microsoft Copilot, with the same website assessment, search reads and scoring checks as every weekly report. Confirmation refuses a prompt set too small to score before starting the report. See First scan.
- 2026-10-16: Topic reads and MCP
get_topicsadd AI bands, band filtering, score and citation-share sorts, filtered prompt counts and head result figures. Detail adds frozen question coverage, own pages with topic signals, per-engine prompt rates, keyword volume and rank, competitor domains, weekly Heralded Score history and live actions. Leaders use the Heralded Score, count ties as you leading and exclude topics without a measured competitor. Display volume keeps earlier-month readings. Actions accept atopicfilter. Existing page and status fields,tasks,problems,winsandunmeasuredremain available. See Topics. - 2026-10-16:
GET /v1/brands/{brand_id}/overviewand MCPget_brand_overviewaddlatest_read.scan_id, the weekly report’s scan ID. It can differ from the daily scan thatmeta.data_as_of.idpins. See Reads. - 2026-10-16: Action titles, details, notes and done-when read in plain words. An action changes only when the evidence changes what it suggests. See Actions.
- 2026-10-16: Each page’s
factsinGET /v1/brands/{brand_id}/pages/{page_id}and MCPget_pageaddload_ms: the milliseconds until the page’s main content shows on a simulated mobile load, PageSpeed’s Largest Contentful Paint. Weekly reports measure it on key pages; it isnullon other pages and where PageSpeed did not answer. See Page stats. - 2026-10-16: Changed: in reports frozen from now on, each page’s
category.name, thefacetsandcategoriesof the site map and pages reads, and each competitor’scategoriesinGET /v1/brands/{brand_id}/audit/competitorsand MCPget_competitor_sitesuse one fixed set of names, such asBlog,DocumentationandProduct, instead of folder and collection labels. Categories sharing a name and group are served once, their counts summed. See Pages. - 2026-10-16: Changed: in a weekly report, each segment’s figures count only the answers asked on that report’s market. Daily answers asked before a segment’s market changed sit out, so
GET /v1/brands/{brand_id}/overview,GET /v1/brands/{brand_id}/scoresand MCPget_brand_overviewandget_scoreskeep their values that week, withstatenot_comparableandchangenull, instead ofnullvalues. Every trend point’sbreak_labelnames a market change in words, such asRomanian answers are now asked in English and Romanian;breaks[].valuekeeps the market key. See Change. - 2026-10-16: Outreach actions on YouTube, LinkedIn, Medium and Reddit name the channel, author, publication or subreddit in
target_entity, such asreddit.com/r/notion, and/v1sources give those sites nopriority. - 2026-10-16:
GET /v1/actions/{action_id},GET /v1/brands/{brand_id}/actionsand MCPget_actionandlist_actionsofferprimary_verbreviewwhenever work needs your decision and has no other primary verb. Its job label is Answer questions for content questions and Review otherwise.GET /v1/brands/{brand_id}/changesand MCPlist_changesnet presence, citation and recommendation moves over the window, combining surviving gains and losses into one sentence per engine. - 2026-10-16: Perception quotes and page passages in
GET /v1/brands/{brand_id}/perceptionand MCPget_perceptionare served as plain text. Claim quotes use prose sentences, never table rows or headings. See Perception. - 2026-10-16: Removed:
prompt_slot_costfromGET /v1/actions/{action_id},GET /v1/brands/{brand_id}/prompts/{prompt_uid},GET /v1/brands/{brand_id}/scoresandGET /v1/brands/{brand_id}/sources/{domain}, and from MCPget_action. The field was not part ofGET /v1/brands/{brand_id}/actionsor MCPlist_actions. It has been0since tracking a prompt stopped being an action. - 2026-10-16:
GET /v1/brands/{brand_id}/evidenceand MCPlist_evidencelist the latest weekly report evidence Heralded holds for your brand: each item’sid,module,kind,target,segment,fact,observed_atand theplaysits owner offers. - 2026-10-15: Removed:
actionfrom each page ofGET /v1/scans/{scan_id}/auditand MCPget_auditwithscan_id, and fromimprove_pagesandcited_strong_pagesinGET /v1/shared/scans/{share_id}. Work wording comes from actions. - 2026-10-15:
GET /v1/brands/{brand_id}/overviewand MCPget_brand_overviewgaincompetitor_rank, yourpositionamong your tracked competitors by Heralded Score and the number of scored brands it isof;lean=trueleaves it out.GET /v1/brands/{brand_id}/scoresand MCPget_scoreswithgroup_by=competitorcarry the samecompetitor_rank. See Figures in the API. - 2026-10-15: Score v9.1 weights Search keywords within their countries, gives keywords without positive volume a small fixed weight, and keeps countries with unfinished research unknown. Stored v9.0 reports keep their frozen weights and version. Comparisons break between v9.0 and v9.1; AI-only reads stay on v8.0. API and MCP figures use the same weights. See The Search side and Versioning.
- 2026-10-14: Action reads and MCP
list_actionsandget_actionaddgrounds.targets, the prompt or keyword results the work targets. Each carrieskind,uid,engineandmetric. Work with grounds but no targets returns an empty list; actions predating structured grounds keepgrounds: null. See Action fields. - 2026-10-14: Topics in
/v1/brands/{brand_id}/topicsand MCPget_topicsaddpieces, every non-failed piece for the topic and segment, newest first.piecekeeps the newest for compatibility. Studio orders can request a similarity warning and confirm another order; a topic can have several pieces. See Content. - 2026-10-14:
GET /v1/brands/{brand_id}/topics/{topic_id}and MCPget_topicswithtopic_idaddproblems,wins,unmeasuredandvalue. Problems include prompt results by engine and keywords outside your top three positions, over four weekly reports regardless ofperiod. See Topics. - 2026-10-14: Overview, scores and competitor figures add
state: "pending"for Search while awaiting its first measurement. Values remainnull; All keeps the AI figures. The Command Center shows Calculating, and MCP returns the same state. See Headline figures. - 2026-10-14: Content action reach uses the demand value frozen with its topic verdict. Keyword check dates now match the report period’s rank results.
- 2026-10-14:
GET /v1/brands/{brand_id}/audit/map,GET /v1/scans/{scan_id}/audit/mapand MCPget_site_mapaddhostandunreadto each page.hostnames the host of a page outside the site you entered, subdomains included, and isnullon the site’s own pages.unreadistruefor a page the site lists that the report never read. Changed: in reports frozen from now on,httpandhttpsspellings of one address are one page, and only the entered site’s homepage hastypehome; other hosts’ homepages and language homepages havetypeother. See Website. - 2026-10-14: Each fact in
profile.factsofGET /v1/brands/{brand_id}/settingsand MCPget_settingsaddssource, the Content Studio piece a member saved it from, with itspiece_idandtitle. It isnullon a fact added in Brand settings or on Perception. See Brand facts. - 2026-10-14: Removed:
rank,src_order,targets,category,effort_weight,perception_lift_ptsandprimary_lift_ptsfrom reportmoves, andtotal_lift_ptsfromGET /v1/shared/scans/{share_id}. The report’sclaimsno longer includetop_moveorowned_content_move. - 2026-10-13: Scheduled actions in
GET /v1/brands/{brand_id}/actionsand MCPlist_actionsmove fromgroupscheduledtonew, with their start date inscheduled_for.schedulednow marks only Heralded’s own scheduled jobs. The Actions board hides dismissed actions whendismissedis omitted, and its old emptystacksfield is removed. See Action fields. - 2026-10-13:
GET /v1/actions/{action_id}and MCPget_actionreturn only settled text incontent_piece. During writing or checking, the previous settled version remains available, or draft fields arenullbefore the first settles.content_piece.stageusesordering,preparing_brief,questions,brief_review,writing,checking,your_review,applying,rewriting,approved,publishing,published,stopped,failedandpaused. See Content Studio. - 2026-10-13: Service tokens can start Full audits for one workspace scan credit through
POST /v1/service/audits, then read progress, Website results, the brief, collections, pages, key pages, maps and retained page text. Audit and Snapshot idempotency keys share the workspace’s namespace; reusing a key across products answers409 idempotency_key_reused. Customer API keys cannot start or read service audits. See Service audits. - 2026-10-13:
GET /v1/shared/audits/{share_id}reads a delivered Quick’s frozen Website, key pages and map without a credential. Base and Full results stay owner-only.GET /v1/scans/{scan_id}and MCPget_scannow read an Audit you ran withkind: auditandaudit_progress, also returned byGET /api/scans/{scan_id}. See Audit reads. - 2026-10-13:
GET /v1/account/free-auditand MCPget_free_auditreturn your Base audit allowance and its renewal time, separately from Snapshot. Quick audits start without an account and expire 30 days after delivery. See Free Base audit allowance. - 2026-10-13: New
GET /v1/brands/{brand_id}/audit/pages,GET /v1/scans/{scan_id}/audit/pagesand MCPlist_site_pageslist the crawl’s pages with filters bycategory,language,findings,access,statusandchanged, sort byfindingsandclicks, andfacetscounting every category and language under the filters. NewGET /v1/brands/{brand_id}/audit/key-pages,GET /v1/scans/{scan_id}/audit/key-pages, their/{path}reads and MCPget_key_pageread the key pages with their above-the-fold read, last four weeks and history. Changed: each page inpagesofGET /v1/brands/{brand_id}/auditaddscategory,language,findings,worst,claims_stated,claims_askedandchange, and the read takes the same filters. See Website. - 2026-10-13: New
GET /v1/brands/{brand_id}/audit/competitors,/audit/competitors/{key}andGET /v1/scans/{scan_id}/audit/competitors, and MCPget_competitor_sites, read competitor websites. Weekly reads carry the table, homepages, pricing, categories, activity and a paged feed filtered by competitor key and change type. An Audit’s owner reads its policy’s comparison: Base homepage screens, with Full adding proof and copy similarity. Unreadable pricing has null plans. - 2026-10-13:
GET /v1/brands/{brand_id}/auditand MCPget_auditaddwebsite, the Website score of the newest weekly report that finished reading your site, named inmeta.data_as_of: groups and areas with bands, every finding with its state, share, points off the score, fix steps and open action,fix_first,coverage,versions,changessince the last report, the weeklyseriesandnext_read_at.finding,finding_pages_limitandfinding_pages_offsetpage a finding’s pages. Changed:meta.data_as_ofon this read names that report once one exists.GET /v1/scans/{scan_id}/auditandget_auditwithscan_idadd an Audit’s ownwebsite,nullon a Snapshot, thebriefit was judged against and the brand’slook. NewGET /v1/brands/{brand_id}/audit/mapandGET /v1/scans/{scan_id}/audit/map, and MCPget_site_map, read the report’s site map in onelanguage, whole or onefolderat a time.GET /v1/brands/{brand_id}/pages/{page_id}andget_pagewith apage_idaddfindings,above_the_fold,against_brandandcopy_and_proof. See Website. - 2026-10-12:
GET /v1/brands/{brand_id}/settingsand MCPget_settingsaddprofile.profile.tone, how the brand’s pages sound:formalityisformal,conversationalornull, andcomplexityistechnical,plainornull. Both arenulluntil set. - 2026-10-12:
failure_reasonon scan rows ofGET /v1/scansandGET /v1/brands/{brand_id}/scans, onGET /v1/scans/{scan_id}and in MCPget_scanaddsservice_unavailable: a service Heralded relies on kept a Snapshot’s profile from drafting for 24 hours. The OpenAPI document now declares those values withx-extensible-enum, so treat one you do not know asother. See Scans. - 2026-10-12:
GET /v1/brands/{brand_id}/prompts,/prompts/{prompt_uid}and MCPlist_promptsandget_promptaddevidence, the stored evidence behind each prompt followed by the questions your team added to its topic, andsynthesised. Each evidence item in these reads and in a suggested topic’sevidenceaddsid, set on a question your team added,impressionsandsearches_mo. See Prompts. - 2026-10-12:
GET /v1/brands/{brand_id}/prompt-suggestionsand MCPlist_prompt_suggestionsare deprecated and return adeprecation_noticeand empty lists. Read suggested topics through/topics?view=suggestedorget_topicswithview=suggested. - 2026-10-11:
GET /v1/scans/{scan_id}/auditand MCPget_auditwithscan_idaddmoves, the scan’s priority actions, best first, with the fields of the shared read’smoves. A Snapshot’s are the ones its report shows. See Priority actions. - 2026-10-11: Each of the
movesinGET /v1/shared/scans/{share_id}gainsplay,groundsandgain, read as on an action. Changed:movesare the work Heralded’s plays would file for the scan: up to five, best first, at most two of one play and none with a low expected gain.perception_lift_pts,primary_lift_ptsandtotal_lift_ptsare always 0,rankandsrc_ordergive each move’s place, and a new report’sclaimscarry notop_moveorowned_content_move. See Priority actions. - 2026-10-11: Each action in
GET /v1/brands/{brand_id}/actionsandGET /v1/actions/{action_id}, and in MCPlist_actionsandget_action, gainsgain, its expected gain:bandishigh,mediumorlow, ornullon work you asked for, andaims_atsays what the work aims at. Changed:expected_impact_ptsis alwaysnullthere and on a competitor page’s queuedactions. Withgroup=new, this week’s work comes first, then the backlog, each with the actions you placed ahead of Heralded’s ranking, which no longer orders by severity. See Expected gain and ranking. - 2026-10-11:
GET /v1/actions/{action_id}and MCPget_actionaddtrail, what happened since the action was delivered: one entry per signal intracking, then themeasuredresult. Each entry has asignal, astateofgood,no_change,couldnt_checkorpending, asummary, areasonand anatdate. Changed:trackingon thesite_fixplay no longer listscited. Thepage_accessplay keepslive,crawledandcited. Tracking on outreach and correction requests no longer listslive; on a site positioning fix it lists onlymoved. See What happened since. - 2026-10-11: Each
placementsrow andbest_threerow of a brand read ofGET /v1/leaderboardsand MCPget_leaderboardsgainssides: the brand’srankandscoreon theaileaderboard and on thesearchleaderboard of the same panel and month.sides.searchisnullwhere that month has nosearchleaderboard, and on a Europe placement unless all seven country reads have a Search side.sidesisnullon a brand page Heralded has not rebuilt yet. See Brand and source pages. - 2026-10-11: Each action in
GET /v1/brands/{brand_id}/actionsandGET /v1/actions/{action_id}, and in MCPlist_actionsandget_action, gainsgrounds,done_whenandtracking.groundscarries itskind,cause, datedevidenceand, for best practice, the publisherguidance. It isnullon an action filed before actions carried their grounds.GET /v1/actions/{action_id}andget_actionalso gainchecklist, the steps you follow where Heralded drafts and applies nothing. See Action fields. - 2026-10-11:
GET /v1/actions/{action_id}and MCPget_actionadddismissal_reason, why a member put the action away:not_now,too_much_work,not_relevantoralready_done. It isnullwhen no reason was given and once the action is restored. See Actions. - 2026-10-10: Brand and source reads of
GET /v1/leaderboardsand MCPget_leaderboardslist Europe placements. Aplacementsrow can havefilters.countryset toeurope, with the brand’s place and score on that Europe leaderboard, or the source’s place and citations there. Questions, highlights, sources, history, engine places and a source’s pages, engines and brands count the country leaderboards only, so Europe adds nothing to them. See Brand and source pages. - 2026-10-10: Changed: a Europe leaderboard compares with the previous month’s.
GET /v1/leaderboardsand MCPget_leaderboardswithcountry=europenow returnprevious_month,previous_rank,rank_change,movers,dropoutsandscore_series, and a brand’s change is no longer always a first reading. See Europe. - 2026-10-10:
GET /v1/leaderboardsand MCPget_leaderboardsacceptcountry=europe. An industry’s Europe leaderboard pools its leaderboards in the United Kingdom, Germany, France, Spain, Italy, the Netherlands and Romania for each month all seven published, and the Europe hub lists brands across industries with their Europe places.origin_countrystill takes ISO codes only. Facetspageslist Europe pages at/leaderboards/<industry>/europe/. Changed:facets.countrieslists a country only once it has a published panel, and never listseurope. See Europe. - 2026-10-10:
GET /v1/leaderboardsand MCPget_leaderboardstakeside:all,aiorsearch. The default isall. Changed: a leaderboard month whose run read Google scores on v9.0, and itsheralded_score, Mentioned, Recommended, places, movers and history are then the weighted score of both sides, not the AI side alone. A month that did not read Google reads as before. Month-over-month comparison breaks at v9.0: forallandsearch, the first v9.0 month has noprevious_month,previous_rankorrank_change, and itsscore_seriesstarts there. Theaiside continues unbroken.searchreturns an empty read for a month without Google results, andenginealways reads the AI side. Brand and source pages readall. See Leaderboards and Score versions. - 2026-10-09:
GET /v1/brands/{brand_id}/overviewacceptslean=true, which leaves outrivals,sources,actions,attributionandreadinessand reads none of them. Every other field is unchanged, and the default response and MCPget_brand_overvieware unchanged. See Figures in the API. - 2026-10-09:
GET /v1/brands/{brand_id}/overview,/scores,/competitorsand/topics, and MCPget_brand_overview,get_scores,list_competitorsandget_topics, takeside:all,aiorsearch. The default isall. Changed:heralded_score,mentionedandrecommendedfollowside, so a brand with search observations gets the figures of both sides weighed together unless it passesside=ai. Without them,allequalsai. Each of those reads gainssides_available, which listssearchwhen a report in the period checked keywords, and the overview gainssides, the three figures on each side. A topic’sscoresgainallandsearchbesideai, andleaderandwinnersfollowside. See Sides. - 2026-10-09: New
GET /v1/brands/{brand_id}/keywordsand/keywords/{keyword_id}, and MCPget_keywords, read the keywords you track: monthly searches, your best rank, the results that name you, each keyword’s figures with their range, the top 10 of the latest check, the prompts that make AI search it and the actions about your pages. See Keywords and Search visibility. - 2026-10-09: On agency plans and custom offers, a brand no longer reserves prompts and the prompt ceiling ends: segments are the allocation, each holding 15 topics.
prompts_reservedin/v1/brands/{brand_id}/settings,/v1/organizations/{organization_id}/usageand MCPget_settingsandget_usageisnullfor every brand, andprompts.poolis three for each topic the live segments can hold. Fields stay the same. See Topics and prompts. - 2026-10-09:
GET /v1/brands/{brand_id}/reviewsand/reviews/{review_id}, and MCPget_reviews, return platform ratings and counts, reviews and reply state. Core receives platform ratings and counts; Plus also receives its review list and work.featuresstates which Plus features are available. See Reviews. - 2026-10-09:
/v1/brands/{brand_id}/sourcesand MCPlist_sourcesinclude Google ranking and monitoring sites,found_via,recommends_you,read_by_searchers,recommendingandchannels. Filter byfound_viaand sort by either new measure. See Source measures. - 2026-10-09: Brand leaderboard reads and MCP
get_leaderboardsremove the individual-pointhistorymodule and its paging parameter.history_serieskeeps monthly rank, score, Mentioned and Recommended values per placement. Boardmonthsstays available. See Brand and source pages. - 2026-10-09: Each competitor in
GET /v1/brands/{brand_id}/competitors,list_competitorsand the overview’srivalsgainsmost_said_forandmost_said_against, its positive and negative opinion with the most holders. See Reputation. - 2026-10-09:
GET /v1/brands/{brand_id}/reputationgainsopinions, what voices think about the brand, each withheld_by,kinds,engines,changeandaction_id.GET /v1/brands/{brand_id}/reputation/opinions/{opinion_id}returns one with itsholdersand their passages, and MCPget_reputationwithopinion_idreturns it asopinion. See Reputation. - 2026-10-09:
GET /v1/brands/{brand_id}/reputation,/reputation/claims/{claim}and MCPget_reputationread Understood and Praised from AI answers and from the pages AI cites and Google ranks that name the brand. They carryunderstoodandpraisedas 0.63 × the AI part + 0.37 × the web part,partswith each, andfacts, the perception claims withaiverdict counts andelsewherecounts of pages that agree or contradict, and the claim read addsdocuments. Under ten pages the two figures are the AI part alone. In/overviewand MCPget_brand_overview,understoodandpraisednow carry the same blend, while/scoreskeeps the AI part. See Reputation. - 2026-10-09: Score v9.0 adds the Search side. A weekly report that checked your tracked keywords on Google is v9.0, and every other read stays v8.0. Trend instrument keys add nullable
sides, the sides a report observed, andkeyword_set_hash, which changes when the keywords a report checked change without breaking the series. Served scores stay the AI side’s. See The Search side and Versioning. - 2026-10-09:
/v1/brands/{brand_id}/topics/{topic_id}and MCPget_topicswith atopic_idaddbuyer_questions, the questions buyers ask within the topic, up to 12 for each segment it is tracked in. Each has itstext,asked_bywithkind,enginesandoften,google_rankandanswered_by_page. See Topics. - 2026-10-09: On a suggested topic in
/v1/brands/{brand_id}/topics,/topics/{topic_id}and MCPget_topics,actionsare those of the segmentsegmentnames, or the Default segment without one. Fields stay the same. See Topics. - 2026-10-09:
/v1/brands/{brand_id}/topics,/topics/{topic_id}and MCPget_topicsaddarchived_aton archived topics, the latesttopic_segments.status_sinceacross archived segments, andengines[]on suggested-topic evidence from AI background searches. Other evidence has an emptyengineslist;archived_atis null on tracked and suggested topics. See Topics. - 2026-10-09:
GET /v1/brands/{brand_id}/topicsand MCPget_topicslist the topics you track instead of the content check’s topics, and/topics/{topic_id}reads one. A topic’sidis its UUID, and a suggested topic’s iss:and its suggestion id.viewselectstracked, the default,suggestedorarchived. Rows keeptopic,status,page,demand,citations,search_clicks,ai_visits,actionandpiece, nownullon a suggested topic, and addstate,need,segments,scores,leader,prompts_count,keywords_count,why_labels,best_to_trackand, on a suggested topic,demand_measured,evidence,coverage,actionsandadds. The list addssides_available. One topic addspages,keywords,winners,by_segment,tasksandsides_available. Earlier topic ids stop resolving, andcontent_topicon answers and sources takes a topic’s UUID.group_by=topicin/scoresand MCPget_scoresreturns tracked topics, and a prompt addstopic_detail. See Topics. - 2026-10-08: On Core and Plus,
promptsin/v1/organizations/{organization_id}/usageand MCPget_usagecounts by topic.usedis the active prompts of tracked topics your reading brands read,poolis three for each topic their live segments can hold, andfreeis the pool lessused.prompts_reservedisnullfor every brand there and in/v1/brands/{brand_id}/settings. Agency and custom-offer workspaces keep their allocation figures. Fields stay the same. See Topics and prompts. - 2026-10-08: Leaderboards and MCP
get_leaderboardscarry the modules their pages use. Boardhistory, brandcompetitors,engines,won,missedandevidence, and facetscombinationsare removed. Brand and source reads are current only, withoutmonth; hubs with an engine or month return an empty read. Cited-page rows appear only on all-engine panels and source pages, capped at 20 positions per source before withholding. Source pages combine those capped panel lists. Page counts and the board’smonthsremain available. See Leaderboards. - 2026-10-08: On
/v1/leaderboardsand MCPget_leaderboards,origin_countryandaudiencenarrow a leaderboard’s lists without ranking the selection again. Each brand keeps its panel place, rank change and score series, and movers, drop-outs and history narrow to the selected brands. The leader, questions and their winners, each engine’s top three, sources’ brand mentions, the answer population andmonthsstay those of the whole leaderboard under any filter. Curated lists read their leaderboard under their filters. Routes, fields and paging are unchanged. See Scores and places. - 2026-10-08:
GET /v1/brands/{brand_id}/prompt-suggestionsand MCPlist_prompt_suggestionsnow return Search Console and recurring engine-search evidence phrases, including those assigned to tracked topics. Suggestions are no longer drafted before adoption. Response fields stay the same. Clicks and position come from Search Console where available, otherwise they are null. See Prompts. - 2026-10-08: Brand overview adds nullable
attribution, with a UTC calendar month, total classified contacts and counts by voice and named platform. Plus brands with a HubSpot attribution property receive this projection in the API and the overview assistant tool. See HubSpot. - 2026-10-07: Leaderboard facets add
origins, sorted ISO-2 brand-origin codes for brands with a measured score in at least one current published panel. See Leaderboards. - 2026-10-07: The leaderboard facets
combinationsfield now lists the same panel, hub and curated-list pages aspages. It no longer lists computed filter combinations. See Leaderboards. - 2026-10-07: Leaderboard facets add
pages, with panel, hub and curated-list paths, titles, indexing status, featured positions and leaders. Matching leaderboard filters serve saved hub and curated-list results, refreshed after publication, included-panel corrections and reducer version changes. MCPget_leaderboardsreturns the same results and catalogue. See Leaderboards. - 2026-10-07: Panel brand rows add
previous_rank,rank_change, entrystateand monthlyscore_series. Boards addprevious_month, pagedmovers.risersandmovers.fallers, anddropoutsthat distinguish unranked brands from roster departures. Brand placement history adds monthly rank and availability state, including missing readings and roster gaps. MCPget_leaderboardsreturns the same fields. See Monthly change and history. - 2026-10-07: Leaderboard facet combinations add nullable
leader, the brand that leaderboard ranks first, withbrand_id,name,sluganddomain. The filtered leaderboard read addsmonths, every month its history covers, oldest first. MCPget_leaderboardsreturns the same fields. See Leaderboards. - 2026-10-07: Score v8.0 uses engine usage weights and a refit calibration. Stored reads and issued Snapshot reports with frozen per-answer facts serve v8.0. Reports issued on v6.0 and v7.0 remain available. See Versioning.
- 2026-10-06: Placements on cross-industry leaderboard rows add
score, the brand’s Heralded Score on that industry’s leaderboard, andranked, the number of brands that leaderboard ranks. Their rows addstrength, the best such score on a leaderboard ranking at least five brands. A list orders by best place, then by how many industries share it, then by name, and filtered to one brand origin, bystrengthfirst. MCPget_leaderboardsreturns the same fields. See Leaderboards. - 2026-10-06: Only score version v7.0 is served. A shared scan on v6.0 now returns
410withcodescan_version_unsupported, as older versions already did. See Versioning. - 2026-10-06: The legacy
/public/categoriesroutes are removed. Read public leaderboards through/v1/leaderboards, including facets and brand and source details. See Leaderboards. - 2026-10-05: Public leaderboard sources, cited pages, brand sources, questions and quotes withhold a stable sample keyed by entity kind, identity and measurement month. The bottom 70% of the SHA-256 range is withheld, with position 1 always sent and positions beyond 20 omitted. The existing
withheldfield reports the withheld positions in the full list. Totals and response shapes stay unchanged. REST and MCP use the same sample, including brand and source pages. See What the public leaderboards show. - 2026-10-05: The brand leaderboard read and MCP
get_leaderboardsaddquestionswith per-question place and named competitors,engine_rankswith average rank, ranked leaderboard count and best rank,highlightswith selected sentence quotes and their question and leaderboard context, andhistory_serieswith monthly score, Mentioned and Recommended values per placement. Each new module has its own paging offset. Existingwon,missed,competitors,engines,historyand their paging parameters remain available.evidencekeeps its row shape and selects the same quotes ashighlights. See Brand and source pages. - 2026-10-05: Leaderboard sources, cited pages, a brand’s sources and questions won and missed, and evidence quotes add
withheldand send only positions 1–2 and 7–20, with positions 3–6 withheld on the server. Totals count the full list, offsets keep their original positions, and these modules stop paging at position 20. Rankings, engine lists, placements, competitors and history keep ordinary paging. MCPget_leaderboardsfollows the same rule. See What the public leaderboards show. - 2026-10-05: Leaderboard facet combinations add nullable
featured_position, the curated display order for measured combinations. MCPget_leaderboardsreturns the same field. See Leaderboards. - 2026-10-05: Leaderboard brand rows add
engines, each engine’s Mentioned and Recommended for the filter, withnullvalues where the engine did not read the brand. Source rows addanswers, the answers in the filter citing the source, besidecitations. Question rows addlanguage. MCPget_leaderboardsreturns the same fields. See Leaderboards. - 2026-10-05: Public leaderboard reads add
GET /v1/leaderboards,/leaderboards/facets,/leaderboards/brands/{slug}and/leaderboards/sources/{domain}, with published measurements, independently paged modules, IP and site-key limits, caching and revalidation. MCP adds token-authenticatedget_leaderboardsover the same reads. See Leaderboards. - 2026-10-05: Trend instrument keys add nullable
passes. A recorded pass-count change prevents comparison; a missing count keeps comparisons unchanged. See Change. - 2026-10-05: Single pages and MCP
get_pageaddfunnel_series, the funnel on each weekly report’s 28-day window, oldest first, back as far as your plan’s history reads. Each point carriesstart,end,search_clicks,crawled,fetched_live,citedandai_visits, withnullfor a measurement the report did not record. See Pages, topics and Audit. - 2026-10-05: One page and MCP
get_pageaddtakes, withwith_takes,takes_limitandtakes_offset: the passage each answer lifted from the page and the claim it supported, one per prompt and engine. Takes are kept with each scan, soas_ofreturns the same takes after a page edit, a later scan or answer-text expiry.unavailablecounts citing answers whose take could not be kept. See Pages, topics and Audit. - 2026-10-04: Page funnel windows add
history_daysandclamped. Crawler, Visits from AI and Search Console measurements read back 90 days on Core and 13 months on Plus,as_ofpins included, and a funnel on an older report hasnullfor them. See History. - 2026-10-04: Shared scans add
source_tier_rollups[].citation_share_pctandbrand_citation_summary.owned_share_pct,competitor_share_pctandindependent_share_pct. Race rows addgap_pts, the row’s Heralded Score minus the subject’s. See Scans. - 2026-10-04: Segment engine rows add
figure, and engine-screen Mentioned and Recommended cards addkpis[].figure, in the API and MCPget_segments. They share the answer-based values, ranges and measurement states of scores filtered to the segment and grouped by engine over1w. See Segments in the API. - 2026-10-04:
GET /v1/brands/{brand_id}/scoresand/competitors, with MCPget_scoresandlist_competitors, acceptcursorand returnnext_cursorfor the Engines table, engine pane competitors and Competitors leaderboard they page.GET /v1/organizations/{organization_id}/brandsrows adddata_as_of, the scan their figures read, to pass asas_ofto that brand’s reads. MCPlist_portfolioserves the workspace’s portfolio. See Errors and limits and Connect an assistant. - 2026-10-04: Audit page rows and MCP
get_auditadd a fifth access gate,ai_crawler_refused. It fails where Cloudflare verified that an AI crawler was refused on the page or got not found from a live page. Changes and MCPlist_changesadd the insight kindai_crawler_refused, whose work is atechnical_fixaction. See Page stats. - 2026-10-04: Page funnels add
crawler_bots, counting served requests per bot with verification true or unknown, including search engines. Known-unverified AI requests remain infunnel.unverified; existing all-served bot totals keep their meaning. See Pages, topics and Audit. - 2026-10-04: Owned page lists, single pages, Audit page rows and MCP
get_pageaddfunnel, with one dated window for search clicks and impressions, AI crawls, live fetches, citations, Visits from AI, blocked, not-found and unverified requests, search-engine crawls and crawler sources. Unmeasured counts arenull; WordPress requests with unknown verification count toward AI crawls and live fetches. See Pages, topics and Audit. - 2026-10-04: Page crawler breakdowns add
category, also served by MCPget_page. Counts use daily source precedence so a connection outside the plugin replaces overlapping plugin counts. See Pages, topics and Audit. - 2026-10-04:
GET /v1/brands/{brand_id}/prompt-suggestionsand MCPlist_prompt_suggestionsaddsuggestions, the picker’s list for tracking a new prompt, with each entry’stext,intent_labelandreason. It is not paged and does not changeitems. See Connect an assistant. - 2026-10-04: Single prompts and MCP
get_promptadd each engine’s display name and the four measured states for its latest answer, including its answer id and read date. The facts follow the same latest-answer rule andas_ofscan pin as the existing engine state. See Prompts. - 2026-10-04: One owned page, topic and competitor, including their MCP reads, add
citation_evidenceandunavailable_scans. Competitor-page panes add the same fields andmeasurementunavailablewhen the period has incomplete citations and no evidence for a known competitor’s page. See Figures in the API. - 2026-10-04: Sources and MCP
list_sourcesacceptsort=priorityand return each site’spriorityposition andpriority_reason.with_summary=trueadds up to three actionableworth_pursuingsuggestions andworth_pursuing_total. See Sources in the API. - 2026-10-04:
GET /v1/brands/{brand_id}/changes,/prompt-suggestionsand MCPlist_changesandlist_prompt_suggestionsacceptcursorand returnnext_cursor. See Errors and limits. - 2026-10-04: Work jobs and MCP
get_workaddholder, who holds the job’s action, with the same values asholderon actions. See Action fields. - 2026-10-04: Before launch, every
answers_linkdrops itstotal: it carries thehreforurlof the answers alone, and the Answers page owns the count. This covers every/v1read and MCP tool that returns one. - 2026-10-04: The overview and MCP
get_brand_overviewaddheralded_score_band,score_bands,score_context,since_startedandverified_actions, andwith_diagnosis=trueaddsdiagnosis. One action and MCPget_actionacceptas_ofand add the action’s state, verbs, job, costs, impact, demand, schedule, assignee, current draft and its recipient, the application’s planned value and effect, and the weekly reports that raised it. Work jobs addaction_id,action_kind,progressandcurrent_step. The overview and Changes pin the latest completed scan by default, daily updates included, and name it inmeta.data_as_of; the overview’s figures still describe the weekly reports in the period. Changes under that pin include the daily updates since the latest weekly report, as Home does. See Figures in the API and Action fields. - 2026-10-04:
GET /v1/shared/scans/{share_id}can answer410withcodereport_retired,domainandrescan_urlfor a report retired with Heralded’s pre-launch data. See Errors and limits. - 2026-10-04:
cited_page_keyon the answers list and MCPlist_answers: the document key of the page thecited_pagefilter matched. See Prompts and answers in the API. - 2026-10-04: Prompt list cursors issued before 4 October 2026 return
400 invalid_cursor; request the first page again. - 2026-10-03: Perception, scores, sources, cited pages, owned pages, topics and Audit add the labels, summaries, menus and evidence their pages and panes show. Scores add opt-in axis panes; owned pages add opt-in Search Console metrics. Lists add search, sorting and evidence paging. The existing MCP tools return the same fields and accept the same parameters. See Figures in the API.
- 2026-10-03: Before launch,
/v1source ownership counts discovered competitors’ sites as competitor-owned. This includes non-channel brands discovered across the selected period with at least three naming answers, alongside the competitors you track today. Sources, cited pages, engine panes and MCP use the same ownership. See Sources. - 2026-10-03: Scores and MCP
get_scoresadd optional Engines table and pane reads, with counts, sentences, prompt evidence and sources. Competitors and MCPlist_competitorsadd filters and an optional page read with leaderboard, discovered cells, share-of-voice bar and brand roster capacity. One competitor and MCPget_competitoradd measurement and comparison sentences, capacity, answers link and an optional competitor-page pane with its explanation, prompts and queued actions, including daily-only discoveries under the same scan pin. See Figures in the API. - 2026-10-03: Prompt lists add the composed
status_notefor paused and archived prompts andcellswith their engine readings, answer ids and measured-day labels. MCPlist_promptsreturns the same fields. See Prompts. - 2026-10-03: Prompts add period scores, trends, engine marks, taxonomy, filter menus and table selection. Single prompts add the composed sentence, tiles, engine cards and linked work. Answers add four-axis states, highlights, citation titles, filter menus and table selection; single answers accept
as_of. Scores add optionalcardsfor the Prompts band. The existing MCP tools return the same additions. See Prompts and answers in the API. - 2026-10-03: Brand settings and MCP
get_settingsaddprompts_used, the brand’s active prompt count, andprompts_reserved, its current reservation ornullfor the shared pool. Brand grants can read this meter. Workspace usage still requires workspace access. See Usage in the API. - 2026-10-03: Segment reads add the complete comparison table, a segment’s figures, trend and prompt evidence, and its selected engine’s prompt answers. Read them through
GET /v1/brands/{brand_id}/segments,/segments/{segment_id}and/segments/{segment_id}/engines/{engine_id}, or MCPget_segments. See Segments in the API. - 2026-10-03: Read the Content read of a Snapshot or Audit you ran through
GET /v1/scans/{scan_id}/audit: every audited page ranked best fix first with what it fails, the page checks, the site’s readability and the topics the site has no page for. Only the account that ran the scan reads it, and the shared read of a Snapshot never carries it. MCPget_audittakesscan_idin place ofbrandfor the same read. See Scans in the API. - 2026-10-03: List the Snapshots you ran through
GET /v1/scans, with the rows, paging and cursor of a brand’s scan list. Scan rows adddomain,share_id,progress_pctandfailure_reason, one ofstuck_no_progress,brief_abandoned,insufficient_engine_signal,cost_cap_exceeded,report_inputs_missingorotheron a failed scan, andGET /v1/scans/{scan_id}addsfailure_reason. See Scans in the API. - 2026-10-03: Answers add an optional
periodtoGET /v1/brands/{brand_id}/answersand MCPlist_answers. Omitting it keeps all weekly and daily answers. Finished answers read frozen measurements. Brands named in answers now come from the detection frozen with each scan, not a text match: thenamesfilter matches the brands detected in an answer and the tracked competitors it names, andrivals_nameduses the frozen detection. - 2026-10-03: Read brand profiles, owned domains, tracked competitors, autonomy, connection status and segment configuration through
GET /v1/brands/{brand_id}/settingsand/segments, with MCPget_settings. Workspace members can read prompt and credit use throughGET /v1/organizations/{organization_id}/usageand MCPget_usage.GET /v1/organizations/{organization_id}/brandsreturns portfolio rows with the last week’s figures, paired changes and actions waiting;managed=trueselects the manager’s active managed accounts. Brand grants alone open neither workspace read. - 2026-10-03: List a brand’s weekly reports, daily updates and Snapshot through
GET /v1/brands/{brand_id}/scans, and read one scan’s progress or issued Heralded Score, Mentioned, Recommended and readiness throughGET /v1/scans/{scan_id}, with MCPget_scan. Read a delivered report as its link holders see it, with no API key, throughGET /v1/shared/scans/{share_id}. See Scans in the API. - 2026-10-03:
GET /v1/brands/{brand_id}/overviewand MCPget_brand_overviewaddnext_weekly_scan_at,next_daily_scan_at,daily_scans_since_weekly,open_action_countandreadiness. See Figures in the API. - 2026-10-03: Read Perception’s statement, positioning rows, claims with their verdicts and trend, negative prompts and sources, and best quotes through
GET /v1/brands/{brand_id}/perception. Read one claim through/perception/claims/{claim}. MCPget_perceptionserves either read with an optionalclaimkey. Both accept the period, shared figure filters andas_of. See Perception in the API. - 2026-10-03: Sources adds
read_pages_naming_you, citation share, answers citing, authority and opportunity score. Sources reads report citation evidence availability and how many reports lack it; unavailable counts and history points are blank.citations_naming_youis deprecated and keeps counting all citations naming you, including unread pages. Sources and cited-page rows accept shared filters, includingengine. Read a site’s pane throughGET /v1/brands/{brand_id}/sources/{domain}andget_source, and cited-page rows throughGET /v1/brands/{brand_id}/cited-pagesandlist_cited_pages. Overview’s top sources add citation share and the read-pages naming-you count. - 2026-10-03: Read one action’s steps, thread, drafts, application state and evidence through
GET /v1/actions/{action_id}and MCPget_action. Read agent jobs, the next scan, weekly tallies and the Herald’s week throughGET /v1/brands/{brand_id}/workand MCPget_work. See Action fields. - 2026-10-03: Read one competitor through
GET /v1/brands/{brand_id}/competitors/{key}and MCPget_competitor, with score, trend, head-to-head figures, prompts won and lost, engines, cited pages and tracked since. Competitor lists include discoveries across the selected period and add a separatechannelslist. - 2026-10-03:
GET /v1/brands/{brand_id}/scoresandget_scorestakeengine,type,intent,topic,segmentandpromptfilters and agroup_byofengine,intent,type,topic,segment,promptorcompetitor. A grouped read addsgroups, each with itsgroupand its five figures. See Figures in the API. - 2026-10-03: Read your own pages through
GET /v1/brands/{brand_id}/pagesand/pages/{page_id}, Content’s topics throughGET /v1/brands/{brand_id}/topicsand/topics/{topic_id}, and Audit throughGET /v1/brands/{brand_id}/audit, with MCPget_page,get_topicsandget_audit. AI visits read the newest weekly report in the period that read the GA4 property connected now. - 2026-10-03: Read one prompt’s period score and trend, each engine’s latest answer, competitors, top sources, tracking date and status through
GET /v1/brands/{brand_id}/prompts/{prompt_uid}and MCPget_prompt. - 2026-10-03: In
GET /v1/brands/{brand_id}/competitorsandlist_competitors,share_of_voice_pctand ashare_of_voicerow’spctarenullfor a tracked competitor that no answer in the period asked about or named, where they read 0. - 2026-10-03: Computed reads add normalized query metadata and an
as_ofscan pin. Prompts, answers, sources, AI visits and actions add cursor pagination. MCP tools accept the same parameters and return the same metadata. Authenticated responses state their rate limit, 429 bodies carry its numbers, and REST problems include the request id. See Errors and limits. - 2026-10-03: Read Home’s Changes through
GET /v1/brands/{brand_id}/changesand MCPlist_changes. Read Discover recommendations, provenance, form and demand throughGET /v1/brands/{brand_id}/prompt-suggestionsand MCPlist_prompt_suggestions. - 2026-10-02: Every response has
Cache-Control: private, no-store.
Reference
API changelog
Every change to the v1 API, newest first.
Within v1, Heralded adds routes, fields, MCP tools and enum values. Versioning states the rules. Each change appears here with its date.