> ## 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.

# Leaderboards

> How published monthly visibility measurements are filtered and compared.

Leaderboards use published monthly measurements. You can narrow them by industry, the country questions were asked from, engine and month. Brand filters select a brand's home country and audience.

A leaderboard uses exactly one country asked from. Global is the default. Brand origin is a separate filter: the country a brand was founded in, even if it later moved or was acquired. Romanian brands can appear in a Global measurement or one asked from Romania.

## Questions, markets and engines

Each panel measures one industry asked from one market. Global questions use English without a country. Providers that require a country receive the United States.

Romania panels ask two thirds of their questions in Romanian and one third in English. Every question is asked from Romania, in its own language. The pages stay in English.

Leaderboards measure four engines: ChatGPT, Gemini, Google AI Overviews and Google AI Mode. Each question is asked twice on each engine. The Command Center measures six engines, so a leaderboard and a tracked brand can cover different answers even though they use the same scoring rule.

## Scores and places

A brand's [Heralded Score](/methodology/heralded-score) uses the questions from industries it belongs to, under the selected filters. A brand needs at least three answers naming it to receive a score and a place. Fewer naming answers leave it unranked.

Each answer contributes 0 when the brand is absent, 50 when named and 100 when recommended. The score applies the product's current calibration when you read it. Recalibration can change a published score; it preserves the ordering of scores.

Within one industry, places reflect the filtered list. Each brand also carries its place among all measured brands in that industry. Selecting Romanian CRM brands, for example, gives their places within that list alongside their overall CRM places.

Across several industries, the result is a list. Naming rates from different question sets cannot establish an overall ranking. Each brand carries its places in its own industries. The list orders by the best such place, then by score. It has no overall rank, leader or engine top three.

## Monthly change and history

Change compares matched question and engine cells with the previous comparable month, using the [paired change method](/methodology/change).

The first comparable measurement is a first reading. Change is calibrating until three comparable months precede it. After that, the comparison can show a move up, a move down or no clear move. The Command Center keeps its own weekly baseline requirement.

History follows the comparable series. A change in the measurement's engines, market, scoring version, answer interpretation version or number of passes starts a new series. Brand identity connects the history even when a brand's name changes.

Joining another industry preserves a brand's earlier history. Each month uses the memberships measured at that time. Changes to questions and memberships leave new or removed question cells unpaired. Filtering by engine keeps instrument breaks, including a month that did not ask that engine.

## Sources and questions

Sources group the cited pages by site and type, and count both the citations and the answers that cite the site. A brand's own site reads as a brand site. Pages carry the brands they mention and recommend only where page readings establish those facts. An unread page or an undecided fact is unavailable.

Within one industry, each engine has its own top three measured brands. Questions carry their winners and their language. Every brand tied for the most recommendations wins that question. A question recommending nobody has no winner.

Each brand row also carries its Mentioned and Recommended for every engine, which is unavailable for an engine that did not read the brand.

Brands, sources, each source's pages, engines, questions and history have separate pages. Each collection carries its total, limit and offset. An empty answer population is unavailable rather than zero.

## What the public leaderboards show

Sources, cited pages, a brand's sources, its questions and quotes use a stable monthly sample. Heralded withholds an entity when the SHA-256 hash of its kind, identity and measurement month falls in the bottom 70% of the hash range. Sources use their registrable domain, pages their URL, questions their prompt ID, and quotes their answer ID paired with the brand ID. Nothing random is stored.

The same entity has the same sample decision across leaderboards, filters, brand pages and source pages in that month. Reloading does not change it. The measurement month rotates the sample. Position 1 of each module is always sent because featured cards name it, even when the sample would withhold it. Positions beyond 20 are never sent.

Each restricted module carries `withheld`, every withheld position within the first 20 rows of its full ordered list. Withheld row data never reaches your browser or assistant. Its `total` still counts every row, and source summary lists include only sources sent in that response. A source detail read is unavailable when the source is outside every leaderboard's public sample and first-20 preview.

Paging uses positions before withholding. An offset of 20 or more returns no rows while keeping the same `total` and `withheld`. A page can contain fewer rows than its `limit`.

