Reads
The API calls each weekly report a read. Scores, overview, competitors, sources and AI visits takeperiod, one of 1w, 4w, 12w or all. The default is 1w.
Every response carries a period descriptor. preset names your choice, reports counts the weekly reports included, and first_answer_at and last_answer_at give the true dates of their answers, including pooled daily answers. excluded_reports counts reports left out because the period crosses a change in how Heralded reads answers.
Scores and overview return figures pooled over that period. Each figure’s trend has one point per weekly report over the latest 12 reports, or the whole selected period if it is longer. It can extend beyond period. The overview’s latest_read, headline.text, answers_citing_you and sources_mentioning_you belong to the latest weekly report, regardless of period.
The overview also states where the brand stands now, whatever period you pick. next_weekly_scan_at and next_daily_scan_at are null while the brand is paused or its organization funds no new scan. daily_scans_since_weekly counts the daily scans whose answers no weekly report has pooled yet, open_action_count the open actions excluding setup, and readiness how many pages AI engines can read, cannot read or could not be checked in the latest crawl.
The overview carries what Home says about the Heralded Score. heralded_score_band names the band of score_bands the score falls in. The score bands says how the API names them. score_context states what the latest weekly report’s score was read from: the brand name, prompts, engines, answers and the dates of its first and last answer. since_started gives the score’s move since the first weekly report on the current score version, its sentence and one point per weekly report. verified_actions lists the newest three delivered tasks that verification credited with a gain, and total counts them all. Set with_diagnosis=true to add diagnosis: the prompts a tracked competitor wins over the last week and you do not, the third-party sources citing competitors and never you, and the drafts ready to answer them.
The overview’s default pin is the latest completed scan, daily updates included, and meta.data_as_of names it. Its figures still describe the weekly reports in the period. Pass that id as as_of to Changes, scores and the other reads to keep one page on the same scans, the daily updates Changes shows included.
Each trend point has its report date at, value and range, answer count, state and a readable break_label when the reading method changes.
Until a brand’s first report completes, the descriptor counts zero reports and each figure has state: "not_measured" with a null value. When a figure is empty lists every reason one can be.
Filters and groups
Scores take the filters the app’s pages take:engine, type, intent, topic as a topic id, segment as a segment’s label, and prompt as a prompt id. Every figure, its change and its trend then read only the answers the filters keep.
group_by also states the five figures per engine, intent, type, topic, segment, prompt or competitor, under the same period and filters. The response keeps the whole figures and adds groups. Each group’s group names the value it groups on and leaves the other dimensions null. A competitor group names the brand by competitor and brand_name, and is_you marks your own. A group exists for each tracked prompt’s value, so a group can have no answers in the period. Without group_by, groups is null.
GET /v1/brands/{brand_id}/scores and MCP get_scores also take include=engines for the Engines table, or include=engine with an engine filter for that engine’s pane. The engines and engine fields carry the same counts, score marks, trends and sentences as those surfaces. The pane includes competitors, strongest and weakest prompts and its five most cited sources. sort, direction, limit and offset select table rows or the pane’s competitor page. with_menus=true adds the four prompt filter menus in menus. These additions leave the existing figures and groups unchanged and follow the same as_of pin.
The engine pane’s sources use the same citations, citation_share_pct, read_pages_naming_you, group and ownership as the Sources read under the engine filter. names_you is null when no read page could establish whether the source names you.
Headline figures
Each is in points from 0 to 100 and carries a 95% range,low to high.
The Heralded Score, Mentioned and Recommended leave out prompts that name the brand. Every figure carries
value, low, high, answers, numerator, denominator, state, change and trend. The score has no numerator or denominator. Understood and Praised count answers naming the brand that were measured for that figure in their denominator.
state is measured, too_few_answers, calibrating, not_comparable or not_measured. An unmeasured value is null, never zero. A calibrating figure can have a value and a change, but its baseline has fewer than four reports, so do not call the trend settled.
Citations
Both come from the latest read and are{count, of, pct}: the count, what it is out of, and the share in points. pct is null where of is zero. Answers citing you and sources mentioning you defines them.
Change
A change carriesdelta, low, high, real, direction, baseline and cells_unpaired. It compares the period with the preceding reports, as many as the period holds and at least four when available. baseline states its report count and true answer dates. cells_unpaired counts prompt and engine cells measured on only one side.
Judge change by real alone. real is true where a paired test over the cells both reads measured says the figure moved. Where real is false, call the figure unchanged, whatever delta says. Two reads’ ranges can overlap while the figure really moved, and ranges that don’t overlap are not a test either.
A change is null without a baseline, without enough measured answers, or when the comparison is not comparable. Its values can also be null where no cells can be paired. Change has the test and every case.
Competitors
share_of_voice states the population, answer count, excluded answers and each brand’s numerator and denominator. Its rows identify each brand by name and is_you. Its population is all_answers, or weekly_answers when pooled daily answers did not receive the brands-named reading. discovered lists untracked brands with name, domain, value, low, high, answers and state. Their Heralded Score uses the same period’s answer rows and estimator as tracked brands. A measured, comparable period needs at least three answers naming the brand; below that, state is too_few_answers and the value and range are null. Discovery includes every weekly scan in the period. channels lists platforms separately, with name, domain, mentioned, answers and prompts, without a score.
The competitor list and MCP list_competitors accept the shared figure filters. Set with_page=true to add page, the Competitors page’s sentence, share-of-voice bar, leaderboard, brand roster capacity and discovered and channel cells. sort, direction, limit and offset select the leaderboard page; discovered_limit and discovered_offset select the discovered and channel pages. with_menus=true adds the prompt filter menus. All measured sections follow as_of; roster capacity follows the current plan and tracked competitors. The page read’s default pin is the latest completed scan, including daily scans, so its panes can open daily-only discoveries. The figures still describe the selected weekly period.
GET /v1/brands/{brand_id}/competitors/{key} and MCP get_competitor read one tracked or discovered competitor. key is its brand key or name, such as linear. Both accept period and the figure filters engine, type, intent, topic, segment and prompt.
The response includes score, trend and weekly history, head-to-head versus and figures, all lost and won prompt rows, engines, and tracked_since. Each comparison’s gap is your value less the competitor’s. lost means the competitor scores above you, and won means you score above it. Ties and missing scores appear in neither. pages lists the five most cited pages on the competitor’s site; pages_total counts every cited page on that site. Counts and page titles come from the scan’s frozen citations. An unknown key or your own brand returns not_found.
citation_evidence is complete, partial or unavailable, and unavailable_scans counts the period’s reports that lost citations before they were frozen; counts derived from citations are floors unless it is complete.
sentence and versus_sentence describe the measurement and comparison. capacity and can_track state the current brand roster’s size and limit. answers_link opens the answers naming that competitor under the same period and filters. These fields also arrive through MCP get_competitor.
The competitor read and MCP get_competitor also take page_url to add that rival-owned page’s pane in rival, including its explanation, cited prompts, queued actions and answers link. With page_url, key can be the page’s hostname instead of its competitor’s brand key. The read also opens a URL found only by an unpooled daily scan, with measurement=daily_only and its pending note. Without as_of, this mode pins the latest completed scan, including daily scans. With it, both the weekly population and unpooled daily discoveries stop at that scan’s completion and id; a URL found only later returns not_found. The competitor’s figures and cited pages still describe the selected weekly period. The Sources cited-page read keeps its existing shape and field meanings. A rival page with no available evidence in an incomplete period returns measurement unavailable instead of 404. An unknown competitor host still returns 404.
Perception
GET /v1/brands/{brand_id}/perception and MCP get_perception return the statement, positioning rows, Understood and Praised, claims, negative prompts and sources, and best quotes. They accept period, the shared figure filters and as_of.
written comes from the latest weekly report through the scan pin. Its statement, line to own and positioning rows keep that report’s full population, regardless of the selected period or filters. The figures and evidence lists follow the selected period and filters.
Each claim carries its key, wording, verdicts, quote, trend and action state. verdicts splits the answers into agrees, partly, contradicts and doesnt_say, with their sum in answers. Counts stay beside the wording those answers were checked against, even after you edit the profile.
Pass that key to GET /v1/brands/{brand_id}/perception/claims/{claim}, or as claim to get_perception, for its quotes, contradicting prompts, engine counts and contradicting pages. Each page keeps its passage and the wording it was checked against. Unknown claims return not_found. MCP returns the whole page in perception or one claim in claim.
Cited-page verdicts and passages and best quotes read the observations kept with each scan, including claim flags on your own pages. Removing an old answer’s raw text or citations does not remove this evidence. Perception explains the verdicts and page flags.
Use list_limit to bound the negative lists or a claim’s evidence lists. Page them with prompts_offset, sources_offset or pages_offset; their totals still count the full filtered population. The Perception read includes menus for the shared filters.
Set with_panes=true on the scores read or MCP get_scores to add panes, pane_prompts, pane_rivals and pane_headline. These carry the axis labels, evidence, trends, engine and intent rows, recommendations and linked tasks. figure_only=true returns each pane’s figure with its evidence fields empty. The existing five score fields keep their meanings.
Prompts
Keyword measurements
The prompt list, prompt detail and Discover read atGET /v1/brands/{brand_id}/prompt-suggestions include measurement. It describes keyword numbers, with country for the requested market, measured_country for the country actually targeted and language. A null country means Global, which keyword measurements target as the United States. The language uses the product’s code, such as no for Norwegian.
coverage gives the current availability of keyword_research (discovery and difficulty) and search_volume (monthly keyword search volume), each as available, unavailable or unknown. Unknown means Heralded cannot read a catalog yet. These states apply now, including to older measurements; they are not a snapshot of coverage when a number was recorded. Historical numbers keep their measured market and language. A row’s non-null measurement overrides the response’s context when it differs.
Discover keeps its demand.source: search_console means the property’s impressions, keyword_volume means monthly searches, and engine_searches means how many engines searched the phrase. Cached Search Console and engine-search rows remain usable when keyword discovery is unavailable.
When keyword research does not cover a market and language, Discover returns an entry in unavailable with provider=keyword_research and reason=market_language_unavailable, and measurement.coverage.keyword_research is unavailable. It does not return older keyword suggestions. English in Romania has keyword research unavailable and search volume available. sources.heralded describes the stage: no_suggestions when it finished with no suggestions, running while unfinished, or failed when it failed.
Tracked prompts
Each tracked prompt carries, per engine, how that engine’s latest answer treated the brand. How an answer is read defines each rung.
Recommended counts both
leading and recommended.
list_prompts and GET /v1/brands/{brand_id}/prompts also return each prompt’s period score, trend, engine marks, type, search volume and status date. marks open the most recent answer in the selected period. The existing engines keep describing each engine’s latest answer, regardless of period, and reading is true while the read of a newly tracked prompt is still asking that engine. reading is about now whatever as_of pins, so read the prompts again without as_of to see the answers it brings. The list defaults to period=4w and adds the filter menus and tracked, active and archived counts. Select archived=true for archived prompts, or use search, sort and direction to browse the table. Omitting sort keeps the existing grouped order; naming a sort orders the selected column. Cursors keep the same ordered population even when a prompt is archived. Each row carries the API-composed status_note for paused and archived prompts. Its cells describe the engine readings and measured days, including the answer id that opens their evidence. The shared figure filters apply, with you selecting named or not_named, and topic_id=untagged selecting prompts without a topic.
get_prompt and GET /v1/brands/{brand_id}/prompts/{prompt_uid} return the score, competitors and sources over period, defaulting to 1w. Each engine includes its name, latest answer’s state and four measured states, answer id, read date and reading. With no answer, the state is unmeasured, the four states are not measured, and the answer id and read date are null. These engine facts use the latest answer under the same as_of scan pin. The read also adds the composed sentence, four tiles with Yes-answer counts, engine_cards, the next trend date, taxonomy provenance and linked work. The shared figure filters scope the same facts. answers_link opens their answers with the prompt and filters selected.
To render the Prompts band’s four cards, pass with_cards=true to the scores read or MCP get_scores. Its cards use the same figures, trend and composed change labels as the app. you and topic_id select the same prompt population as the prompt list. Without with_cards, cards is null.
Answers
Withoutperiod, list_answers and GET /v1/brands/{brand_id}/answers return all finished weekly and daily answers once. Set period to select weekly reports and the daily answers they pooled. The names filter matches the brands detected in each answer and the tracked competitors it names.
Each answer names its prompt, engine and segment, and when it was read. mentioned and recommended are null where the answer was not read for them. get_answer and GET /v1/brands/{brand_id}/answers/{answer_id} add the retained text, the URLs it cited and the rivals detected in it. Finished answers keep their frozen measurements and detected names after text retention. A running scan’s answer uses its live measurements until delivery. A finished answer without a frozen row returns 404.
Lists add states for all four axes, excerpt highlights, cited-page counts, detected brands and text_retained. The response adds the composed summary_sentence and filter_options. Request with_menus=true for the shared type, intent, topic and segment menus. Answers accept the shared figure filters, you, cites, source_group, cited_page, claim, claim_wording, content_topic, action and retained-text search. Sort by time or sources, with direction=asc or desc. With cited_page, the response adds cited_page_label and cited_page_key, the document key of the page the filter matched. The existing prompt_id and the shared prompt filter select the same prompt; passing both with different ids returns 422.
Single answers add cited_pages with stored titles and document keys, full-text highlights and the same four-axis states. Pass the list’s meta.data_as_of.id as as_of on subsequent lists and single-answer reads to keep one population. An answer newer than the pin, or an unknown or foreign scan pin, returns 404. Omit the pin to open an answer from a running scan. MCP list_answers and get_answer return the same fields and accept the same selection.
Sources
Sources are the domains the engines cited over the selected period, including pooled daily answers, most cited first. Counts follow the period and retention rules. Sources describes the page they come from.
Set
with_summary=true on the sources list to add its state, sentence, cards, source mix, site and page totals, and row labels and changes. with_menus=true adds the filter menus to sources or cited pages. Both lists accept owner, source_type, names_you, content_topic, q, sort and direction; cited pages also accept domain. List search changes the rows, while the cards keep the population selected by the other filters.
The sources list keeps citations as its default order. Set sort=priority to put the sites worth pursuing first, ranked by the search demand of the prompts citing them, weighted by each site’s authority. The remaining sites follow by citations. The fractional score stays internal; priority is a position in the ranking.
With with_summary=true, worth_pursuing returns up to three actionable suggestions and worth_pursuing_total counts them all. Each suggestion carries its title, reason, source type label, citation count and action_id. That id is null when no pitch is filed or its pitch was withdrawn. A filed pitch in state new carries its id. Dismissed, deferred, started and settled pitches leave the suggestions but keep their place in the priority order. Search, sorting and pagination affect the table rows alone.
One source adds its Answers link and task list. Use actions_limit and actions_offset to page tasks; the default returns no tasks. Nested tasks use kind, the same field as the actions read. Source and cited-page histories include comparability keys and breaks. One cited page also states its owner, content type label, topic and prompt count.
Setup actions
list_actions and GET /v1/brands/{brand_id}/actions include one-time setup with kind: "setup". A setup action finishes when its setting or connection is in place. It settles without claiming a measured gain in the answers.
Visits from AI
list_ai_visits and GET /v1/brands/{brand_id}/ai-visits return your owned pages with id, url and ai_visits. Use limit and offset to page through them. period controls their order by citations.
ai_visits counts sessions GA4 attributes to AI assistants in a 28-day read: the one of the newest weekly report in the period that read the GA4 property connected now. Its own inclusive dates are coverage.start and coverage.end. These are separate from the selected period’s answer dates. Do not describe the visits as totals for period or sum overlapping GA4 reads. A query-selected page stays unmeasured unless it has a measured path-only alias, because GA4 landing pages omit query strings.
The count is a floor because assistant visits often carry no referrer. coverage and visits are null without a connected GA4 property, before its first complete dated read, when that read is unavailable or incomplete, or when no report in the period read the property connected now. A page outside the read’s coverage also has null visits. Zero means the read covered the page and found no attributed sessions.
Pages, topics and Audit
get_page and GET /v1/brands/{brand_id}/pages return the same pages and Visits from AI, with each page’s citations and prompts over the period, its AI crawls and its rubric. rubric.score is the score the newest weekly report with page checks gave the page, and rubric is null on a page the rubric does not check, such as a legal page. crawler_hits comes from the newest weekly report through as_of, over crawler_hits_days, 28 whole days ending two days before that report started. The counts stay fixed with that report and do not follow period. One page adds the prompts and answers citing it, its citations in each weekly report, each rubric pillar, its checks against rival pages and when Heralded delivered it.
Each entry in crawler_bots has a category of training, ai_search, user_fetch or search_engine. Googlebot, Bingbot and Applebot are search engines. The category is null for a bot no longer in the vocabulary. Counts cover served requests from every listed bot, including search engines and requests known to be unverified. Sources collect counts daily. When the report records them, it uses connected sources with a successful pull in the preceding seven days. When a source outside your site’s plugin reports requests for a day, its counts replace the plugin’s counts for that whole day. A WordPress reply carries at most 500 counters. At that limit, Heralded updates the counters received and keeps saved counters the reply omits. Query strings do not distinguish pages in crawler counts. A query-selected page stays unmeasured unless it has a measured path-only alias. Raw crawler counts are kept for 13 months; removing them or changing a connection leaves the report’s recorded counts unchanged. A page without a recorded measurement reads null; a covered page with no served requests reads zero.
citation_evidence is complete, partial or unavailable, and unavailable_scans counts the period’s reports that lost citations before they were frozen; counts derived from citations are floors unless it is complete.
Each pages-list row, single page and Audit page row carries funnel. MCP get_page returns the same object with and without page_id. An Audit row without a registered page_id has funnel: null.
The funnel’s window.start and window.end are inclusive dates covering 28 whole days, ending two days before the newest weekly report through as_of started. This window stays the same when you change period or figure filters. It is null before the first weekly report. window.history_days is how many days back from today your plan reads crawler, Visits from AI and Search Console measurements, and window.clamped is true when the report is older than that. A clamped funnel has null for each of those counts. See History. sources lists the crawler sources recorded for that window, or is null without a crawler measurement.
funnel.crawler_bots lists each bot’s bot name, operator, recorded category and served hits with verification true or unknown in this window. It includes search-engine bots and excludes known-unverified requests from every category. WordPress requests with unknown verification count here. The list is null when the page has no crawler measurement and empty when the page is measured but no requests qualify. The existing crawler_hits and top-level crawler_bots[].hits count all served requests, including known-unverified requests.
A single page, and MCP get_page with a page_id, also carries funnel_series: one point per weekly report inside your plan’s history, oldest first. A point has the start and end of that report’s 28-day window and the search_clicks, crawled, fetched_live, cited and ai_visits the table below defines for it. A figure the report did not record is null. Consecutive windows overlap, so a point is a rolling 28 days, not a separate week. It is empty before the first weekly report in that history.
Each count is
null when its source did not measure the page for that window. Search and visit reads covering another window do not fill it. cited is null without weekly reports completed inside the window, or when any of those reports lacks complete citation evidence. A measured zero remains zero. Plugin crawl counts are a floor: they cover requests the plugin sees. WordPress reports unknown verification, so its served AI requests fill crawled and fetched_live.
Pass url to the pages list to get resolved_page_id, or null when the URL names no live page of your own. One page includes its content work, Answers link and each citing answer’s id and states. Set with_details=true to include search. Set with_takes=true to include takes: for each prompt and engine whose latest answer, up to the pinned scan, cited the page, the passage the answer lifted from the page and the claim it supported. Takes are paged with takes_limit and takes_offset. A take is kept with its scan, with the page wording and answer read then, so a later page edit, scan or answer-text expiry does not change what as_of returns. A take shows once Heralded has checked that its passage supports its claim. pending counts takes not checked yet, rejected those that failed the check and unavailable answers whose take could not be kept. None of them is in items or total. Open an item’s answer at answers/{answer_read_id}.
get_topics and GET /v1/brands/{brand_id}/topics return the topics of the latest weekly report’s content check in the period, with the same statuses as Content. Search clicks and visits from AI cover 28 days of the properties connected now. One topic adds its page’s checks, its top search query, its questions, prompts and the pages they cite most.
citation_evidence is complete, partial or unavailable, and unavailable_scans counts the period’s reports that lost citations before they were frozen; counts derived from citations are floors unless it is complete.
Topic lists add sentence, cards, status labels and connection availability. Use status, q, sort and direction to select rows, and with_menus=true for the shared filters. The cards keep the population selected by the figure filters. One topic adds its Answers link, prompt scores and trends, source labels, and current content work.
A citation count is null, never zero, when a weekly report it covers could not keep all its citations, because answers aged out before Heralded stored them. A count over other reports is unaffected.
get_audit and GET /v1/brands/{brand_id}/audit return the latest crawl. readiness counts the pages the checks cover, the same counts as Home and the Snapshot report. Website has no period: page citations count the last weekly report, citations_scan, and crawler_hits uses the same frozen 28-day window as Pages. A page’s read_at is the date that crawl read the page, and is null for a page the crawl could not read and for some audits before 2026-10-04.
Website adds its summary sentence, page-type menu, check action ids and page status words. status, cited, page_type, q, sort and direction select its page rows without changing the headline. Each check returns up to checks_limit failing pages. Pass check with checks_offset to read another page of that check’s failures.
These reads and their existing MCP tools accept as_of. Pass the first response’s meta.data_as_of.id on subsequent requests to keep the page on the same completed scan.
Scans
GET /v1/brands/{brand_id}/scans lists a brand’s weekly reports, daily updates and the Snapshot it started from, newest first. Each row has kind, one of weekly, daily or snapshot, state, one of preparing, running, completed or failed, domain, started_at, completed_at and heralded_score, the score the scan issued. A daily update issues no score, and a partial Snapshot shows none until it is final. While a scan is preparing or running, progress_pct says how far it has come. A completed weekly report or Snapshot has a share_id. A scan that failed has a failure_reason, and every other scan has null:
stuck_no_progress: the scan stopped making progress.brief_abandoned: the brief was not confirmed in time.insufficient_engine_signal: the engines did not return enough usable answers to score it.cost_cap_exceeded: the scan reached its safety cost cap.report_inputs_missing: the scan finished without the data its report needs.other: any other reason.
other.
GET /v1/scans lists the Snapshots you ran, with the same rows, paging and cursor. It covers the one-time scans no brand’s list shows, and a Snapshot that became a brand’s first scan stays on it. A Snapshot whose report is no longer served is left out. It lists only your own, with an API key or signed in.
GET /v1/scans/{scan_id} and get_scan read one scan. While it runs, progress gives its step and how many answers are in. Once it completes, issued gives the Heralded Score, Mentioned and Recommended with the brand’s place among the competitors that scan measured, and readiness over the pages it checked. These are the numbers its report shows. Anyone who can read the brand can read its scans. A Snapshot no brand holds is read only by the account that ran it.
GET /v1/scans/{scan_id}/audit and get_audit with scan_id read the Content read of a Snapshot or Audit you ran: the page the app opens at /r/{share_id}/audit. pages lists every audited page, best fix first, each with its priority, value, score, the checks it fails or could not measure, and the buyer questions it answers. pillars counts how many pages pass each page check. readiness, site_blockers and site_checks give the same counts as Website’s readiness and the site’s checks, with the fix for each blocker. missing_topics names the topics the site has no page for: a Snapshot names its top five and missing_topics_total counts them all. content_pass says whether the read is still running, failed or done, and the fields after it fill in once it is done. Only the account that ran the scan reads it, with an API key or signed in. Anyone else, a reader of the brand a Snapshot became included, gets not_found, and so does a request with no API key. The scan is named by its id or by its share_id.
A delivered weekly report or Snapshot has a share_id. GET /v1/shared/scans/{share_id} returns its report as anyone with its link sees it, with no API key. It never includes your workspace’s analytics, search queries, crawled pages, content strategy or anything about who is reading.
source_tier_rollups[].citation_share_pct gives each tier’s share of all citations. brand_citation_summary gives the same population’s ownership shares in owned_share_pct, competitor_share_pct and independent_share_pct. Independent means every tier outside owned and competitor, including unclassified citations. Each percentage rounds half up independently, so the shares can total 99 or 101. An empty citation population has null shares. Each row of scan.race.rows also has gap_pts, its Heralded Score minus the subject’s score, or null if either score is unmeasured.
A report retired with Heralded’s pre-launch data answers 410 with code report_retired, its domain and a rescan_url.