GET /v1/brands/{brand_id}/profile and MCP get_brand_profile. Read your brand profile describes its buyer context, facts, market and domains.
Home
GET /v1/brands/{brand_id}/weekly-brief and MCP get_weekly_brief return the issued decision set for the reader. Home explains the weekly brief.
A decision has a stable
id, kind of needs_you or suggestion, title, demand, a work link in href, from_last_week and decided. A stored action has action_id; a recurring job has job_id and a null action_id. A job appears when its next step needs a person, and counts as decided when that request ends. An action removed after issue has a null action_id and href and counts as decided. Assignment changes do not replace the issued list.
Set with_today=true to include the live today box. It is null otherwise. today.state is A when decisions wait on the viewer, B when only teammates have open decisions, C when only Heralded has work running, and D when nothing is in flight. It carries the UTC date, title and line. viewer_decisions holds up to three current work rows, viewer_decision_ids their review order, and viewer_total and viewer_more their counts. team_open holds the two oldest decisions assigned to others, each with its work row, assignee_name and age_days; team_total counts all of them. heralded_running holds up to three running work rows with their served stages. running_total and running_more count all running items and those beyond the list. running_line summarises them. in_flight counts the viewerâs decisions, the teamâs open decisions and Heraldedâs running items. suggestions follows Workâs order with focused work first. Each has its work row, the observation it leads with as reason, or null when it rests on none, and cost in content credits, with zero meaning free. Today describes how many suggestions appear. HTTP and MCP return the same content.
GET /v1/brands/{brand_id}/week-timeline and MCP get_week_timeline return week, rows, total and the same paging fields. week is the Monday starting the week, in UTC. Omit it for the current week. A row carries id, kind of change, result or competitor, the source observation kind or signal in event, observed_at and an optional typed target. A result also carries action_id, work_href and, for a tracking signal, its result step with the result states. First-party sessions also receive the observed eventâs sentence. Rows describe observed changes, delivered work or measured outcomes. A signal still waiting for a citation or an unavailable check does not create a row.
days lists every observed UTC day in the selected week, newest first, independently of the rowsâ page. Each day has date, lead, a timeline row, and others, the number of remaining observations. The Home timeline describes the lead order. Set day to a date within the selected week to page that dayâs rows in lead order. total then counts that dayâs observations. Without day, rows keep their newest-first order and total counts the week. HTTP and MCP support the same filters and cursors.
GET /v1/brands/{brand_id}/focus-cards and MCP get_focus_cards return items, one per starred topic, competitor or market. Each has focus and two figures. Each figure carries its key and the standard figure with its value, range, measurement state and change. Topics and markets show recommended and mentioned; competitors show your_score and competitor_score. The focus keeps Strategyâs kind, id, name and tracked fields. First-party sessions also receive a sentence and each figureâs label.
These reads also carry the standard meta fields. A read makes no model call.
Reading figures in an assistant
Links in API and MCP responses open the Command Centerâs current pages. Theroute identifiers stay stable: actions opens Work, content opens Strategy, prompts opens Visibility, search opens Visibilityâs Google search side, market opens Competitors and audit opens Website. answers_link opens All answers with its filters selected. Previously shared page links redirect to their current destinations.
Treat unmeasured figures as unknown. Check basis, state and coverage dates before comparing values. Change explains the real flag, and sides distinguishes AI answers from Google results. The Website score describes its areas, findings and versioned comparisons.
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. latest_read.scan_id identifies the weekly report. The overviewâs latest_read and answers_citing_you belong to the latest weekly report, regardless of period. Its sources_mentioning_you follows 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 workspace funds no new scan. daily_scans_since_weekly counts the daily scans whose answers no weekly report has pooled yet, counts the current work populations, open_action_count a deprecated alias of counts.open, 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, questions, engines, answers and the dates of its first and last answer. since_started gives the scoreâs move since the first report on the current score version, one point per weekly report. competitor_rank places you among your tracked competitors by Heralded Score over the period, on the side read: position is 1 plus the brands scoring higher, so tied brands share it, and of counts the brands with a score, you included. It is null while your score or every competitorâs is unmeasured, and under lean. GET /v1/brands/{brand_id}/scores and MCP get_scores with group_by=competitor carry the same competitor_rank. verified_actions lists the newest three qualifying results from delivered actions: a verified gain or a first citation of the delivered page. A citation without a verified gain has before: "uncited", after: "cited" and credited_pts: null. total counts all qualifying results. Set with_diagnosis=true to add diagnosis: the questions 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. Set lean=true on the HTTP route to leave out rivals, competitor_rank, sources, actions, attribution and readiness and skip reading them. They come back empty or null, source_citation_evidence and source_unavailable_scans keep their defaults, and every other field is unchanged. MCP get_brand_overview does not take lean.
The overviewâs default pin is the latest completed scan, daily updates included, and meta.data_as_of names it. Its figures and report details describe the last good weekly reports in the period. A newer failed report leaves those results unchanged. Pass the pin as as_of to Changes, scores and the other reads to keep one page on the same scans, the daily updates Changes shows included.
Home selects its Search figures independently of its AI report. If a newer reportâs keyword reads fail, the Search figures keep their previous measurement while the AI figures and report details can advance. meta.surfaces["search.score"] identifies that Search result and refresh state, including in the default responseâs sides.search. With side=search, home.score identifies the same result, and period and competitor_rank follow the selected Search measurement. The daily response pin stays independent of both results.
Each trend point has its report date at, value and range, answer count, state and structured break data when the reading method changes.
When the selected period has no delivered report, the descriptor counts zero reports and each figure has a null value. Search can have state: "pending" while its first measurement is underway; other empty figures have state: "not_measured". When a figure is empty lists every reason one can be.
Result freshness
Computed reads includemeta.query and meta.data_as_of. The latter identifies the responseâs scan pin with a required UUID id and completed_at. It is null when the response has no scan pin.
meta.partial means the displayed report is partial. meta.updating means a newer attempt is underway or its result is not yet included in this response, such as a weekly report still being written or a keyword check still running. A daily updateâs finished keyword checks count in the next weekly report, so they do not set it. meta.last_attempt_failed means the newest attempt failed. A failed refresh keeps the last good result and its date.
Composite responses also include meta.surfaces, keyed by Command Center section, such as home.score, perception.positioning or website.overview. Each entry has its own partial, updating and last_attempt_failed flags, plus as_of. One section can be updating while another is complete.
A surfaceâs as_of is { "scan_id": "âŚ", "at": "âŚ" }, or null before a result is available. scan_id is null for a result measured independently of a scan, such as a connection sync or review batch. This does not change meta.data_as_of, whose id remains a required UUID. REST reads and their MCP tools return the same freshness fields.
Work in progress
GET /v1/brands/{brand_id}/work and MCP get_work return reading_progress with done and total summed across live reading jobs. Scheduled reads and jobs of other kinds do not contribute. The field is null when no live reading job has measurable progress with a positive total. Each job keeps its own progress and current_step.
Asked language
Figure and answer reads acceptlanguage=english or language=local, except the overview read and MCP get_brand_overview, which take no language. Omit language for all asked languages. These values filter the language the question was asked in. Local includes all non-English policy languages, including both local languages in Belgium and Switzerland. A thin language returns a null figure under the usual minimum-answer rule. MCP uses the same parameter.
Sides
The overview, scores, competitors and topics takeside:
The Heralded Score uses AI answers only.
all equals ai for the score, Mentioned and Recommended, including ranges, changes, trends and competitor ranks. Searchâs heralded_score has a null value and state not_scored, even when its shares are measured. Every response lists sides_available: ai, and search once a weekly report in the period checked your keywords. Search shares awaiting their first measurement have a null value and the state pending. Other unmeasured shares have not_measured, never zero.
The Search side has no engine, type, intent, question, asked-language filter or recorded answer country. Under one of those filters, market or you, search is not measured and all is the AI side. The topic and segment filters narrow the Search side to their keywords. A group_by of engine, intent, stage, type, prompt or country follows the same rule.
Understood and Praised follow the same side in overview, scores and MCP get_brand_overview and get_scores. ai reads AI answers, search reads pages Google ranks, and all reads the blend. Under a filter, grouping or question selection that pages cannot follow, they keep the AI part with basis: "ai".
The overview also returns sides: all five figures on all, ai and search, so one read draws a switch between them. Its top-level figures belong to the selected side. Its since_started and score_context describe the AI side. In the competitor list, all and ai use the Heralded Score and rank; Search has no score; its rank field gives list order. The page, share of voice and channels read AI answers, except that page.leaderboard follows side=search and ranks the tracked brands by their Search shares. In scores, engines, engine and the default supporting detail inside panes read AI answers. Set with_search_detail=true with with_panes=true and side=search for Google detail on Mentioned and Recommended instead.
Filters and groups
Scores takeengine, type, intent, topic as a tracked-topic id, prompt as a question id, market and audience. Every figure, its change and its trend then read only the answers the filters keep.
Scores also return headline, one sentence on how AI answers treat the brand under the same period and filters, written from templates with no model call. It states where the brand ranks by Recommended among the brands the Competitors page ranks, or its Recommended share when the filters leave no rank, and it adds a contrast when no topic is selected and a topic is far below or above the overall Recommended. It stays in English for every market and is null on side=search, before the first report and when the filters keep no answers.
market=RO selects topics tracked in Romania. It excludes Romanian answers from a Europe topic. Country codes ignore case. market=europe selects Europe topics, and market=global selects Global topics. Omit market for every topic. audience accepts an audience UUID or all_buyers; omit it for every audience. AI answers, keywords and coverage use the same topic selection. A Europe topic keeps its per-country breakdown.
group_by also states the five figures per engine, intent, stage, type, topic, segment, prompt, competitor or country, 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 stage group names learn, evaluate or buy and counts its tracked questions in prompt_count. A group exists for each tracked questionâs value, so a group can have no answers in the period. Without group_by, groups is null.
A country group carries its ISO code in group.country. A null country groups answers with no recorded country. Europe includes its member countries even when a country has no answers. Each countryâs figure keeps the language weights of its pooled definition, and its change and trend follow the same country selection. A country with too few answers has a null value and too_few_answers state; one with none is not_measured. Answers repeated in overlapping weekly reports count once.
Set with_panes=true on scores or MCP get_scores to include the Mentioned, Understood, Recommended and Praised panes. Every pane carries figure, the top-level figure for its axis under the same period, side and question selection, with change: null and its trend. The paneâs trend uses the same points. you and topic_id narrow its question rows as they narrow the top-level figures.
A blended Understood or Praised pane adds parts.ai_answers and parts.web_pages, each with value, numerator and denominator. Other panes have parts: null. The supporting tables describe AI answers. by_engine and engine screens include only engines that rendered at least one answer in the selected period and population.
Brands and paused engines
Withwith_panes=true and side=ai or side=all, the Mentioned, Recommended and Praised panes add brands, brands_total and paused_engines, and the Understood pane adds paused_engines. Panes on side=search leave them out; their brands arrive in Search detail.
brands lists up to five brands from the Competitors board, highest axis value first, unmeasured last, with a name breaking a tie. Your brand takes the fifth row when it places lower. Each row has brand_key, the key that opens the brandâs competitor read, name, domain, is_you, rank, value and change. Brands on one measured value share a rank. A rowâs value and change match the competitor list for the same period and filters. brands_total is the boardâs total, including unmeasured brands.
paused_engines, on every axis pane, lists the engines paused for the periodâs latest report, in the enginesâ order, so you can mark them beside the engines that answered. An engine filter keeps only that engine.
Each axis paneâs by_engine row and each competitor paneâs engines row carries its engineâs change. A newly measured engine shows New. A single engineâs change has no compared-engines tooltip.
Competitor reads also carry paused_engines, with the same latest-report rule and engine filter. Topic reads with with_pane=true carry paused_engines alongside by_engine; both ignore the engine filter. These engines show Paused in the app. An engine that has no answers is not necessarily paused.
Compact pane reads
Usepane_axis=mentioned|recommended|understood|praised on scores or MCP get_scores to select one compact figure pane. It includes its bounded evidence and live Work, with next_step selected across all eligible work. section with limit and offset pages its questions, facts, brands or work. On side=search, include with_search_detail=true; the sections are rankings, ranking_pages, brands, markets and work.
Topic detail accepts preview=true with with_pane=true. Its section pages questions, keywords, unanswered, brands, work, own_pages, pages, engines or segments. pane_figures contains the selected sideâs figures and trends. answered_questions, unanswered_questions and own_pages_total count the complete selection. segments_menu and focus_selection supply the current controls.
Keyword detail accepts preview=true. It returns five results and questions, three work items, results_total, prompts_total, competitors_ahead, a separate own_result and the keywordâs markets. rank_delta and competitors_delta compare its last two comparable weekly checks; negative rank change means a better position. Page results, questions or work through section, limit and offset. An AI Overview and the separate own result do not count towards results_total.
For an engine, use scores with include=engine and preview=true. Sections weakest, strongest, brands, sources and work page those lists. Each carries its complete total; topic_label names a selected topic. Engine Work includes only items whose recorded target explicitly names that engine.
Competitor detail accepts preview=true, with sections lost, won, pages, work and changes. It includes figure_trends, figure_changes, gap_delta, focus_selection, a bounded moves feed and live work. The gap is your score less theirs; its delta is null unless both comparisons use the same baseline and engines. with_details=true adds the full website read. GET /v1/brands/{brand_id}/competitors/{key}/page with page_url, or MCP get_competitor with page_url and preview=true, returns only rival and measurement context. The existing competitor detail keeps its combined response. Its questions and work sections page the citing questions and work targeting that exact URL. question_trend gives weekly counts of citing questions, and questions_delta compares the selected period with its preceding comparable period.
The existing full reads keep their defaults. Compact sections are available through the corresponding MCP reads as well as REST. See all in the app uses these section reads and keeps the selected period, filters and report.
Search detail
Scores and MCPget_scores accept market for a country or global. The headline, trend and Search detail use that market. The competitors read and MCP get_competitors accept the same market on side=search, so the detailâs own-brand value and brand count agree with that board.
GET /v1/brands/{brand_id}/scores and MCP get_scores accept with_search_detail, default false. With with_panes=true or a selected pane_axis, and side=search, it adds search to the Mentioned and Recommended panes. The flag is ignored otherwise. Responses without it keep their existing fields and values; an unset search is omitted. This detail follows period, as_of, segment, market and topic and reads the checks saved in weekly reports.
Each ranking is one tracked keyword in one country of one tracked topic, the population the keywords read lists. Not checked is one of its position bands. Mentioned counts results showing you; Recommended counts third-party results recommending you. Each count equals the keywords readâs under the same period, segment, market and topic. The detail carries these fields:
country: null means Global. Under market, Search figures use only that countryâs frozen checks and show once its coverage rule holds. A country without measured checks remains unmeasured.
figure_only is deprecated and remains accepted until 2026-11-23. Requests using it return Deprecation and Sunset headers. Full panes already include figure and its trend.
GET /v1/brands/{brand_id}/scores and MCP get_scores also take include=engines for the Engines table on AI visibility, or include=engine with an engine filter for that engineâs pane. The engines and engine fields carry the same measured counts, score marks and trends as those surfaces. The pane includes competitors, strongest and weakest questions and its five most cited sources. Its competitors are the brands the competitor board lists, your own and the competitors you track, or with prompt or topic_id the brands those answers name; competitors_total counts them, and a brand with no earlier reading has change new. An engineâs score needs at least three answers behind it, as on every question and engine figure. sort, direction, limit and offset select engine rows or the paneâs competitor page. with_menus remains an accepted parameter; filter menus are excluded from the public API and MCP results. These additions leave the existing figures and groups unchanged and follow the same as_of pin.
Question and engine panes return answer_count: null for Understood. Its numerator can be fractional because answers receive partial credit, so it has no count of perfect matches. The paneâs denominator still gives the answers naming you that Understood measures. Other axes keep their answer_count.
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.
Scores and MCP get_scores return engine_weights, keyed by engine id, and side_weights, keyed by ai and search. Each value is a fraction from 0 to 1. Engine weights are the configured shares of the AI side under the v8 method. Side weights are AI 1 and Search 0 while Search is not scored. They stay the same under filters and when an engine or side has no measurement. The Heralded Score explains how missing measurements affect the index.
The competitors list and detail reads, and MCP list_competitors and get_competitor, also accept you as named or not_named, and topic_id as a topic id or untagged. These select the same question population as the Questions read. A competitorâs detail follows side for its score, share tiles and history; its question and engine sections read AI answers. The scores readâs engine cards and the competitors readâs leaderboard, share of voice and competitor pane keep that population.
On scores and MCP get_scores, you_engine selects the engine that resolves you, before engine selects the answers to measure. Use you_engine=all when opening an engine pane from a page on all engines, or the pageâs engine id when it has one selected. Omit you_engine to resolve you under the measurementâs engine filter. The pane keeps the pageâs selected questions even when engines disagree about naming your brand.
MCP get_scores accepts one topic selector, a tracked topic UUID or an s: suggestion id. Suggested topics have no score. REST keeps topic_id as a deprecated selector; topic selects tracked topics.
Headline figures
Each is in points from 0 to 100 and carries a 95% range,low to high.
The table describes the AI side. All five figures follow
side. The Heralded Score, Mentioned and Recommended leave out questions that name the brand. Every figure carries basis, value, low, high, answers, numerator, denominator, state, change and trend. basis is ai_and_web when Understood or Praised includes web reputation evidence, search for Search-side figures, and ai elsewhere. value is weighted; it is not the raw numerator divided by the denominator. numerator and denominator describe that figureâs own population; both are null for a blended score. describes_you.n is deprecated; use the individual figureâs denominator. The score has no numerator or denominator. On the AI side, Understood and Praised count answers naming the brand that were measured for that figure in their denominator. A web-only figure counts its web observations; a blend has no single denominator.
state is measured, too_few_answers, calibrating, first_report, not_comparable, not_measured, pending or not_scored. An unmeasured value is null, never zero. A report count never makes a figure calibrating. Its measurement state is separate from its change state. not_comparable with a value means the figure stands but its change canât be computed against a baseline read differently; with a null value, the report itself was read two ways.
not_scored means Search has no score, even when its shares are measured. Its value is null.
pending applies to Search Mentioned and Recommended, including competitor figures, before any report has shown Search under the selected tracked topic. It requires an active keyword created within 14 days, inside your topic limits, that does not name your brand and has no frozen report check. It also applies when an active topic tracked within 14 days has no active keyword and its keyword research has neither found none nor been unavailable. Topic and topic groups apply these conditions within each groupâs scope; competitor rows share the requestâs scope. Reactivating an older keyword does not restart this window. The app shows Calculating with one explanation per value. On Home, the headline names the date of your next weekly report when Search is selected; the Mentioned and Recommended info buttons carry it too. The Mentioned and Recommended cards keep the date in their info buttons. Where that date is unavailable, the explanation says âYour Search figures appear with your next weekly report.â All keeps its AI figures while Search is pending, even when pooling several reports would produce a Search measurement. MCP returns the same state.
Citations
Both 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 comes from the latest read and sources_mentioning_you from the selected period. Answers citing you and sources mentioning you defines them.
Change
A change carriesstate, delta, low, high, real, direction, baseline, cells_unpaired and compared_engines. Its state is up, down, steady, first_report or not_comparable, which the app words New baseline. delta is the shown value minus the baselineâs, in points, as the trend draws them, or over compared_engines where it names engines; a Search change compares with the baseline reportâs own Search point, under any filter. Latest compares with the previous comparable report. Multi-report periods compare with the preceding equal-length window, pooled the same way. The baseline stops at the first non-comparable report. baseline states its report count and true answer dates; a Search change states the dates of the baseline reports the Search trend draws, and a first_report change states none. cells_unpaired counts question and engine cells measured on only one side. compared_engines is a list of engine keys, or null. When the engines asked in the period differ from the baselineâs, delta is the move over the engines both asked, compared_engines names them, and the figureâs value and trend keep every engine asked. It is null when the size is the move the trend draws, and on the Search side. Change has the rule.
Read state before calling a change. up and down mean the paired test calls the move real and the move has the sign of delta. steady keeps its signed delta otherwise: the test found no real move, had no interval, or disagreed in sign with the drawn values. not_comparable means no valid comparison exists. A change can be called from the second report, and a baseline with no value is a first_report. low, high and real are the paired testâs: real is true where a paired test over the cells both reads measured says the figure moved, and the test only decides that, never the size. Two readsâ ranges can overlap while the figure really moved, and ranges that donât overlap are not a test either.
A measured first report carries change.state: "first_report". An incompatible comparison carries change.state: "not_comparable". Both keep null change values and real: false. A change is null for an unmeasured figure, except when a change in side coverage makes the comparison not_comparable. It is also null for a comparable period covering multiple reports and the whole history with no preceding baseline. Its values can also be null where no cells can be paired. Change has the test and every case.
Competitors
Set
with_details=true on the competitor list or MCP list_competitors for one combined read. It includes page, a templated headline over the filtered leaderboard, and sites, the weekly competitor websites read with its first 20 changes. description_scan_id and description_at date the stored AI descriptions. They follow the report cutoff, not the figure filters. The responseâs freshness surfaces include visibility.competitors, website.competitors and perception.positioning.
With a question or topic filter, ranks follow the Brands table, including measured suggested brands. On AI, the headline compares Heralded Scores. On Search, it compares your filtered Mentioned in search. The headline names that figure and is null when you or every competitor is unmeasured.
Omitting sort orders the leaderboard by Heralded Score descending on AI and All, or Mentioned in search descending on Search. An explicit sort and direction override that order.
The competitor detail and MCP get_competitor accept with_details=true too. Its website holds that competitorâs site and first 20 changes, or null when no site read contains it. Its description, description_scan_id and description_at have the same meanings as the listâs. most_said_for and most_said_against carry its leading positive and negative opinions over the selected period. The existing plan availability of each data source stays the same.
share_of_voice states the population, answer count, excluded answers and each brandâs raw numerator and denominator. Each rowâs pct is weighted, and the rows sort by that share, highest first, then by name; unmeasured rows follow. 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. Search uses search_keywords and its own population and point counts. 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 share-of-voice data, leaderboard, brand roster capacity, checked_7d (the tracked competitors Herald checked in the last 7 days) 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. 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.
With prompt or topic_id, the list and the leaderboard hold only the brands those answers name, tracked or discovered, and your own brand even when no answer names you. The leaderboardâs total counts them. The question detail serves the same count as competitors_total, and topic detail with with_pane=true serves it as brands_total. MCP reads follow the same rule.
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 question 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.
capacity states the current competitor 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 competitor-owned pageâs pane in rival, including its explanation, cited questions, 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. 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 competitor 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 questions and sources, and best quotes. They accept period, the shared figure filters and as_of. Understood and Praised are the blend of AI answers and pages, the same figures as the overview and the reputation read.
headline is the written statement when one exists, otherwise a template over the served Understood and Praised figures under the active period and filters. It is null when Understood has no measured value; the Perception page then omits the headline. facts_summary carries mostly_right, measured and insufficient_keys. Facts and profile claims with at least three addressing answers enter measured. A profile claim read part by part counts as its parts. Addressing answers have verdict agrees, partly or contradicts; doesnt_say is excluded. Strictly more than half must agree to enter mostly_right. insufficient_keys lists facts and claims below the minimum. The reputation read and both MCP tools return the same fields. See Facts.
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 questions, engine counts and contradicting pages. Each page keeps its passage and the wording it was checked against, and its insight names the work that fits it, as Insights and their work describes. Unknown claims return not_found. MCP returns the whole page in perception or one claim in claim.
Where the latest report read a profile claim part by part, its row lists parts. Each part has its key, its wording as that report read it, a quote, its verdicts and its trend. doesnt_say counts the answers naming your brand that never mention the part. A fact, or a claim read whole, has an empty list. The reputation read gives each part ai and elsewhere in place of verdicts.
The claim read includes the current factâs definition, including its original author name. Profile claims have no definition. next_fact_check_at is the next scheduled weekly report date, or null when unscheduled, and brand_paused indicates whether checks are paused. The evidence keeps the definition it measured.
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.
Set with_panes=true on the scores read or MCP get_scores to add panes, pane_prompts and pane_rivals. These carry the axis labels, evidence, trends, engine and intent rows, recommendations and linked actions. figure_only=true returns each paneâs figure with its evidence fields empty. The existing five score fields keep their meanings.
Labels you want to leave behind
GET /v1/brands/{brand_id}/moving-away-from returns period, filters and labels: one entry for each label in the brand profileâs Labels you want to leave behind list, in the order the profile lists them. MCP get_perception with moving_away_from set returns the same read for every label under moving_away_from. Both accept period, the shared figure filters and as_of. On the route, label, a labelâs key, reads that one label. labels is empty when the profile names none.
Each label carries key, label, state, answers, uses, share, low, high, trend, quote, pages and pages_total. key stays the same however the label is spaced or cased, and a label you reword is a new one. answers counts the answers naming the brand that were read against the label, and uses counts those that describe the brand with it. share is the whole percentage of answers that use the label, averaged over question and engine cells like the other figures, with its 95% range in low and high. state is measured, too_few_answers under three answers, or not_measured before a report has read an answer against the label. share, low and high are null unless state is measured.
trend is {state, delta, label}, the change in share against the baseline in points. Its state is up or down only where the paired test calls the move real, and steady, first_report, not_comparable, calibrating or none otherwise. A fall is the improvement. Change has the test.
quote is the newest answer in the period that describes the brand with the label, with quote, engine_id, prompt_uid, answer_read_id, asked_language and language, or null when none does. pages lists the pages the periodâs answers cited that describe the brand with the label, your own first and then the most cited. Each has url, domain, title, type, citations, owned and state, which marks a page of yours or one that is new this report. pages_total counts them before paging. list_limit bounds the pages under each label, 10 unless you set it, and pages_offset skips pages under every label.
Perception explains how answers and pages are read against a label.
Reputation
A member-added fact carries its currentdefinition, with kind, check, question, definition_version and added_by_name, and its counts carry origins, definition_version and current_version_pending. Profile claims have definition: null and origins: null. The rowâs existing kind still distinguishes a fact from a profile claim. Fact definitions describes the fields and how they relate to older evidence.
Each fact in the reputation page also carries nullable insight, a contradicting pageâs work choice. Existing work takes precedence; otherwise the first actionable page is chosen, your own pages first and then the most cited. Its stable page identity, fitting kinds and canonical work are the same as the claim panelâs page. With AI contradictions alone and no actionable page, it is null.
GET /v1/brands/{brand_id}/reputation and MCP get_reputation return the perception read with the web weighed in. Reputation describes the fields. understood and praised follow the blend and its fallback rules, and parts states each part. facts replaces claims: each row keeps the answersâ verdict counts under ai and adds elsewhere, how many pages agree with it and how many contradict it. Pass a factâs key to GET /v1/brands/{brand_id}/reputation/claims/{claim}, or as claim to get_reputation, for the pages behind elsewhere as documents. opinions lists what voices think of the brand, with held_by, kinds, engines, change, change_detail, action_id and insight, which Insights and their work describes. Pass an opinionâs id to GET /v1/brands/{brand_id}/reputation/opinions/{opinion_id}, or as opinion_id to get_reputation, for its holders. MCP returns the whole page in reputation, one fact in claim or one opinion in opinion. The request parameters are Perceptionâs, and filters donât narrow opinions. change compares distinct holders over the selected reports against their baseline. change_detail carries that delta, baseline and the shared figure testâs verdict; it is null without a comparable baseline. A nonzero delta need not be a real rise or fall. For one opinion, pages_offset skips holders and list_limit bounds the returned holders; holders_total counts all of them before paging.
Reputation through the API describes which parts the overview and scores reads return.
Reviews
GET /v1/brands/{brand_id}/reviews and MCP get_reviews return the rating and review count for each review platform, ratings for tracked competitors, and the reviews Heralded has read. Review rows include their platform, stars, title, excerpt, publish time, reply state and linked action. Pass review_id to MCP get_reviews, or use /reviews/{review_id}, for one review. On Core, the review list and work are empty; platform ratings and counts remain available. features reports the brandâs Mentions monitoring, Reviews and Advocacy entitlements. See Reviews.
Questions
Keyword measurements
The question list and question detail includemeasurement. 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.
Tracked questions
Topic and question reads carrymeasurement_status as new or measured, independently of tracking state. first_answers_at is the first answered time or the pending estimate. first_score_on is the next weekly reportâs date for the market, or null before the brand has a weekly schedule. These fields appear on the topics list and detail, a topicâs question rows, the questions list and detail, and their MCP tools. New topics sort first. See First answers and score.
Each tracked question 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. A question one of whose engines reads absent carries an insight, on the list and on one question, which Insights and their work describes.
list_prompts and GET /v1/brands/{brand_id}/prompts also return each questionâs period score, trend, engine marks, type, search volume and status date. marks open the most recent answer in the selected period. A mark, like an engine cardâs score, from fewer than three answers has a null value and too_few_answers state. The existing engines keep describing each engineâs latest answer, regardless of period, and reading is true while the read of a newly tracked question is still asking that engine. reading is about now whatever as_of pins, so read the questions again without as_of to see the answers it brings. The list defaults to period=4w and adds tracked, active and archived counts. Select archived=true for archived questions, or use q, 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 question is archived. Its cells describe the engine readings and measured answers, 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 questions 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. The Command Centerâs score sentence counts the answers behind the displayed score and only the engines kept in that score. For Europe, it follows the pooled answer population. Individual engine cards keep their own answer counts. sources lists the five domains the questionâs answers cite most, and sources_total counts every domain they cite. 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 four tiles with Yes-answer counts and measurement states, engine_cards (each with its mentioned_count and recommended_count, the engineâs answers that mention or recommend you), the next trend date, taxonomy provenance and linked work. Mentioned and Recommended tiles have state: not_applicable on Brand questions. The shared figure filters scope the same facts. answers_link opens their answers with the question and filters selected.
Both question reads carry evidence and synthesised. evidence lists what Heralded stored when it drafted the question, then the questions your team added to its topic, with the fields a suggested topicâs evidence has. synthesised is true when Heralded drafted the question with no buyer evidence behind it, false when evidence supports it, and null for a question you wrote or one drafted before Heralded stored evidence. Reading them buys no research.
Both question reads also carry wordings. One question keeps one id and display text across countries. Each wording carries id, country, language, version, text, answers, mentioned and mentioned_pct. The list includes the latest stored asked wording for each country and language, plus older wordings with different text asked in the selected period. An older version with the same text is folded into the newer one, whose version and counts it carries. The wording list reads current stored versions; as_of pins the answers it counts. answers counts distinct rendered answers for that wording under the period and figure filters; mentioned counts those naming your brand. mentioned_pct is mentioned over answers in whole points, rounded half up, and null when answers is 0. A wording with no matching answer has zero counts. Display and master translations are excluded. A question with no stored asked wordings returns an empty list. With a country filter, individual question scores and their engine and competitor figures have null values and not_measured state, with no change or trend. Wording and mention counts still follow the filter. MCP list_prompts and get_prompt return the same fields.
Display sentences, labels, cards and menus belong to the signed-in Command Center. They are absent from API-key and MCP results. Versioning defines the public contract.
Work results
GET /v1/actions/{action_id} and MCP get_action serve results.steps. GET /v1/brands/{brand_id}/results and MCP list_results include the same results object on each row. It carries status_label, headline, confirmed results, targeted_prompts, watching, warnings, connect, measured and the citation fields described in Action fields.
Each ordered step has signal, state, label, tone, summary, reason, at, metric, answer_id, display_name, prompt and citation. The list follows the playâs tracking, then its measured answer outcome. A site fix uses its live step for verification. Work with no tracking signals or no delivery has an empty list.
Observation states are good, pending, no_change, couldnt_check and not_connected. Measured answer outcomes also use no_effect, fell and inconclusive. A pending measurement is labelled Too early to tell. metric is recommended or mentioned only for a verified gain and is otherwise null. at is the observation time or, while a measurement is pending, its due date when known. Evidence fields and unavailable reasons follow the verification method. Recommended more and Paying off require verification of the targeted metric against untouched questions.
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. read_since, an ISO 8601 time, keeps the answers whose run finished at or after it. With period=all it reads every weekly and daily answer once, as without period. The names filter matches the brands detected in each answer and the tracked competitors it names.
meta.surfaces.answers follows the same selection. With period, a newer daily update changes freshness only once a selected weekly report includes it. A question filter also limits freshness to that questionâs results and pending reads.
Each answer names its question and engine, 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 competitors 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.
With a period and only shared figure filters, summary_sentence counts the stored measured answer population used by Visibility, including its pooled-market exclusions. The listâs total and row counts describe retained answer rows, which can be fewer. Answer-specific filters count matching retained rows.
Lists add states for all four axes, excerpt highlights, cited-page counts, detected brands and text_retained. Answers accept the shared figure filters, you, cites, source_group, cited_page, claim, claim_wording, content_topic, action and retained-text q. Sort by time or sources, with direction=asc or desc. With cited_page, the response adds cited_page_key, the document key of the page the filter matched. REST accepts prompt_id and prompt for the same question; passing both with different ids returns 422. MCP list_answers accepts only prompt. MCP get_prompt uses prompt_uid and has no second question filter.
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
The source list and MCPlist_sources add found_via, recommends_you, read_by_searchers and placements per site, plus recommending, which counts the sites that recommend you and the sites that name you, and channels for the period. found_via also filters the list. Source measures defines the recommendation count and monthly estimate.
Sources are sites found through AI citations, Google rankings or monitoring over the selected period, most cited first. Citation counts include pooled daily answers and follow the period and retention rules.
Set
with_summary=true on the sources list to add its state, source mix, site and page totals, and row changes. Both lists accept owner, source_type, names_you, content_topic, q, sort and direction; cited pages also accept domain. List search changes the rows; population totals keep their documented scope.
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 questions 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, citation count, action_id and insight, which Insights and their work describes. The title names the route the sourceâs outreach takes. 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 its live outreach and correction actions, highest priority first. Use actions_limit and actions_offset to page actions; the default returns no actions. Nested actions 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, topic and question count. Its topicâs tracked_topic_id, market, audience and band refer to the same tracked topic; copies in other markets or for other audiences have their own bands.
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.
An actionâs long-form content_piece returns its settled draft, writing stage and fields through GET /v1/actions/{action_id} and MCP get_action. Each field carries name, label and value for that version. A pieceâs stage is ordering, researching_and_writing, applying_comments, your_review, approved, publishing, published, stopped, failed or paused. Its report contains questions, sources and checked references when available. has_brief is deprecated and is false for pieces without a retained brief. See Content Studio for the stages and what remains available while a version is checked.
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.
Question AI searches
Question lists and details, includinglist_prompts and get_prompt, carry ai_searches. Each item has text, engine, answer_id, observed_at, segment_id and google_rank. The rank object has state, position, read_id, checked_at and failure_reason. The AI searches definition states freshness, the five rank states and the weekly check budget. These are engine leads and never buyer evidence or page-coverage questions.
Question details, including get_prompt, also carry google_searches: one entry for each search text and market, with text, country, language, engines, answers, searches_mo, volume_state, google_rank, keyword_id and last_searched_at. Entries come most-run first and the list is not paged. The Google searches definition states the grouping, volume states and order.
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 questions and answers citing it, its citations in each weekly report, each rubric pillar, its checks against competitor 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 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 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 question 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 one item per tracked topic independently of the content check. Its id and tracked_topic_id identify one subject in one market for one audience. topic_id links copies of the same subject. Each item includes market, audience and audience_id; All buyers has a null audience ID. scores is the topicâs Heralded Score on all, ai and search under the same period and filters, equal to get_scores filtered to that tracked topicâs id and the same side. The result band uses the Heralded Score and is Not measured without one. Topics through the API defines leaders, filters, sorts and detail sections.
cited_share divides counted answers citing at least one own page by all counted answers under the period and figure filters. An answer counts once even when it cites several own pages or appears in overlapping reports. The object carries value, the percentage, citing_answers, answers and state. Incomplete citation facts make value and citing_answers null with state: "unavailable". Zero answers give a null percentage and state: "not_measured". A measured zero means answers were counted and none cited an own page. Row and head figures use the same population.
coverage_questions carries each questionâs key, label, segment, state and the pages answering it, from the selected reportâs frozen coverage. An unanswered question adds its topicâs insight, which Insights and their work describes. unanswered_questions counts only questions judged unanswered, once per tracked topic. It does not count unknown questions. own_pages combines judged, cited and ranking own pages; each pageâs citations counts distinct answers to this topic citing that page. Search clicks and Visits from AI read the properties connected now and retain their own 28-day windows. The headâs Visits from AI counts each document once across topics.
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.
On a tracked topic, demand sums the latest known monthly volumes of its country keywords in its market, regardless of the month fetched. demand_countries gives each countryâs country, demand and volume_partial. The topicâs volume_partial is true when any keyword volume is unknown or a country has no volume data. Confirmed zero and no data contribute zero. A sum is null when all its volumes are unknown. Global volume targets the United States. Suggested topics have an empty country split.
Suggested-topic demand and question evidence searches_mo use one country in your topicâs market that speaks its language. Europe in English uses the United Kingdom, Belgium in Dutch uses Belgium, and Global uses the United States. If no country in the market speaks your topicâs language, these volumes are unknown.
Topic lists add bands and connection availability. They describe your tracked topics whichever view you read. Use band, q, sort and direction to select rows. One topic adds its Answers link, question scores and trends, cited pages and live actions. A suggested topic has no score, and its id is s: and its suggestion id.
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âs checks, and pages from the weekly report Website shows, the pages on your site. readiness counts pages read, AI-readable and blocked on that reportâs site map, the same counts as Website. Before the first Website assessment, it counts the pages the AI-access checks measured. 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 its 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 page types, check action ids and page status words. status, cited, page_type, q, sort, direction and the Website filters 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.
Website
A findingâsinsight.work identifies the canonical work returned when you file from that insight. Its status comes from the work projection, as does action.status on the newest open matching work. For example, an in-progress change waiting for your approval says Needs you. A delivered change says Live. Insight filing results carry the same status. On insight reads that do not load a work projection, status is null.
get_audit and GET /v1/brands/{brand_id}/audit carry website, the Website score with its findings, from the newest weekly report that finished reading your site. meta.data_as_of names that report. While a newer report is still reading the site, or after it fails, the previous completed Website read stays available. Its freshness fields identify the date and refresh state. Before any report completes a Website read, website.state is pending, score, coverage and versions are null and the lists are empty.
The AI-access checks use their own last good crawl, identified by meta.surfaces["website.ai_access"]. Their date can differ from the Website assessmentâs date. A pending or failed content read keeps the previous crawlâs checks available.
Once a Website assessment is available, meta.surfaces["website.pages"] identifies that weekly report on the Audit and Pages reads. Its site map supplies the page addresses and AI-access statuses, and its Website assessment supplies their findings. Before the first assessment, the page inventory and its freshness follow the last complete crawl.
A finding lists up to
finding_pages_limit of its pages, 10 by default, and pages.count counts them all. Pass finding with finding_pages_offset to read further pages of one finding. A finding that the read has not got returns not_found.
GET /v1/brands/{brand_id}/audit/map and MCP get_site_map return the site map frozen with the same report, named in meta.data_as_of. It reads one language: language takes a code from languages, and the default is the siteâs primary language. counts gives the languageâs broken, orphans and agent_unreachable pages. Each address is one page: http and https, www and trailing-slash spellings fold into the form you entered or the site serves, and only the homepage of the site you entered is typed home. A page on another host, a subdomain included, has its host, and host is null on the siteâs own pages. A page the site lists but the report never read has unread set and no status or facts. Each page has its status, depth in clicks from the homepage, category, alternates, the ids of its findings, the severity of the worst, facts from its HTML and, on a key page, its above_the_fold read and screenshot_url. links are the links between the pages listed. Pass folder, such as /blog, for that folderâs own pages and the folders under it, each with its page, issue, improve and broken counts. A folder lists up to folder_pages_limit pages, 50 by default, from folder_pages_offset, and pages_total counts them all. Without folder, the read lists every page in the language and folders are the top-level ones. site_pages counts the pages in every language, the same number as the Website readâs coverage.pages.
above_the_fold is what a page shows before scrolling: the headline, the offer, audience and reason it states, null where it states none, its heroâs call_to_action and the header_action, whether proof_on_screen shows, the six design checks with a verdict and why, and whether the headline is specific and the action clear. regions place the headline and the action as fractions of the screenshot. screenshot_url is the screenshot three seconds after load, and load_screenshot_url the one at load.
GET /v1/brands/{brand_id}/audit/pages and MCP list_site_pages list your pages on the site, one row each, the same pages as the Auditâs pages, with the same status, cited, page_type, q, sort, direction, limit, offset and cursor, and five more filters. category takes a name from facets.categories and language a code from facets.languages. findings is issue for pages holding an issue, improve for pages holding improvements and no issue, and none for pages holding neither. access is readable, blocked for any page AI engines cannot read, or unmeasured. changed is new or changed since the previous weekly report. sort adds findings, most first, and clicks, the Search Console clicks in the pageâs funnel window. A page with nothing to sort by comes last whichever way it sorts.
The brand pages read also serves headline, a templated summary of the filtered population, and readable, with_findings and cited, counted before paging. with_findings is null if any matching page was not measured; cited is null when citations are unavailable. Each row has section, the URL section past a locale prefix, and finding_ids, the measured findings holding it back. A null finding_ids means no page measurement. These fields also reach MCPâs list_site_pages.
Each page adds its category and the group it falls in (Site, Content, Support or Other), its language, the number of findings that hold it back, the worst of them, claims_stated of the claims_asked of your briefâs category, buyer and difference, and its change. They come from the report that website and meta.data_as_of name. A page that report did not measure has null for them, never zero, and no findings filter matches it. A page with no category or language is in no facet.
changed compares the pageâs own text, excluding tracking images and lines repeated across most pages in each report, such as navigation, templates and popups. An existing page whose earlier report kept no comparable text reading is neither new nor changed. The first report marks no page new.
facets.categories counts the pages in each category under every filter except category, so a count is the total you get by choosing it, and choosing one leaves the others counted. facets.languages counts under every filter except language, so choosing one leaves the others counted. A language filter leaves the categories as categories, counted in that language. GET /v1/scans/{scan_id}/audit/pages reads an Audit you ran in the same way, with no citations, crawler counts or funnel because an Audit has no brand. A Snapshot reads no website, so its pages are unavailable.
Key pages are the pages a buyer sees first. They start with the homepage and pricing, then product, solution and comparison pages, customer stories and About pages. Pages in each group follow click depth, then the number of pages linking to them, with navigation and footer prominence breaking ties. GET /v1/brands/{brand_id}/audit/key-pages and MCP get_key_page list them from the same report. Each has its above_the_fold read with the screenshot_url, its moves, which are what changed in that read, its strip of the last four weekly reads, oldest first, each with whether the page changed and the direction of its checks, and its history of up to 13 reads, newest first, with the changes each made. summary counts the key pages that changed since the previous weekly report, and how many of them say_more or say_less. GET /v1/brands/{brand_id}/audit/key-pages/{path} reads one by its path without the leading slash, and the homepage is the empty path. get_key_page takes the same path and lists the key pages without it. A path that is not a key page of the report is not_found.
GET /v1/scans/{scan_id}/audit/key-pages and .../key-pages/{path} read an Audit you ran. Its history is the one read the Audit made, and a Snapshotâs key pages are unavailable. Only the account that ran the scan reads its pages and key pages.
Key-page moves, changed and summary counts reflect only measured check changes. Changes to explanations, category wording and screenshot positions remain in history without marking a page changed.
One page, GET /v1/brands/{brand_id}/pages/{page_id} and get_page with a page_id, adds what the same report found of it. Each finding carries this pageâs own note and others, the number of other affected pages. It does not carry the site-wide points_off_score. engines gives each engineâs citation count, the number of its answers citing this page and answers_share_pct, their share of that engineâs answers under the selected period and filters. paused_engines names engines paused in the selected report. above_the_fold is set on a key page. against_brand lists the briefâs claims and whether the page stated each, null where the read was unclear, and the claims its text contradicts as conflicts, as that report read the page. copy_and_proof says whether its copy is specific, whether it sounds_generated and whether it shows proof. Each of its checks the page fell short on carries insight, which Insights and their work describes. against_brand is null without a brief, and copy_and_proof where the report did not read the pageâs text.
Competitor websites
GET /v1/brands/{brand_id}/audit/competitors and MCP get_competitor_sites read your competitorsâ websites from the newest weekly report with a completed comparison. meta.data_as_of names that report. rivals carries each competitorâs key, page count, new and removed pages, key pages changed, homepage checks, proof and copy similarity. A homepage has screenshot_url and above_the_fold. The key joins the same competitor in /v1/brands/{brand_id}/competitors/{key}.
changes pages the weekâs moves from the reportâs frozen feed. A move is one competitorâs changes of one type, and its url is the shallowest of their pages. Moves come homepage first, then pricing, other key pages, new pages and removed pages, with more pages first within a type. competitor selects a competitorâs key, and change selects new_page, removed_page, homepage_changed, pricing_changed or key_page_changed; with change, changes lists each page of that type instead of moves. total counts the moves, or with change the pages, after those filters. A file such as a PDF or an image is never a page: it is left out of changes, and a competitorâs new and removed and that weekâs activity do not count it. The report keeps up to 200 changes, so this total can be smaller than the competitor tableâs counts. Use limit and offset, or next_cursor with the same filters, to page it. as_of pins the weekly read.
Each change adds nullable before, after and screenshot_url. Homepage and pricing comparisons use stored weekly values only. Each snapshot has week; a homepage snapshot includes headline and checks, and a pricing snapshot includes pricing with its stored plan names, prices and periods. Missing readings stay null. before comes from this brandâs latest stored earlier detection week for the same host and page. after is available only when the siteâs stored week matches the changeâs week. A homepage change can include its current screenshot_url; no earlier screenshot or full text diff is reconstructed. Other change types leave these three fields null. On your own brandâs reads, each change also carries insight, which Insights and their work describes.
GET /v1/brands/{brand_id}/audit/competitors/{key}, or MCP get_competitor_sites with key, returns competitor with its homepage read, pricing, page counts by category and weekly activity, plus its paged changes. An unknown key returns not_found. pricing.plans states each planâs name, price and billing period as its page writes them. Pricing that cannot be read has state not_readable and plans null, never a zero price.
GET /v1/scans/{scan_id}/audit/competitors, or MCP get_competitor_sites with scan_id instead of brand, reads an Audit you ran. Only its owner can read it. Base carries homepage screens with proof and sameness null; Full adds those measurements. A Snapshotâs comparison is unavailable. Scan reads use limit and offset for paging.
Topics and keywords return tracked_total and archived_total for their tabs, separately from the current filtered listâs total. A topic is archived when you stop tracking it. A keyword is archived when it or its tracked topic is archived.
Keywords
GET /v1/brands/{brand_id}/keywords and MCP get_keywords list the keywords you track, and /keywords/{keyword_id} or get_keywords with a keyword_id reads one. The list takes period, view (tracked or archived), topic, market and audience for the tracked topic selection, sort (searches, keyword, best_rank, clicks, score, markets_top10 or change), direction, limit, offset and cursor. It defaults to 20 rows, ordered by searches descending. keyword defaults to ascending. Missing values come last in either direction. clicks orders by Mentioned and change by its signed change in points.
You can narrow the list with these optional filters. They select keywords before grouping, sorting and paging.
tracked_total and archived_total are each viewâs total under the requestâs filters and grouping: keywords, concepts with group=concept, topics with group=topic, or markets with group=market. Archived keywords appear only with view=archived, including in grouped lists.
The keywords list also returns headline, one sentence on where the brand ranks on Googleâs first page, written from templates with no model call. It covers the tracked keywords with a successful check in the requested segment and topic, whatever the other filters, grouping and paging, and is null for view=archived and while no keyword has been checked. It stays in English for every market.
Grouped keyword lists
group=topic returns paged topics and an empty keywords list. Each row carries its topic with id, tracked_topic_id, name, market and audience, the number of selected keywords and distinct country-and-language markets, and its own full keyword rows in members. Use tracked_topic_id to open the topic. Copies in other markets or for other audiences have separate groups, volumes and checks. A meaning tracked in two topics appears under each with only that topicâs members. Members, volume totals and best ranks follow the concept rules below. members_checked counts members with any fetched check. rankings counts members checked in the period, and checked_top_3 and checked_top_10 count their latest ranks in those bands, out of rankings. The rowâs mentioned uses the Search sideâs coverage rule, with change and an empty trend, so it agrees with the Topics page and the summary filtered to that topic under the same selection. sort=keyword orders by topic name and sort=markets_top10 by checked_top_10.
group=concept returns concepts and an empty keywords list. A concept joins the selected keywords with the same normalised English meaning, across topics, audiences and markets. English wording is its own meaning. A keyword with no English meaning stays separate. Each member keeps its own id, checks and history. With topic, a concept with a selected member in that topic is kept with its selected members in other topics, while concepts_total, keyword_markets_total, rankings_total and summary count the topicâs keywords.
total, limit, offset and next_cursor count concepts in this view. Ask for limit=10 for a page of 10 concepts.
group=market returns paged markets with keywords empty. total counts market rows. Each row carries country, language, the number of selected keywords, rankings with a fetched check in the period, searches_total, volume_partial, top_3, top_10 and its Search mentioned figure with change and an empty trend. Volume totals follow the concept rule. Rows sort by total searches descending, then country A to Z with Global last.
With any group, or with_summary=true, concepts_total counts concepts in the selection, keyword_markets_total counts selected keywords, and rankings_total counts selected keywords with a fetched check in the period.
with_summary=true also adds summary. Its mentioned is Search Mentioned over the selection, with change and an empty trend. Without position, ai_overview, mentions or q, the tracked summary equals scoresâ Search Mentioned for the same period, topic, audience and market. markets counts distinct country and language pairs. positions counts top_3, top_4_10, not_in_top_10 and unchecked, which sum to keyword_markets_total; each reads the keywordâs latest fetched check, which can be older than the period. top_10 serves the combined top-10 count. checked_top_3 and checked_top_10 count only the keywords checked in the period, out of rankings_total. Without grouping or the summary flag, these optional response fields are omitted.
Keyword detail
A keyword is a results page read, not a sample of keywords. Its figures are shown as soon as one check has fetched its results, and the range runs from the share Heralded read to that share plus the share it could not read. How a keyword is measured explains the method. A keyword that is archived or paused, or that no check has fetched, has anull clicks_showing_you and no score. Keyword detail keeps its figures.mentioned and figures.recommended shares; figures.heralded_score has state not_scored and a null value. best_rank, top10_naming_you and the results come from the latest check that Google answered.
One keyword adds figures, its heralded_score, mentioned and recommended with range, change and trend, and results, the ten results of the latest check. Each result has its position, url, title, domain, owner (own, competitor or third_party), click_share, names_you, recommends_you and read_state. For an unread third-party page, names_you and recommends_you are null. Competitor pages are always false for both. Your own pages always have names_you: true and recommends_you: false. prompts lists the topicâs questions for the keywordâs tracked topic, those the engines searched the keyword for first with the engines that did. tasks lists the live actions about your pages in the results, highest priority first.
rank_series is your best Google position at each weekly report that figures.mentioned.trend charts, oldest first. A point has the same at and the same break as that trendâs point, so a new baseline falls on the same date on both charts. Its state is ranked when one of your pages is in the reportâs newest fetched check of the keyword, not_in_top_10 when that check was fetched and none of your pages is among its ten results, and unchecked when the report holds no fetched check of the keyword because it failed or was not read. position is your best place, 1 to 10, and is null unless the state is ranked. New states may be added; handle unknown values gracefully. When a report holds a weekly check and a later daily check, the later one counts, so the latest point equals best_rank whenever the latest report holds the latest check. The series is empty while figures is null.
Free Base audit allowance
GET /v1/account/free-audit and MCP get_free_audit return available and resets_at for your verified emailâs Base audit. You can start one Base audit per 30 days, separately from your free Snapshot. A Base reserves its allowance when you create it and uses no scan credit. A failed run or abandoned brief releases the allowance. The status does not reserve a start or check the daily platform ceiling.
Quick audits need no account and use no scan credit. Each IP can start three per UTC day, within a platform ceiling of 300 per UTC day. Quick counts toward the per-minute start limit. Its report expires 30 days after delivery, and an expired link answers 410 report_retired. Baseâs separate platform ceiling is 100 starts per UTC day. Every admitted Base counts toward that dayâs ceiling, including a failed run.
First-screen rewrites
Each brand inGET /v1/organizations/{organization_id}/usage, and MCP get_usage, carries first_screen_rewrites: the free first-screen rewrites it has started this calendar month (UTC). used counts the rewrites started, limit is the most the brand gets in a month, and resets_at is when the month turns and used starts again at zero. limit is 0 for a workspace with no plan. A draft that could not be made returns its place, so used falls. See First-screen rewrites.
Scans
GET /v1/account/free-snapshot and MCP get_free_snapshot return the status for your verified email. available is true when your next Snapshot is free, with resets_at: null. Otherwise available is false and resets_at is the UTC time your next free Snapshot opens. The status belongs to the person who issued the key or signed in to the assistant, across their workspaces. It does not check the daily platform cap or reserve a start. See Snapshot for the free allowance and failure rules.
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, market, started_at, completed_at and heralded_score, the score the scan issued. market is the Snapshot reportâs market label, or null for weekly and daily scans. The same field appears on GET /v1/scans and in the rows returned by MCP get_scan. 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 Snapshotâs profile was not run 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.service_unavailable: a service Heralded relies on, not your site, kept the Snapshotâs profile from drafting for 24 hours. See Starting a Snapshot.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/audits lists the Audits you ran, newest first, with the same paging and cursor. Each row has id, state, domain, started_at, completed_at, progress_pct and failure_reason, as on the scan lists. A delivered Audit has a share_id, which reads it at GET /v1/scans/{share_id}/audit. It lists only your own, with an API key or signed in.
Both account lists accept an optional domain, such as ?domain=seedblink.com, to return only your scans of that domain. The filter applies before paging; keep it unchanged when following a cursor. Omitting it lists all your sites.
GET /v1/scans/{scan_id} and get_scan read one scan. questions_asked is how many questions it asks the engines. A Snapshot asks 20, or 12 to 19 when fewer of its drafted questions passed Heraldedâs check. It is null before a Snapshotâs questions are fixed and on an Audit. 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 personal Snapshot no brand holds is read only by the account that ran it. A service Snapshot belongs to its tokenâs workspace and is read by people who can read that workspace.
The one-scan read gives a Snapshot whose profile waited 24 hours without a run state: expired and a null failure_reason: nothing failed and nothing was charged. The lists show the same Snapshot as failed with brief_abandoned.
Before a Snapshot runs, the one-scan read also carries what its page shows:
profile: the draftedbrand_name,descriptionandmarket, which isglobal,europeor a country code. It isnullwhile the profile drafts and once the Snapshot runs.run_request: Run pressed before the Snapshot started. Itsstateisrequesteduntil the profile is ready,stoppedafter an edit or Stop, when the Snapshot needs Run again, orneeds_actionwhen it could not start, with the error code inreason, such asno_creditsorfree_snapshots_exhausted. It isnullbefore Run and once the run starts.payer: who pays, recorded on Run and charged when the run starts.byisfree_snapshotorcredits, andorganization_idnames the workspace whose credits pay. A run that needs action keeps the payer it waits on: buying Snapshot credits for that workspace from the Snapshotâs page starts it. A running or finished Snapshot keeps the payer it charged. It isnullbefore Run, after a stop, on an expired Snapshot and on other scans.
GET /v1/scans/{scan_id} and get_scan, with kind: audit. It carries audit_progress instead of engine progress or issued AI figures. The scan lists keep their existing kinds. A Quick no account owns is read by share link alone.
audit_progress is the same on GET /api/scans/{scan_id}. Its phase is discovering, reading, judging, done or failed. found counts the pages the auditâs selection rules kept, including pages beyond its read limit. It appears once planning finishes, so it has the same meaning as the reportâs coverage. read counts pages read so far, updating while the crawl runs. planned is the runâs page limit clipped to found, and shots counts screenshots used by the run. Other scan kinds have audit_progress: null. The tab that starts an anonymous Quick can watch its progress with x-scan-mutation-token from the start response.
issued.missing_question names the buyer question your strongest scored competitor was named for most often while you went unnamed. It carries question, query_id, competitor and answers, the number of qualifying answers. It reads the scanâs frozen answers and excludes branded questions. A question qualifies only when your brand is named in fewer than half its answers and the competitor is named more often than you. The strongest competitor has the highest issued Heralded Score among the scanâs measured competitors. Competitors tied on score follow name order; questions tied on answer count follow the order asked. The field is null if there is no scored competitor or that competitor won no qualifying question. It does not substitute a weaker competitorâs question.
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. moves are its priority actions, best first, with the fields the shared readâs moves carry. content_pass says whether the read is still running, failed or done, and the fields after it fill in once it is done. An Audit also carries website, read from its own run with the fields of a brandâs Website except series, next_read_at and change, and with no actions; it is null on a Snapshot. brief is what the scan was judged against: the brand, category, buyer, difference, tone and competitors, and each buyer question with the page the read matched it to. look is the brandâs logo, colours, fonts, buttons and corner radius as its homepage showed them. GET /v1/scans/{scan_id}/audit/map returns an Auditâs own map, as a brandâs map reads. A Snapshotâs map is unavailable. Only the account that ran the scan reads either, 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.
For brands with Ecommerce on, the prompts and competitors reads include product-card counts, shares and read states. The Products read uses the same definitions and filters. These fields are null for brands with Ecommerce off and hidden on the competitorsâ Google search view.
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.
market is the reportâs stored Your market section. MCP get_shared_snapshot returns the same field. It is null on a run without market research. Its status is pending, complete or unavailable; figures is filled only when complete.
figures carries vertical, scope, demand, ai_summary, chatgpt_estimate, panels, top_searches and the structured verdict. scope names the market, the countries that answered, how many were asked and whether the figures are floors. Demand, AI summary share, panels and top searches have kind: measured; ChatGPT has kind: estimate. Panel brands carry their share and 95% range in low and high. constants_version identifies the constants used for every figure in the section. These values stay as issued, including the exchange rate and ChatGPT ratio. Google and ChatGPT figures are never added together.
This shared read carries the same missing_question at the top level. readiness_status is processing while a late site-check read can still change the report and ready when that work has ended.
Each scan.axes.by_prompt rollup has leader, the brand recommended in the most answers to that question. It is null unless a brand has at least two recommending answers. A tied leader has name: null and tied: true. The subject brand is included. If a unique leader is not the subject or one of the competitors shown in the report, name is null and hidden is true.
GET /v1/shared/scans/{share_id}/questions/{query_id}/answers and MCP list_shared_question_answers read one questionâs answers, 10 per page. The REST route needs only the share link. Each answer includes engine, run, its position within that engine across the whole question starting at 1, a strength mark with its value and label, an excerpt of up to 600 characters, highlights, named brands with their marks, and cited_urls. text carries the full retained answer as Markdown, preserving headings, lists and tables. text_highlights marks the names in that Markdown source. Highlight offsets count Unicode code points in their respective text, with an exclusive end. text_retained is false when the answer text has expired; your brandâs stored mark and citations remain. Other brandsâ marks are not measured if their retained strength reading is unavailable. Both text fields are empty if the answer has no retained text or no reading of the brands it names. The position follows the reportâs answer order and stays unique for each engine across pages, including when a weekly report pools answers from earlier runs. Pass next_cursor as cursor for the next page of the same question.
GET /v1/shared/scans/{share_id}/products and MCP list_shared_products list every product of an ecommerce Snapshotâs question or brand, 20 a page by default and 100 at most. The shopping section keeps only its first 50 products and, for each product, its first 20 questions. Pass query_id for the products shown in answers to one question, maker for one brandâs products, or both. maker takes the key that the shopping sectionâs brand_keys serves for your brand or a competitor the report names. brand_keys maps each name the report shows to the key of its brands figures, so you never normalize a name yourself. Each product carries its figures in that scope, its maker and maker_key, and its price and seller in offer. Products shown in the most answers come first, then the best placed. Pass next_cursor as cursor for the next page with the same query.
total counts the products the report may name, and hidden_products counts those of brands the report does not show, with hidden_brands counting those brands. The two never overlap, and together they equal the questionâs product count in the shopping section. A hidden brandâs products are counted and never listed, and asking for the brand by maker returns 404.
GET /v1/shared/scans/{share_id}/products/{product_id} and MCP get_shared_product return one productâs details as the report shows them, including products outside the shopping sectionâs 50. Its questions page with questions_limit and questions_offset over questions_total. A product of a hidden brand, or one the report never showed, returns 404. Both reads follow the reportâs link rules, so revoked links, restricted links and another reportâs question or product return 404.
GET /v1/shared/scans/{share_id}/engines/{engine_id}/sites and MCP list_shared_engine_sites read all sites that engine cites in the report. sites lists each domain without www. and its citation_count, most citations first, with domain order breaking ties. A cited page counts once per answer, with campaign tracking parameters removed. The read uses the same rendered answers and hidden-brand filter as cited_urls. It needs the same report access as the shared answers read and returns an empty list when the engine has no visible citations.
A Snapshot names only the competitors its report shows. Other names and their aliases become âanother brandâ in both text fields, including Markdown link labels, titles and destinations, positioning engine passages, flag titles and passages, and understanding-row quotes, values and gap notes. Cited URLs and positioning flags whose URL or domain exposes a hidden name are omitted. Each positioning flagged count matches the flags returned. The readâs top-level brands lists each shown brandâs name and answers count across the whole question. Top-level pages lists each visible cited url and the number of distinct answers citing it, across every page of answers. cited_urls and pages remove campaign tracking parameters, including utm_*, and combine matching URLs. A page cited twice in one answer counts that answer once. Unknown share links and questions outside the report return 404. Partial reports and reports whose measurements cannot be served return 410 with scan_version_unsupported.
A failing site_checks entry carries fix, the steps to take when guidance is available. Passing and unmeasured checks have an empty fix list. Every ReadabilityCheck in site_blockers.gates and site_checks carries group: reach for crawler access, page access and text without JavaScript; understand for structured data, content and site hygiene; fast for speed; and trust for HTTPS and domain authority. The Audit dashboardâs existing check groups retain their display names.
moves are the reportâs priority actions, best first. Each has its play, title, rationale, the finding it answers, and effort, what is left for you to do. grounds and gain read as on an action, as Action fields describes. pointer_type and pointer_target name the site check or the page the work is on.
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.
GET /v1/shared/audits/{share_id} reads a delivered Quick with its share link alone and no API key. It returns the frozen website, key_pages with above-the-fold checks and screenshot_url, and map. It includes no raw claims or workspace data. Base and Full results stay owner-only and return 404 here. Quick results are deleted 30 days after delivery; a retired link returns 410 with report_retired, and an unknown link returns 404.
Reports
GET /v1/brands/{brand_id}/reports lists the brandâs reports, newest period first, including those issued for a site the brand tracked before a domain change. Pass kind, weekly or quarterly, to read one kind. Each row has its id, kind, brand_id, the brand row the report measured, domain, the site it measured, period_start, period_end, issued_at, pdf_ready and shared_with, the number of people it was sent to. The headline is composed text, which the app shows and the API leaves out. total counts the reports of that kind. A quarterly reportâs period_end is the last moment of its quarter.
GET /v1/brands/{brand_id}/reports/{report_id} and MCP get_reports with report_id return one report with its body, as it issued. Nothing changes a body after it issues. A quarterly reportâs figures pool the weekly reports completed in its quarter, with their change against as many reports before them.
GET /v1/brands/{brand_id}/reports/{report_id}/recipients, and MCP get_reports with report_id and recipients=true, list who the report was sent to, newest send first: each personâs account_id, name and sent_at, paged with limit and cursor. total counts them. Someone you can see only as a teammate is named A teammate.
aiandgooglestate where the brand stood on each side. Each figure hasvalue,low,high,stateandchange, the paired testâs verdict, withdelta.aiaddsunderstood,praised,rank,rank_ofandtrend, the Heralded Score at each of the last eight weekly reports.moved.changesare the changes that report listed, each with theid,source,kindandatthatlist_changesserves, and theroute,paneandkeyit opens on.products, for a brand that sells products online, holds the shopping figures the report measured:answers_with_cards,in_product_cards,seller_ownandprice_matches, each withvalue,low,highand theanswersit was read from.alertslists the changes it saw on your products, most seen first: each haskind,price_shown_changed,product_droppedorproduct_replaced, theproduct_id,at, the number ofanswersit was seen on, and asentence.evidencesays whether the shopâs catalogue and Google Shopping were read incomplete,partialorunavailableform, with anotenaming what could not be read.productsis null for a brand that does not sell products online.work_completed.itemsare the actions delivered in the period, each withaction_id,title,issue_type,delivered_at,resultandresult_at.new_pages.pagesare your pages the reportâs answers cited for the first time, each withurlandtitle, andnew_pages.totalcounts them. A quarterly report gathers its weekly reportsâ pages.competitors.rowsare the tracked brands by score, each withrank,brand_key,brand_name,domain,is_you,score,change,delta,mentionedandrecommended.nextcounts the open work at issue inneeds_you,suggested,in_progressandscheduled, and givesnext_report_at,nullwhile weekly reports are paused.focuslists thetopics,competitorsandmarketsstarred at issue, each as Strategy serves a star, with where the brand stood. A topic or market line hasscore, your Heralded Score there with itschange; a topic line addsrankandrank_of. A competitor line hasthem, its leaderboard row, besideyou, yours.goal, on a quarterly report, is the goalâsrevisionthat was current at issue, with itsmeasurethen, as Strategy serves a goal.weekslists a quarterly reportâs weekly reports.made_with_heraldedisfalsefor a brand in a managed account.
state. ready holds what the report measured. missing marks a section the report had no data for when it issued, such as a first reportâs google side or its moved, and it stays missing. not_set marks a section the brand had not set up, such as focus and a quarterly reportâs goal.
Instrument breaks
Trend points returnbreak, null within a baseline, or {at, parts, engines_added, engines_removed, comparable} where the instrument changes. parts names engines, language, market, score_version or answer_pack_version. The pointâs date marks the change. comparable is true for engine or language changes alone. A country, pooled definition or version change sets it false and starts a new comparable series. Existing breaks arrays remain available on reads that already returned them.
Competitor-site reads return reason: no_read, read_running or read_failed while incomplete, and null when complete. Change targets keep their observationâs applicable figure filters.
Strategy
GET /v1/brands/{brand_id}/strategy and MCP get_strategy return goal, revisions, focus and moving_away_from. Strategy and goal explains each.
goal is null before you set one. Otherwise it carries revision, goal, target, reason, started_at, prompts and measure. target is null or {value, date}, a Recommended percentage with an optional date. reason is goal_set, goal_changed, focus_changed, profile_changed or domain_changed. prompts counts the questions the revision is measured on.
measure.progress is measured when a report since the revision started is compared with its baseline, first_report before the first goal has a later report, and not_comparable when the revision started after the newest report or a market it is measured on changed setup. baseline_at and measured_at date the two reports. recommended, mentioned and understood are figures read on the goalâs questions. A figureâs change is the paired change from the baseline report and is present only when progress is measured. See Change. baseline holds each figure at the baseline report, over the questions and engines both reports measured. It is the current value when the baseline is the newest report, and null when the figure is not measured or a market changed setup.
revisions lists every revision newest first, the current one included, each with ended_at, when the next one started. Figures never compare across two revisions.
focus holds topics, competitors and markets, each a list of {kind, id, name, tracked}, and limit, the most stars of one kind. id is the tracked topic id, the competitorâs key or the marketâs identity. tracked is false once the tracked topic is archived, the competitor is no longer tracked or the market is retired.
Every actionâs focus is {kind, id, name}. kind is topic, competitor or outside, and id and name are null outside your focus. Heraldedâs own recurring work has a null focus.
Brand look
GET /v1/brands/{brand_id}/look and MCP get_brand_look return your brandâs four colours, heading and body font families and sources, whether a logo and a dark logo are set, your default social card style, and the three style cardsâ states. A fontâs source is website, uploaded or default.
The response contains no image URLs. To download a logo or style card, use GET /v1/brands/{brand_id}/look/images/{slot} with logo, logo_dark, mounted, strip or band. The route checks your access and redirects to the image.
Herald greeting
GET /v1/brands/{brand_id}/herald and MCP get_herald_greeting return the opening for the Herald. page selects a page question. scope carries the active page filters as a URL query string, such as engine=gemini&asked_language=local&period=latest. Measurement filters supported by that page narrow both counts to work linked to the questions in its filtered answers. On Work, subject narrows both counts to the same live subject work as Actions. Without these filters, the counts cover the brandâs work.
These counts use the same work and delivered-result rules as Actions. Reading the greeting starts no work and uses no monthly answer allowance.