> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Figures in the API

> What each figure, state and enum value in the API means, and where the method behind it is explained.

The API serves the same figures as the app. This page maps its fields to their meaning. The method behind each figure is under Methodology, linked from each row.

## Reads

The API calls each [weekly report](/concepts/daily-updates-and-weekly-reports) a **read**. Scores, overview, competitors, sources and AI visits take `period`, one of `1w`, `4w`, `12w` or `all`. The default is `1w`.

Every response carries a `period` descriptor. `preset` names your choice, `reports` counts the weekly reports included, and `first_answer_at` and `last_answer_at` give the true dates of their answers, including pooled daily answers. `excluded_reports` counts reports left out because the period crosses a change in how Heralded reads answers.

Scores and overview return figures pooled over that period. Each figure's `trend` has one point per weekly report over the latest 12 reports, or the whole selected period if it is longer. It can extend beyond `period`. The overview's `latest_read`, `headline.text`, `answers_citing_you` and `sources_mentioning_you` belong to the latest weekly report, regardless of period.

The overview also states where the brand stands now, whatever `period` you pick. `next_weekly_scan_at` and `next_daily_scan_at` are `null` while the brand is paused or its organization funds no new scan. `daily_scans_since_weekly` counts the daily scans whose answers no weekly report has pooled yet, `open_action_count` the [open actions excluding setup](/concepts/actions), 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](/methodology/heralded-score#the-score-bands) says how the API names them. `score_context` states what the latest weekly report's score was read from: the brand name, prompts, engines, answers and the dates of its first and last answer. `since_started` gives the score's move since the first weekly report on the current score version, its sentence and one point per weekly report. `verified_actions` lists the newest three delivered tasks that verification credited with a gain, and `total` counts them all. Set `with_diagnosis=true` to add `diagnosis`: the prompts a tracked competitor wins over the last week and you do not, the third-party sources citing competitors and never you, and the drafts ready to answer them.

The overview's default pin is the latest completed scan, daily updates included, and `meta.data_as_of` names it. Its figures still describe the weekly reports in the period. Pass that id as `as_of` to Changes, scores and the other reads to keep one page on the same scans, the daily updates Changes shows included.

Each trend point has its report date `at`, value and range, answer count, state and a readable `break_label` when the reading method changes.

Until a brand's first report completes, the descriptor counts zero reports and each figure has `state: "not_measured"` with a `null` value. [When a figure is empty](/methodology/empty-figures) lists every reason one can be.

## Filters and groups

Scores take the filters the app's pages take: `engine`, `type`, `intent`, `topic` as a topic id, `segment` as a segment's label, and `prompt` as a prompt id. Every figure, its change and its trend then read only the answers the filters keep.

`group_by` also states the five figures per `engine`, `intent`, `type`, `topic`, `segment`, `prompt` or `competitor`, under the same period and filters. The response keeps the whole figures and adds `groups`. Each group's `group` names the value it groups on and leaves the other dimensions `null`. A `competitor` group names the brand by `competitor` and `brand_name`, and `is_you` marks your own. A group exists for each tracked prompt's value, so a group can have no answers in the period. Without `group_by`, `groups` is `null`.

`GET /v1/brands/{brand_id}/scores` and MCP `get_scores` also take `include=engines` for the [Engines table](/concepts/engines), or `include=engine` with an `engine` filter for that engine's pane. The `engines` and `engine` fields carry the same counts, score marks, trends and sentences as those surfaces. The pane includes competitors, strongest and weakest prompts and its five most cited sources. `sort`, `direction`, `limit` and `offset` select table rows or the pane's competitor page. `with_menus=true` adds the four prompt filter menus in `menus`. These additions leave the existing figures and `groups` unchanged and follow the same `as_of` pin.

The engine pane's sources use the same `citations`, `citation_share_pct`, `read_pages_naming_you`, `group` and `ownership` as the Sources read under the engine filter. `names_you` is `null` when no read page could establish whether the source names you.

## Headline figures

Each is in points from 0 to 100 and carries a 95% [range](/methodology/ranges), `low` to `high`.

| Field | Means | Method |
| - | - | - |
| `mentioned` | The share of answers that name the brand. | [Mentioned and Recommended](/methodology/mentioned-and-recommended) |
| `recommended` | The share of answers that recommend the brand, including answers that lead with it. | [Mentioned and Recommended](/methodology/mentioned-and-recommended) |
| `heralded_score` | How the answers treat the brand overall, on a calibrated 0 to 100 scale. | [The Heralded Score](/methodology/heralded-score) |
| `understood` | How well answers naming the brand understand it. | [Perception](/methodology/how-ai-describes-you) |
| `praised` | How positively answers naming the brand frame it. | [Perception](/methodology/how-ai-describes-you) |

The Heralded Score, Mentioned and Recommended leave out [prompts that name the brand](/methodology/how-we-measure#which-answers-count). Every figure carries `value`, `low`, `high`, `answers`, `numerator`, `denominator`, `state`, `change` and `trend`. The score has no numerator or denominator. Understood and Praised count answers naming the brand that were measured for that figure in their denominator.

`state` is `measured`, `too_few_answers`, `calibrating`, `not_comparable` or `not_measured`. An unmeasured value is `null`, never zero. A calibrating figure can have a value and a change, but its baseline has fewer than four reports, so do not call the trend settled.

## Citations

Both come from the latest read and are `{count, of, pct}`: the count, what it is out of, and the share in points. `pct` is `null` where `of` is zero. [Answers citing you and sources mentioning you](/concepts/sources#answers-citing-you-and-sources-mentioning-you) defines them.

| Field | Means |
| - | - |
| `answers_citing_you` | The answers that cite a page on the brand's own site, out of the answers read. |
| `sources_mentioning_you` | The distinct pages on other sites, cited in the answers and read by Heralded, that name the brand, out of those pages read. |

## Change

A change carries `delta`, `low`, `high`, `real`, `direction`, `baseline` and `cells_unpaired`. It compares the period with the preceding reports, as many as the period holds and at least four when available. `baseline` states its report count and true answer dates. `cells_unpaired` counts prompt and engine cells measured on only one side.

**Judge change by `real` alone.** `real` is true where a paired test over the cells both reads measured says the figure moved. Where `real` is false, call the figure unchanged, whatever `delta` says. Two reads' ranges can overlap while the figure really moved, and ranges that don't overlap are not a test either.

A change is `null` without a baseline, without enough measured answers, or when the comparison is not comparable. Its values can also be `null` where no cells can be paired. [Change](/methodology/change) has the test and every case.

## Competitors

| Field | Means |
| - | - |
| `share_of_voice_pct` | The brand's [share of voice](/methodology/share-of-voice): the answers naming it, out of every brand slot across the answers. `null` for a competitor no answer in the period asked about or named. |
| `rank` | The tracked brand's place by Heralded Score. Unmeasured scores follow measured scores. |
| `heralded_score`, `mentioned`, `recommended` | The same period figures, states, ranges and changes as the figures read. |
| `is_you` | Whether the row is the brand itself. |

`share_of_voice` states the population, answer count, excluded answers and each brand's numerator and denominator. Its rows identify each brand by `name` and `is_you`. Its `population` is `all_answers`, or `weekly_answers` when pooled daily answers did not receive the brands-named reading. `discovered` lists untracked brands with `name`, `domain`, `value`, `low`, `high`, `answers` and `state`. Their Heralded Score uses the same period's answer rows and estimator as tracked brands. A measured, comparable period needs at least three answers naming the brand; below that, `state` is `too_few_answers` and the value and range are null. Discovery includes every weekly scan in the period. `channels` lists platforms separately, with `name`, `domain`, `mentioned`, `answers` and `prompts`, without a score.

The competitor list and MCP `list_competitors` accept the shared figure filters. Set `with_page=true` to add `page`, the [Competitors page](/concepts/competitors)'s sentence, share-of-voice bar, leaderboard, brand roster capacity and discovered and channel cells. `sort`, `direction`, `limit` and `offset` select the leaderboard page; `discovered_limit` and `discovered_offset` select the discovered and channel pages. `with_menus=true` adds the prompt filter menus. All measured sections follow `as_of`; roster capacity follows the current plan and tracked competitors. The page read's default pin is the latest completed scan, including daily scans, so its panes can open daily-only discoveries. The figures still describe the selected weekly period.

`GET /v1/brands/{brand_id}/competitors/{key}` and MCP `get_competitor` read one tracked or discovered competitor. `key` is its brand key or name, such as `linear`. Both accept `period` and the figure filters `engine`, `type`, `intent`, `topic`, `segment` and `prompt`.

The response includes `score`, `trend` and weekly `history`, head-to-head `versus` and `figures`, all `lost` and `won` prompt rows, `engines`, and `tracked_since`. Each comparison's `gap` is your value less the competitor's. `lost` means the competitor scores above you, and `won` means you score above it. Ties and missing scores appear in neither. `pages` lists the five most cited pages on the competitor's site; `pages_total` counts every cited page on that site. Counts and page titles come from the scan's frozen citations. An unknown key or your own brand returns `not_found`.

`citation_evidence` is `complete`, `partial` or `unavailable`, and `unavailable_scans` counts the period's reports that lost citations before they were frozen; counts derived from citations are floors unless it is `complete`.

`sentence` and `versus_sentence` describe the measurement and comparison. `capacity` and `can_track` state the current brand roster's size and limit. `answers_link` opens the answers naming that competitor under the same period and filters. These fields also arrive through MCP `get_competitor`.

The competitor read and MCP `get_competitor` also take `page_url` to add that rival-owned page's pane in `rival`, including its explanation, cited prompts, queued actions and answers link. With `page_url`, `key` can be the page's hostname instead of its competitor's brand key. The read also opens a URL found only by an unpooled daily scan, with `measurement=daily_only` and its pending note. Without `as_of`, this mode pins the latest completed scan, including daily scans. With it, both the weekly population and unpooled daily discoveries stop at that scan's completion and id; a URL found only later returns `not_found`. The competitor's figures and cited pages still describe the selected weekly period. The Sources cited-page read keeps its existing shape and field meanings. A rival page with no available evidence in an incomplete period returns `measurement` `unavailable` instead of 404. An unknown competitor host still returns 404.

## Perception

`GET /v1/brands/{brand_id}/perception` and MCP `get_perception` return the statement, positioning rows, Understood and Praised, claims, negative prompts and sources, and best quotes. They accept `period`, the shared figure filters and `as_of`.

`written` comes from the latest weekly report through the scan pin. Its statement, line to own and positioning rows keep that report's full population, regardless of the selected period or filters. The figures and evidence lists follow the selected period and filters.

Each claim carries its `key`, `wording`, `verdicts`, quote, trend and action state. `verdicts` splits the answers into `agrees`, `partly`, `contradicts` and `doesnt_say`, with their sum in `answers`. Counts stay beside the wording those answers were checked against, even after you edit the profile.

Pass that key to `GET /v1/brands/{brand_id}/perception/claims/{claim}`, or as `claim` to `get_perception`, for its quotes, contradicting prompts, engine counts and contradicting pages. Each page keeps its passage and the wording it was checked against. Unknown claims return `not_found`. MCP returns the whole page in `perception` or one claim in `claim`.

Cited-page verdicts and passages and best quotes read the observations kept with each scan, including claim flags on your own pages. Removing an old answer's raw text or citations does not remove this evidence. [Perception](/methodology/how-ai-describes-you) explains the verdicts and page flags.

Use `list_limit` to bound the negative lists or a claim's evidence lists. Page them with `prompts_offset`, `sources_offset` or `pages_offset`; their totals still count the full filtered population. The Perception read includes `menus` for the shared filters.

Set `with_panes=true` on the scores read or MCP `get_scores` to add `panes`, `pane_prompts`, `pane_rivals` and `pane_headline`. These carry the axis labels, evidence, trends, engine and intent rows, recommendations and linked tasks. `figure_only=true` returns each pane's figure with its evidence fields empty. The existing five score fields keep their meanings.

## Prompts

### Keyword measurements

The prompt list, prompt detail and Discover read at `GET /v1/brands/{brand_id}/prompt-suggestions` include `measurement`. It describes keyword numbers, with `country` for the requested market, `measured_country` for the country actually targeted and `language`. A null `country` means Global, which keyword measurements target as the United States. The language uses the product's code, such as `no` for Norwegian.

`coverage` gives the current availability of `keyword_research` (discovery and difficulty) and `search_volume` (monthly keyword search volume), each as `available`, `unavailable` or `unknown`. Unknown means Heralded cannot read a catalog yet. These states apply now, including to older measurements; they are not a snapshot of coverage when a number was recorded. Historical numbers keep their measured market and language. A row's non-null `measurement` overrides the response's context when it differs.

Discover keeps its `demand.source`: `search_console` means the property's impressions, `keyword_volume` means monthly searches, and `engine_searches` means how many engines searched the phrase. Cached Search Console and engine-search rows remain usable when keyword discovery is unavailable.

When keyword research does not cover a market and language, Discover returns an entry in `unavailable` with `provider=keyword_research` and `reason=market_language_unavailable`, and `measurement.coverage.keyword_research` is `unavailable`. It does not return older keyword suggestions. English in Romania has keyword research unavailable and search volume available. `sources.heralded` describes the stage: `no_suggestions` when it finished with no suggestions, `running` while unfinished, or `failed` when it failed.

### Tracked prompts

Each tracked prompt carries, per engine, how that engine's latest answer treated the brand. [How an answer is read](/methodology/how-we-measure#how-an-answer-is-read) defines each rung.

| `state` | The answer |
| - | - |
| `leading` | ranks the brand as the single first choice |
| `recommended` | tells the reader to choose, try or consider the brand |
| `mentioned` | describes the brand without advising anyone to choose it |
| `weak` | names the brand only in passing, or with criticism or dismissal |
| `absent` | does not name the brand |
| `unmeasured` | was not read: a gap, not a zero |

Recommended counts both `leading` and `recommended`.

`list_prompts` and `GET /v1/brands/{brand_id}/prompts` also return each prompt's period `score`, `trend`, engine `marks`, type, search volume and status date. `marks` open the most recent answer in the selected period. The existing `engines` keep describing each engine's latest answer, regardless of period, and `reading` is true while the read of a newly tracked prompt is still asking that engine. `reading` is about now whatever `as_of` pins, so read the prompts again without `as_of` to see the answers it brings. The list defaults to `period=4w` and adds the filter menus and tracked, active and archived counts. Select `archived=true` for archived prompts, or use `search`, `sort` and `direction` to browse the table. Omitting `sort` keeps the existing grouped order; naming a sort orders the selected column. Cursors keep the same ordered population even when a prompt is archived. Each row carries the API-composed `status_note` for paused and archived prompts. Its `cells` describe the engine readings and measured days, including the answer id that opens their evidence. The shared figure filters apply, with `you` selecting `named` or `not_named`, and `topic_id=untagged` selecting prompts without a topic.

`get_prompt` and `GET /v1/brands/{brand_id}/prompts/{prompt_uid}` return the score, competitors and sources over `period`, defaulting to `1w`. Each engine includes its name, latest answer's state and four measured states, answer id, read date and `reading`. With no answer, the state is `unmeasured`, the four states are not measured, and the answer id and read date are null. These engine facts use the latest answer under the same `as_of` scan pin. The read also adds the composed `sentence`, four `tiles` with Yes-answer counts, `engine_cards`, the next trend date, taxonomy provenance and linked work. The shared figure filters scope the same facts. `answers_link` opens their answers with the prompt and filters selected.

To render the Prompts band's four cards, pass `with_cards=true` to the scores read or MCP `get_scores`. Its `cards` use the same figures, trend and composed change labels as the app. `you` and `topic_id` select the same prompt population as the prompt list. Without `with_cards`, `cards` is `null`.

## Answers

Without `period`, `list_answers` and `GET /v1/brands/{brand_id}/answers` return all finished weekly and daily answers once. Set `period` to select weekly reports and the daily answers they pooled. The `names` filter matches the brands detected in each answer and the tracked competitors it names.

Each answer names its prompt, engine and segment, and when it was read. `mentioned` and `recommended` are `null` where the answer was not read for them. `get_answer` and `GET /v1/brands/{brand_id}/answers/{answer_id}` add the retained text, the URLs it cited and the rivals detected in it. Finished answers keep their frozen measurements and detected names after text retention. A running scan's answer uses its live measurements until delivery. A finished answer without a frozen row returns 404.

Lists add `states` for all four axes, excerpt highlights, cited-page counts, detected brands and `text_retained`. The response adds the composed `summary_sentence` and `filter_options`. Request `with_menus=true` for the shared type, intent, topic and segment menus. Answers accept the shared figure filters, `you`, `cites`, `source_group`, `cited_page`, `claim`, `claim_wording`, `content_topic`, `action` and retained-text `search`. Sort by `time` or `sources`, with `direction=asc` or `desc`. With `cited_page`, the response adds `cited_page_label` and `cited_page_key`, the document key of the page the filter matched. The existing `prompt_id` and the shared `prompt` filter select the same prompt; passing both with different ids returns 422.

Single answers add `cited_pages` with stored titles and document keys, full-text `highlights` and the same four-axis `states`. Pass the list's `meta.data_as_of.id` as `as_of` on subsequent lists and single-answer reads to keep one population. An answer newer than the pin, or an unknown or foreign scan pin, returns 404. Omit the pin to open an answer from a running scan. MCP `list_answers` and `get_answer` return the same fields and accept the same selection.

## Sources

Sources are the domains the engines cited over the selected period, including pooled daily answers, most cited first. Counts follow the [period and retention rules](/concepts/sources#how-citations-are-counted). [Sources](/concepts/sources) describes the page they come from.

| Field | Means |
| - | - |
| `citations` | How many times answers cited the domain. |
| `citations_naming_you`, `citations_naming_rivals` | Of those, the citations whose cited page names the brand, or names a competitor. |
| `prompts` | How many prompts' answers cited it. |
| `engines` | The engines that cited it. |
| `ownership` | `own`, `rival` or `independent`, following the [Sources ownership rule](/concepts/sources). |
| `group` | The kind of site: `own`, `rival`, `review`, `editorial`, `community`, `vendor` or `other`. |
| `priority` | The site's 1-based position among the sites worth pursuing under the selected filters. `1` comes first; `null` means the site is outside that set. |
| `priority_reason` | Why the site is worth pursuing, or `null` when it is outside that set. |

Set `with_summary=true` on the sources list to add its `state`, `sentence`, `cards`, source `mix`, site and page totals, and row labels and changes. `with_menus=true` adds the filter menus to sources or cited pages. Both lists accept `owner`, `source_type`, `names_you`, `content_topic`, `q`, `sort` and `direction`; cited pages also accept `domain`. List search changes the rows, while the cards keep the population selected by the other filters.

The sources list keeps citations as its default order. Set `sort=priority` to put the sites worth pursuing first, ranked by the search demand of the prompts citing them, weighted by each site's authority. The remaining sites follow by citations. The fractional score stays internal; `priority` is a position in the ranking.

With `with_summary=true`, `worth_pursuing` returns up to three actionable suggestions and `worth_pursuing_total` counts them all. Each suggestion carries its title, reason, source type label, citation count and `action_id`. That id is `null` when no pitch is filed or its pitch was withdrawn. A filed pitch in state `new` carries its id. Dismissed, deferred, started and settled pitches leave the suggestions but keep their place in the priority order. Search, sorting and pagination affect the table rows alone.

One source adds its Answers link and task list. Use `actions_limit` and `actions_offset` to page tasks; the default returns no tasks. Nested tasks use `kind`, the same field as the actions read. Source and cited-page histories include comparability keys and breaks. One cited page also states its owner, content type label, topic and prompt count.

## Setup actions

`list_actions` and `GET /v1/brands/{brand_id}/actions` include one-time setup with `kind: "setup"`. A setup action finishes when its setting or connection is in place. It settles without claiming a measured gain in the answers.

## Visits from AI

`list_ai_visits` and `GET /v1/brands/{brand_id}/ai-visits` return your owned pages with `id`, `url` and `ai_visits`. Use `limit` and `offset` to page through them. `period` controls their order by citations.

`ai_visits` counts sessions GA4 attributes to AI assistants in a 28-day read: the one of the newest weekly report in the period that read the GA4 property connected now. Its own inclusive dates are `coverage.start` and `coverage.end`. These are separate from the selected period's answer dates. Do not describe the visits as totals for `period` or sum overlapping GA4 reads. A query-selected page stays unmeasured unless it has a measured path-only alias, because GA4 landing pages omit query strings.

The count is a floor because assistant visits often carry no referrer. `coverage` and visits are `null` without a connected GA4 property, before its first complete dated read, when that read is unavailable or incomplete, or when no report in the period read the property connected now. A page outside the read's coverage also has `null` visits. Zero means the read covered the page and found no attributed sessions.

## Pages, topics and Audit

`get_page` and `GET /v1/brands/{brand_id}/pages` return the same pages and Visits from AI, with each page's `citations` and `prompts` over the period, its AI crawls and its rubric. `rubric.score` is the score the newest weekly report with page checks gave the page, and `rubric` is `null` on a page the rubric does not check, such as a legal page. `crawler_hits` comes from the newest weekly report through `as_of`, over `crawler_hits_days`, 28 whole days ending two days before that report started. The counts stay fixed with that report and do not follow `period`. One page adds the prompts and answers citing it, its citations in each weekly report, each rubric pillar, its checks against rival pages and when Heralded delivered it.

Each entry in `crawler_bots` has a `category` of `training`, `ai_search`, `user_fetch` or `search_engine`. Googlebot, Bingbot and Applebot are search engines. The category is `null` for a bot no longer in the vocabulary. Counts cover served requests from every listed bot, including search engines and requests known to be unverified. Sources collect counts daily. When the report records them, it uses connected sources with a successful pull in the preceding seven days. When a source outside your site's plugin reports requests for a day, its counts replace the plugin's counts for that whole day. A WordPress reply carries at most 500 counters. At that limit, Heralded updates the counters received and keeps saved counters the reply omits. Query strings do not distinguish pages in crawler counts. A query-selected page stays unmeasured unless it has a measured path-only alias. Raw crawler counts are kept for 13 months; removing them or changing a connection leaves the report's recorded counts unchanged. A page without a recorded measurement reads `null`; a covered page with no served requests reads zero.

`citation_evidence` is `complete`, `partial` or `unavailable`, and `unavailable_scans` counts the period's reports that lost citations before they were frozen; counts derived from citations are floors unless it is `complete`.

Each pages-list row, single page and Audit page row carries `funnel`. MCP `get_page` returns the same object with and without `page_id`. An Audit row without a registered `page_id` has `funnel: null`.

The funnel's `window.start` and `window.end` are inclusive dates covering 28 whole days, ending two days before the newest weekly report through `as_of` started. This window stays the same when you change `period` or figure filters. It is `null` before the first weekly report. `window.history_days` is how many days back from today your plan reads crawler, Visits from AI and Search Console measurements, and `window.clamped` is `true` when the report is older than that. A clamped funnel has `null` for each of those counts. See [History](/concepts/usage#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](/concepts/usage#history), oldest first. A point has the `start` and `end` of that report's 28-day window and the `search_clicks`, `crawled`, `fetched_live`, `cited` and `ai_visits` the table below defines for it. A figure the report did not record is `null`. Consecutive windows overlap, so a point is a rolling 28 days, not a separate week. It is empty before the first weekly report in that history.

| Funnel field | What it counts inside `window` |
| - | - |
| `search_clicks`, `search_impressions` | Search Console clicks and impressions from the property connected now. |
| `crawled` | Served requests from `training` and `ai_search` bots, verified true or unknown. |
| `fetched_live` | Served requests from `user_fetch` bots, verified true or unknown. |
| `cited` | The page's recorded citations from weekly reports completed inside the window, using the default figure filters. The existing `citations` field keeps its own period meaning. |
| `ai_visits` | Visits from AI attributed by the GA4 property connected now. These are a floor because many visits carry no referrer. |
| `blocked`, `not_found` | AI-category requests with that outcome, across all verification states. Search-engine bots do not count here. |
| `unverified` | AI-category requests known to be unverified, across all outcomes. Unknown verification does not count here. |
| `search_engine_crawls` | Served search-engine requests, verified true or unknown. |

Each count is `null` when its source did not measure the page for that window. Search and visit reads covering another window do not fill it. `cited` is `null` without weekly reports completed inside the window, or when any of those reports lacks complete citation evidence. A measured zero remains zero. Plugin crawl counts are a floor: they cover requests the plugin sees. WordPress reports unknown verification, so its served AI requests fill `crawled` and `fetched_live`.

Pass `url` to the pages list to get `resolved_page_id`, or `null` when the URL names no live page of your own. One page includes its content work, Answers link and each citing answer's id and states. Set `with_details=true` to include `search`. Set `with_takes=true` to include `takes`: for each prompt and engine whose latest answer, up to the pinned scan, cited the page, the passage the answer lifted from the page and the claim it supported. Takes are paged with `takes_limit` and `takes_offset`. A take is kept with its scan, with the page wording and answer read then, so a later page edit, scan or answer-text expiry does not change what `as_of` returns. A take shows once Heralded has checked that its passage supports its claim. `pending` counts takes not checked yet, `rejected` those that failed the check and `unavailable` answers whose take could not be kept. None of them is in `items` or `total`. Open an item's answer at `answers/{answer_read_id}`.

`get_topics` and `GET /v1/brands/{brand_id}/topics` return the topics of the latest weekly report's content check in the period, with the same statuses as [Content](/concepts/content#topics). Search clicks and visits from AI cover 28 days of the properties connected now. One topic adds its page's checks, its top search query, its questions, prompts and the pages they cite most.

`citation_evidence` is `complete`, `partial` or `unavailable`, and `unavailable_scans` counts the period's reports that lost citations before they were frozen; counts derived from citations are floors unless it is `complete`.

Topic lists add `sentence`, `cards`, status labels and connection availability. Use `status`, `q`, `sort` and `direction` to select rows, and `with_menus=true` for the shared filters. The cards keep the population selected by the figure filters. One topic adds its Answers link, prompt scores and trends, source labels, and current content work.

A citation count is `null`, never zero, when a weekly report it covers could not keep all its citations, because answers aged out before Heralded stored them. A count over other reports is unaffected.

`get_audit` and `GET /v1/brands/{brand_id}/audit` return the latest crawl. `readiness` counts the pages the checks cover, the same counts as Home and the Snapshot report. Website has no period: page `citations` count the last weekly report, `citations_scan`, and `crawler_hits` uses the same frozen 28-day window as [Pages](#pages-topics-and-audit). A page's `read_at` is the date that crawl read the page, and is null for a page the crawl could not read and for some audits before 2026-10-04.

Website adds its summary sentence, page-type menu, check action ids and page status words. `status`, `cited`, `page_type`, `q`, `sort` and `direction` select its page rows without changing the headline. Each check returns up to `checks_limit` failing pages. Pass `check` with `checks_offset` to read another page of that check's failures.

These reads and their existing MCP tools accept `as_of`. Pass the first response's `meta.data_as_of.id` on subsequent requests to keep the page on the same completed scan.

## Scans

`GET /v1/brands/{brand_id}/scans` lists a brand's weekly reports, daily updates and the Snapshot it started from, newest first. Each row has `kind`, one of `weekly`, `daily` or `snapshot`, `state`, one of `preparing`, `running`, `completed` or `failed`, `domain`, `started_at`, `completed_at` and `heralded_score`, the score the scan issued. A daily update issues no score, and a partial Snapshot shows none until it is final. While a scan is preparing or running, `progress_pct` says how far it has come. A completed weekly report or Snapshot has a `share_id`. A scan that failed has a `failure_reason`, and every other scan has `null`:

* `stuck_no_progress`: the scan stopped making progress.
* `brief_abandoned`: the brief was not confirmed in time.
* `insufficient_engine_signal`: the engines did not return enough usable answers to score it.
* `cost_cap_exceeded`: the scan reached its safety cost cap.
* `report_inputs_missing`: the scan finished without the data its report needs.
* `other`: any other reason.

New values may be added, so treat one you do not know as `other`.

`GET /v1/scans` lists the Snapshots you ran, with the same rows, paging and cursor. It covers the one-time scans no brand's list shows, and a Snapshot that became a brand's first scan stays on it. A Snapshot whose report is no longer served is left out. It lists only your own, with an API key or signed in.

`GET /v1/scans/{scan_id}` and `get_scan` read one scan. While it runs, `progress` gives its step and how many answers are in. Once it completes, `issued` gives the Heralded Score, Mentioned and Recommended with the brand's place among the competitors that scan measured, and readiness over the pages it checked. These are the numbers its report shows. Anyone who can read the brand can read its scans. A Snapshot no brand holds is read only by the account that ran it.

`GET /v1/scans/{scan_id}/audit` and `get_audit` with `scan_id` read the Content read of a Snapshot or Audit you ran: the page the app opens at `/r/{share_id}/audit`. `pages` lists every audited page, best fix first, each with its `priority`, `value`, `score`, the checks it fails or could not measure, and the buyer questions it answers. `pillars` counts how many pages pass each page check. `readiness`, `site_blockers` and `site_checks` give the same counts as Website's `readiness` and the site's checks, with the fix for each blocker. `missing_topics` names the topics the site has no page for: a Snapshot names its top five and `missing_topics_total` counts them all. `content_pass` says whether the read is still `running`, `failed` or `done`, and the fields after it fill in once it is done. Only the account that ran the scan reads it, with an API key or signed in. Anyone else, a reader of the brand a Snapshot became included, gets `not_found`, and so does a request with no API key. The scan is named by its `id` or by its `share_id`.

A delivered weekly report or Snapshot has a `share_id`. `GET /v1/shared/scans/{share_id}` returns its report as anyone with its link sees it, with no API key. It never includes your workspace's analytics, search queries, crawled pages, content strategy or anything about who is reading.

`source_tier_rollups[].citation_share_pct` gives each tier's share of all citations. `brand_citation_summary` gives the same population's ownership shares in `owned_share_pct`, `competitor_share_pct` and `independent_share_pct`. Independent means every tier outside owned and competitor, including unclassified citations. Each percentage rounds half up independently, so the shares can total 99 or 101. An empty citation population has `null` shares. Each row of `scan.race.rows` also has `gap_pts`, its Heralded Score minus the subject's score, or `null` if either score is unmeasured.

A report retired with Heralded's pre-launch data answers `410` with `code` `report_retired`, its `domain` and a `rescan_url`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.