Brand rankings, each engine's top three, engine lists, leaderboard questions, placements, competitors, history and a source's brands keep ordinary paging without withholding or the position-20 cutoff. The API and MCP follow the same rules. Run a [Snapshot](https://heralded.ai/snapshot/) to measure your brand's visibility and sources in a full report.

## Page filters and links

Each filter combination has a path with industry, country asked from, brand origin, audience and engine in that order. Empty filters disappear. For example, `/leaderboards/crm/romania/chatgpt/` selects CRM tools measured from Romania on ChatGPT. Brand and source pages use separate paths under `/leaderboards/brands/` and `/leaderboards/sources/`.

Titles use the filter names and measurement month. An industry that implies the selected audience omits that audience from its title. Global adds no country wording. A list spanning industries says "brands by AI visibility in their industry". Descriptions name the first three measured brands in the displayed order.

Facet combinations include `featured_position`, Heralded's curated display order. It is `null` for combinations that are not featured. Only combinations with measured brands in the selected month appear, so a featured path without data stays out of the list.

A combination is indexed when it has at least five measured brands and narrows its parent's brands or measurement scope. Its parent removes the last selected filter in the path. A combination below the threshold, or one that leaves its parent's population unchanged, points to the nearest indexed ancestor. The unfiltered Global page is the fallback. Related links show the same industry in other markets, other industries in the same market and brand-origin views.

## Brand and source pages

A brand page shows its best three measured placements and a paged placement module, including unranked measurements. The `engine_ranks` module gives each engine's average place across the leaderboards where it ranks the brand, the number of those leaderboards and its best place. Unranked leaderboards do not enter the average. An engine with no ranked placement has no average or best place.

**Questions it answers**, the `questions` module, lists questions the brand wins first, then questions where it places, then questions naming competitors while leaving the brand out. Each row carries the question's language, its leaderboard title and path, the brand's place in the question's standing and up to five competitors, most named first. An absent brand has a `null` place. Standing follows the product's order by recommendations, then mentions.

Highlighted descriptions, the `highlights` module, select up to four complete sentences from frozen answers, one per engine. They prefer answers recommending the brand, then the most recent reading. Sentences have 60 to 280 characters; table rows, list lines and near-duplicates are left out. Each quote carries its engine, question and leaderboard. Fewer suitable quotes leave fewer descriptions. The `evidence` module returns the same selected quotes in its existing row shape, with filters, prompt ID, engine ID and quote text.

The `history_series` module returns one series per placement, with its leaderboard title and path, change state and monthly score, Mentioned and Recommended values. Points follow comparable months only, oldest first. A first reading and a calibrating series keep the [monthly change states](#monthly-change-and-history).

Existing clients can keep reading `won` and `missed` for question winners, `competitors` for the nearest ranked brands, `engines` for a brand row per leaderboard and engine, and `history` for individual monthly figure points. These modules keep their row shapes and paging parameters. The new modules have independent paging offsets.

A brand's sources, questions and highlighted descriptions follow the [public withholding rule](#what-the-public-leaderboards-show). Highlights refer only to questions the public read can disclose. Quote selection happens before withholding.

A source page groups citations by the site's registrable domain. It shows the source's place in each leaderboard, brands its pages mention and recommend, its most cited pages and the engines citing them. When a page reading is unavailable, the brand mentions and recommendations remain unavailable.

## Read through the API or an assistant

The leaderboard HTTP reads need no login or API key. Only published measurements appear.

| Read | Route |
| - | - |
| Filtered modules | `GET /v1/leaderboards` |
| Filter combinations, titles and paths | `GET /v1/leaderboards/facets` |
| Brand page | `GET /v1/leaderboards/brands/{slug}` |
| Source page | `GET /v1/leaderboards/sources/{domain}` |

Use `industry`, `country`, `engine`, `month`, `origin_country`, `audience` and `source_type` on the filtered read. Country values are uppercase two-letter codes, engine values come from the facets read, and month uses `YYYY-MM`. Omit `country` for Global. The facets and detail reads accept `month` too.

```bash theme={null}
curl 'https://api.heralded.ai/v1/leaderboards?industry=crm&country=RO&limit=10&brands_offset=10'
```

`limit` defaults to 10 and accepts 1 to 100. Every module has a separate offset, such as `brands_offset`, `sources_offset`, `source_pages_offset`, `engines_offset`, `prompts_offset` or `history_offset`. Brand and source detail collections use their names too, such as `placements_offset`, `questions_offset`, `engine_ranks_offset`, `highlights_offset` or `history_series_offset`. On a brand read, `history_offset` pages individual points and `history_series_offset` pages placement series; each series contains every comparable monthly point. Each collection returns `offset`, `limit` and `total`; advance its offset by its `limit` to read another page. Restricted modules also return `withheld` and stop at position 20. `next_cursor` is null on these collections.

Responses carry `meta.query` and `meta.data_as_of`, the newest included measurement. They cache for one hour and allow a stale copy for a day while revalidating. Send the `ETag` back in `If-None-Match` to receive `304` when the response is unchanged. Published responses can change after recalibration, brand corrections or page readings.

Anonymous requests share a bucket per client IP, with a default of 60 requests per minute across these routes. The site's server sends `X-Heralded-Site-Key` for a separate bucket, default 600 per minute. The site key changes only the bucket; it grants no access to unpublished measurements. An unknown key uses the anonymous bucket. `RateLimit` and `RateLimit-Policy` describe the bucket, and a `429` [problem](/errors-and-limits) includes its state and `Retry-After`.

The token-authenticated [MCP server](/connect-mcp) offers `get_leaderboards` over the same reads. Its normal credential limit applies. Use `resource` to select `leaderboard`, `facets`, `brand` or `source`, and pass `slug` for a brand or `domain` for a source. Filters go in `filters`; collections take their own limit and offset in `pages` or `detail_pages`.

```json theme={null}
{ "filters": { "industry": "crm", "country": "RO" }, "pages": { "brands": { "limit": 10, "offset": 10 } } }
```

```json theme={null}
{ "resource": "brand", "slug": "atlas" }
```


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