# Concepts Source: https://docs.recomma.ai/concepts Recomma uses a small vocabulary and uses it precisely. Most of these words appear in the app beside a `?` that gives the same definition — this page is the whole set in one place. ## The things being measured ### Project One brand's tracking setup: its domain, its market and language, the prompts asked for it, the models they are asked on, and the rivals it is measured against. The switcher at the top of the rail moves between them, and every figure you see is scoped to the one that is open. A project is not a brand. It is *about* a brand — and it also holds the competitors, which are brands too, which is why the two words cannot be the same one. Your plan caps how many projects you run and pools the prompt budget across all of them. ### Brand A company that can be named in a chat. The one a [project](#project) is about is the **tracked brand**; the rest are [competitors](#competitor). A brand is matched by name and by its aliases, so "Ahrefs", "ahrefs.com" and "Ahrefs Site Explorer" all count as one. The **Competitors** panel in the project's Settings is where the set is kept — your rivals and your own row among them — because that set is the denominator of two of the four metrics. ### Competitor A rival brand you have chosen to measure yourself against. [Share of voice](/metrics/share-of-voice) and [position](/metrics/position) are both computed across the tracked set, so the list you keep decides what those two numbers mean. A rival you have not added does not dilute your share. ### Prompt One question, tracked over time. It runs on every enabled model every cycle, and each run produces one [chat](#chat). A prompt carries a [topic](#topic) and a [funnel stage](#funnel-stage). ### Topic The subject a prompt belongs to, so a group of questions can be read together. A prompt carries exactly one topic, and the rail on the Prompts page lists whatever topics the prompts carry — there is no separate list of topics to maintain, and a topic with no prompts under it does not exist. ### Funnel stage Where the question sits in a buying decision — **awareness** asks what exists, **consideration** compares options, **decision** is ready to choose. Assigned when the question is written. ### Chat One model's reply to one prompt on one day, stored whole: the text, the brands it named in the order it named them, and every source it cited. Every figure in the product is counted from these, and every figure can be opened to read them. ### Mentions The brands a model named in its chat, in the order it named them. A mention is the brand appearing in the text — **not** a link to it. A brand can be mentioned without being cited and cited without being mentioned. ## What a reading rests on ### Sample size The chats a figure was measured over — prompts × models × sampling days in the window. Below twenty, a percentage moves too much on one answer to be reported as a reading, and Recomma greys it out. ### Confidence interval The range the true figure is likely to sit in, given how many chats it was measured over. A reading of 50% from ten chats and one from a thousand are not the same claim, and this is the difference. ### Fidelity How the chat was obtained: from the model's own interface, the way a person sees it, or from the model's API. Interface chats are the truer measurement; API chats are a fallback and are marked as such. A model's product and the model behind it are not the same thing. ChatGPT the product searches the web, applies its own ranking, and formats sources; the API call behind it may do none of that. A figure mixing the two without saying so would be comparing two different questions. ## The market behind the prompts ### Keyword pool The set of keywords a category is actually contested on: everything the tracked brand or one of its [competitors](#competitor) ranks in the top twenty for, minus brand terms, kept only where **two or more** of those domains rank and the intent is commercial or transactional. Rebuilt monthly and kept as a numbered version, so last month's figure can still be reproduced. The whole recipe, and what it deliberately throws away, is on [Market value](/metrics/market#the-pool). A pool is small — a few dozen keywords is normal. It is the commercial head of a category, not a keyword export. ### Intent What somebody typing a keyword wants. The pool holds two kinds: **commercial** compares options, **transactional** is ready to buy. Informational keywords are left out, because they are answered by a paragraph naming nobody, which measures nothing. This is the keyword's intent, from the search data. It is a different axis from a prompt's [funnel stage](#funnel-stage), which is a property of a question you chose to write. ### Rivals How many of the tracked domains — yours and your competitors' — rank in the top twenty for a keyword. Two is the floor for entering the pool at all: a keyword only one site ranks for is that site's content marketing rather than the category's. ### Keyword difficulty How hard the top ten is to enter for a keyword, 0 to 100, from the strength of whoever already holds it. Banded by colour, because nobody acts differently on 43 and 46: under 30 is a page, over 60 is a project. It weights no ranking in the product — value alone orders the pool. ### Category value What the market pays, per month, to own the intents in the pool: each keyword's monthly searches times the share of clicks a top result takes times what advertisers bid on it. A valuation of the intent, not a forecast of revenue — [being named in an answer is not a click](/metrics/market#how-a-keyword-is-priced). ### Prompt coverage The share of category value that any tracked [topic](#topic) reaches. The remainder is **uncovered**: real demand that no question measures, so the brand is scored on it in neither direction. It is the figure on [Keywords](/product/keywords#uncovered-demand) with a button attached. ### Captured The share of covered value the engines actually name the brand in — each topic's visibility weighted by what that topic is worth, rather than each question counted once. A brand doing well on cheap questions and badly on the expensive one reads as doing badly here, which is the point. ## Sources ### Source A page a model reached for while answering. Recomma records both the pages a chat **cited** and, where the model reports them, the ones it **read and did not cite**. ### Citations Every appearance of a source across the chats, counted in full. One chat citing three pages of the same site counts three — which is why this is larger than the chats that used it. ### Cited in Chats that linked to a source in what they said. A chat citing it five times still counts once. ### Used The share of chats that cited a source at least once. The denominator is every chat in the window, not only the ones it appeared in. ### Per chat Citations divided by the chats that used it — how heavily a chat leans on a source once it reaches for it. Two means a typical chat quotes it twice. ### Overlooked Chats where the model read a source but did not cite it. Read-and-passed-over is not the same as never found, and the difference is what tells you whether the page or its ranking is the problem. ### With you Of the chats that cited a source, the share that also named you. A high number means the source is friendly ground; a low one means it is being trusted while you are absent from it. ### Retrieved, and cited A model can open a page and quote nothing from it, and the two are recorded separately. | Figure | What it counts | | --- | --- | | **Retrievals** | Every time a model reached for a source, cited or not. One chat opening three of its pages counts three | | **Retrieved** | Share of *all* chats in the window that reached for it at least once | | **Retrieval rate** | Retrievals ÷ chats that retrieved it — how many of a source's pages a typical chat opens | | **Citation rate** | Citations ÷ chats that *retrieved* it — how often a chat that opened a source goes on to quote it | The gap between retrieved and cited is itself a reading. A source opened in a third of chats and quoted in a twentieth is being picked up and put down, which is a content problem; one that is never opened is a discovery problem. The two need opposite fixes. ### Index, held, returned A second layer, and a word of warning about the first. *Retrieved* above is about a chat: a page the model opened while writing an answer. An assistant that can search does something before that — it calls a **search index** and is handed a ranked list of URLs. [Agent search](/product/agent-search) measures that layer, and uses its own words on purpose: - **Index** — the search service an agent's tool calls, such as Brave or Exa. Independent of each other, and independent of the assistants. - **Held** — the index has the site's pages at all. Measured as a floor, because no vendor publishes a count. - **Returned** — the index handed the site back for one of the tracked questions, and where in the list. Held but never returned is a content problem; not held at all is a crawling one. It is the same shape as the retrieved-against-cited gap above, one layer down, which is why the page is not called Retrieval — that word is already spoken for. ### Source type What kind of site the model leaned on: | Type | What it is | | --- | --- | | **Owned** | Your own domain | | **Competitor** | A tracked competitor's own site | | **Editorial** | Press and publications | | **Corporate** | Other companies' sites | | **Reference** | Documentation, encyclopaedias, directories and review sites | | **Institutional** | Universities, governments, standards bodies and public research | | **UGC** | Forums and communities | | **Unclassified** | Nobody has placed it yet — a statement about us, not about the site | The type is not decoration: it decides how much a citation is worth when [opportunities](/product/opportunities) are scored. Editorial coverage is weighted well above a corporate page, because it is harder to get and the models lean on it more. **Institutional** was split out of reference, because the two need opposite advice. A review directory is a listing you go and claim; a `.edu` paper or a standards document citing your subject is ground nobody buys their way onto, and being absent from it is a research problem rather than a marketing one. It is decided by public suffix — `.gov`, `.edu`, `.ac.uk` and the named archives — so no classification pass is ever spent on it. **Unclassified** is the one that is not a finding. It means nothing has placed the domain yet, which is a statement about us and not about the site — so it carries the lowest weight of any type, and moves to its real one as soon as the classifier gets to it. It is kept distinct from **Corporate** deliberately: "we have not looked at this" and "this is a company's marketing page" are different facts, and a category holding both would be unreadable. ### Gap A domain the chats cited without ever naming you in the same chat. It is being trusted on your subject while you are absent from it, which is the cheapest place to go and be present. Gap strength is your overall visibility minus that source's coverage of you — so a source that already mentions you as often as the web at large is not a gap, however often it is cited. ### Crawlability What a site's `robots.txt` says about AI crawlers — whether GPTBot, ClaudeBot and the rest are allowed to read it. Blocking them is a choice a site makes about being quotable. ## The four brand metrics Each has its own page; in one line each: | Metric | What it asks | | --- | --- | | [Visibility](/metrics/visibility) | How often are we named at all? | | [Share of voice](/metrics/share-of-voice) | How much of the conversation is ours? | | [Sentiment](/metrics/sentiment) | How favourably are we spoken about? | | [Position](/metrics/position) | How early in the chat are we named? | A fifth page, [Market value](/metrics/market), covers the figures that say what the chats those four are counted from are worth. --- # Welcome to Recomma Source: https://docs.recomma.ai/ Buyers used to arrive from a list of ten blue links. Increasingly they arrive from a chat — one paragraph, three brands named, a handful of sources cited. There is no rank to check and no impression count to read. Either the chat named you or it did not. Recomma measures that. It asks the questions your buyers ask, on the models they ask them on, on a schedule, and keeps every chat. From those chats it reports how often you were named, how much of the conversation was yours, how the chat spoke about you, and which pages on the open web the models leaned on to decide. Not a rank tracker with an AI tab. Nothing here is derived from search positions. Every figure on every screen is counted from chats that were actually generated, and you can open any of them and read the text it was counted from. ## How it works ### You describe the brand A domain and a market. Recomma reads the site, works out what you sell and who you sell against, and proposes the first set of questions and competitors. You approve them — nothing is tracked until you do. ### Recomma asks the questions Every tracked prompt runs on every model you have enabled, on your project's cadence. Each run produces one chat, stored whole: its text, the brands it named in the order it named them, and every source it cited. ### The chats become readings [Visibility](/metrics/visibility), [share of voice](/metrics/share-of-voice), [sentiment](/metrics/sentiment) and [position](/metrics/position) are all counted from those stored chats, per day, per model, per market. ### And what the indexes underneath do with you An assistant that can search does not read the web — it calls a search index and writes from the ranked list it gets back. Those indexes are independent of each other and of the assistants, and they disagree, so [Agent search](/product/agent-search) asks the same tracked questions of them directly: whether they hold your pages at all, and whether they hand them back. ### And how much of the market that is The questions come from somewhere: a category people search, bid on and buy in. Recomma prices that market from what you and your rivals rank for, and reports how much of it your questions reach and how much of it the answers name you in — so a visibility figure has a denominator. See [Market value](/metrics/market). ### You work the gaps, and your own pages [Sources](/product/sources) shows which sites the models trust on your subject; [Opportunities](/product/opportunities) ranks the ones that are trusted *and* silent about you. [Site](/product/site) holds your own pages to a fixed set of rules, which needs no gap and has an answer on day one. Then [Impact](/product/impact) reads the figure back after you have acted. ## Where to start --- # Metrics overview Source: https://docs.recomma.ai/metrics Every metric in Recomma is counted from stored [chats](/concepts#chat). None of them is modelled, estimated, or derived from search rank. If a figure says 73%, you can open the chats it was counted from and read them. ## The four ## And what they are a share of The four say how a chat treated you. None of them says whether the chat was worth being in — a brand can win a corner of its category worth very little and read as a success on all four. ## They answer different questions It is tempting to read them as four versions of the same number. They are not, and the interesting cases are where they disagree: | Pattern | What it usually means | | --- | --- | | High visibility, low share of voice | You are named in most chats, but always alongside many others. Presence without preference. | | High visibility, weak position | You are the afterthought — named late, after the recommendations. | | High visibility, low sentiment | You are known for something you would rather not be. Read the chats. | | Low visibility, high sentiment | The few chats naming you like you. A distribution problem, not a positioning one. | ## When a figure is a reading A percentage measured over a handful of chats is not a measurement. Recomma is explicit about this rather than hiding it: - **[Sample size](/concepts#sample-size)** — prompts × models × sampling days in the window. This is the number that makes a percentage mean something. - **[Confidence interval](/concepts#confidence-interval)** — the range the true figure is likely to sit in. `±3pt` on 73% means the honest claim is "between 70% and 76%". - **Below twenty chats**, Recomma greys the figure out. It is not that the number is wrong; it is that one chat moves it several points, so a change between two readings tells you nothing. - **And the interval has to be narrower than the reading.** Counting chats does not catch a rare event: one chat in twenty-eight clears any floor and still prints 4%, where the interval runs 0.6% to 17.7%. A figure that cannot be told apart from zero is dimmed too, however many chats are behind it. - **A reading of 0% is judged the other way round.** Its interval cannot be narrower than itself, so what makes it readable is how tight the *upper* bound is: zero out of twenty-eight runs to 12%, which is not "you are absent" but "we have not asked enough to tell". A 0% is shown plainly once that bound is within ten points, and dimmed until then. Before calling a movement real, check that it is larger than the intervals on both sides. A jump from 61% to 66% with `±5pt` on each is not a jump. ## Scope Every figure obeys the filter bar at the top of the Overview, and every filter changes the denominator: - **Period** — the window the chats are drawn from. - **Model** — one model, or all of them. Models disagree substantially; an all-models figure is an average over that disagreement. - **Locations** — one market's answers, or all of them. The same question asked from two countries is two answers, not one asked twice. - **Topic** — one [topic](/concepts#topic)'s prompts, or all of them. This is the filter that turns "how visible are we?" into the more useful "how visible are we *on the questions we care about winning*?" --- # Market value Source: https://docs.recomma.ai/metrics/market The four brand metrics say how a chat treated you. None of them says whether the chat was worth being in. **Market value is the denominator**: what the intents behind your prompt set are worth per month, how much of that a tracked question reaches at all, and how much of *that* the models name you in. ``` category value what the market pays, per month, to own these intents prompt coverage the share of it any tracked topic reaches captured the share of what is covered that the answers name you in ``` Three figures, deliberately not one. A brand can be highly visible on a corner of its category worth very little, and the four brand metrics will report that as success. ## The pool Every figure here is arithmetic over one table: the **pool**, the set of keywords the category is actually contested on. It is rebuilt monthly, kept as a numbered version, and you can read every row of it on [Keywords](/product/keywords). It is built from what you and your tracked [competitors](/concepts#competitor) already rank for, in seven steps: | # | The cut | Why | | --- | --- | --- | | 1 | Every keyword you or a rival ranks in the **top 20** for | Below that, a ranking is not evidence of anything | | 2 | Brand terms removed — your names, aliases and domains, and theirs | "acme pricing" is your own traffic, not the category's | | 3 | Only keywords **at least two** of those domains rank for | One site ranking alone is that site's content marketing | | 4 | Only **commercial** and **transactional** [intent](/concepts#intent) | An informational keyword answers with a paragraph naming nobody | | 5 | Near-identical variants collapsed into one row | The vendor lists "usage based billing" and its plural separately | | 6 | Each keyword priced (below) | — | | 7 | Cut at 95% of the total value | The long tail adds rows and no money | Steps 1 and 3 are the ones doing the work. Take a large rival's thousand biggest keywords by volume and you get that rival's blog: for a billing product, the top of the list comes back "purchase orders", "llc registration", "business credit cards". Requiring a top-20 ranking from two different domains is what makes the same query answer *about the category*. ### The half a contest cannot find Steps 1 and 3 can only see demand somebody already ranks for. A phrase nobody tracked ranks in the top 20 for produces no evidence of a contest — and people are still searching it about a topic you track, so the money is real and the recipe above is blind to it. Those phrases are added per topic, most searched first, and held to the same cuts as everything else: priced, commercial or transactional intent, variants collapsed, and not already in the pool under another spelling. They carry no rival count, and [Keywords](/product/keywords) shows `searched` in that column rather than a zero. They are ordinary pool rows in every other respect — priced the same way, counted in the same totals, placed onto topics by the same pass. ## How a keyword is priced ``` value = monthly searches × 0.3 × cost per click ``` - **Monthly searches** — Google's volume for the keyword in the project's country. Not how often it is asked of an assistant, which is a different quantity nobody publishes. - **0.3** — roughly the share of clicks the top organic result takes. Without it the figure answers "what would it cost to buy every click for this keyword", which is an advertising budget and not the value of owning the intent — a difference of two orders of magnitude on a mid-sized category. - **Cost per click** — what advertisers bid, from Google Ads. A bid is the market's own price on an *intent*, not the price of Google traffic. An advertiser paying $18 for "best billing software" is telling you what that buyer is worth to them, and that is true whichever interface eventually answers the question. What a bid is not is your revenue: **being named in an answer is not a click.** That is also why **the money and the percentages are never multiplied together**. The product says what share of a priced market the answers name you in; it never prints a dollar figure for what you captured, because that number would be a claim about clicks nobody counted. ## Prompt coverage ``` prompt coverage = value of keywords a tracked topic reaches ÷ value of the whole pool ``` Once the pool is priced, a model places each keyword onto one of your [topics](/concepts#topic), or onto none. Coverage is the share of the money that landed on a topic you actually ask questions about. The rest is [uncovered](/product/keywords#uncovered-demand): real demand in your category that no question measures, so you are scored on it in neither direction. **The denominator is the whole pool, including the uncovered part.** Adding prompts raises coverage; it never quietly enlarges the market to match what you happen to track. That is what makes one month's figure comparable with the next, which is the only reason to have the figure. ## Captured ``` captured = Σ (topic value × that topic's visibility) ÷ Σ (value of the measured topics) ``` [Visibility](/metrics/visibility) with each topic weighted by what it is worth, rather than every question counted once. A brand winning the cheap questions and losing the expensive one reads as doing badly here — which is the entire point of the figure. Two things are held out of it deliberately: - **A priced topic nobody has sampled yet** is in neither the numerator nor the denominator. Folding it in as 0% would report a measurement that was never taken. - **A reading carried by thin topics is not reported.** More than half the value in the average has to come from topics that individually clear the sample floor. Summing sample sizes across topics hid exactly this: 51 answers spread over four topics, none of them readable on its own, presented as a reading. A weighted average is only as sound as the weights carrying it. ## When a figure is missing Three different absences, and none of them is a zero: | You see | It means | | --- | --- | | No Market panel at all | No pool has been built for this project yet | | Coverage as `—` | The pool is priced but not yet placed onto topics | | Captured absent, with a note | No answers against a priced topic yet, or too few to read | A pool that has been priced but not placed has every keyword sitting in the uncovered bucket, so the arithmetic would return 0% coverage — a sentence telling a brand it reaches none of its market, produced by a job that has not finished. The product says which of the three it is instead. ## What this is not **It is not total category demand.** The pool is defined by what you and your rivals rank for, so it measures *the market somebody is contesting*. Rivals with weak SEO make for a smaller pool. That is the right frame for a competitive gap and the wrong one for a market-sizing slide. **It is not everything you track.** Plenty of good prompts have no priced demand behind them — a subject buyers ask assistants about and nobody bids on. Those topics are still measured by the four brand metrics; they simply carry no money, and the product says "not priced" rather than "worth nothing". **It is not deeper than one page per domain.** Sampling three times as many keywords per rival was tested: the contested set grew in exact proportion, the number of topics with a price behind them barely moved, and on one project coverage *fell* — a deeper sample mostly adds the rivals' wider tail, which is further from the subjects you track. What the contested cut removes is real. ## Related --- # Position Source: https://docs.recomma.ai/metrics/position **Position is where you are named among the tracked brands in a chat, averaged over the chats that name you.** First is `#1`. Tracked is the operative word. The order comes from where each tracked brand is first named in the answer, so a company nobody added does not push you down — like [share of voice](/metrics/share-of-voice), this figure is read against the field you defined on [Competitors](/product/brands). Being named late in a list is weaker than being named first, and this is the only figure in Recomma that says so. ## Why it exists [Visibility](/metrics/visibility) is binary per chat: you were named or you were not. But these two chats are not the same result, and visibility scores them identically: > For a small agency, **Linear** is the strongest option. **Asana** and > **Monday** are also worth considering, and **Basecamp** if you prefer > something simpler. > There are many options here — **Asana**, **Monday**, **Basecamp** and > **Linear** all have their advocates. In the first, one brand is the recommendation and the rest are alternatives. In the second, four brands are a list. Position separates them. ## How to read it **It is an average, and averages hide shape.** `#1.7` does not mean you are usually second. It can mean "first in most chats, fourth in a few", which is a different situation from "second in nearly all of them". The distribution is on the [Prompts](/product/prompts) table, per question. **Lower is better, and the scale is short.** The difference between `#1.4` and `#2.8` is large — roughly the difference between "usually the recommendation" and "usually an alternative". **It only counts chats that named you.** A brand named in 5% of chats can have an excellent position. Read it next to visibility or it will flatter you: ## What moves it Position responds to how the sources talk about you rather than whether they mention you. A brand that appears in every comparison table but is never the recommendation will have good visibility and a poor position — and the fix is in what those comparison pages *say*, not in getting more of them. ## Related --- # Sentiment Source: https://docs.recomma.ai/metrics/sentiment **Sentiment is how favourably a chat speaks about the brand, scored 0–100.** | Score | Reads as | | --- | --- | | 0 | Hostile | | 50 | A neutral mention — named, not praised or criticised | | 100 | A strong endorsement | The figure shown is the average over the chats that **named** the brand. Chats that did not name it are not in the denominator: a chat that ignored you is a [visibility](/metrics/visibility) problem, not a sentiment of zero. ## Who scores it A separate, cheaper model reads the answer and rates every brand it named, against the three anchors above. One call per answer covers the whole field at once — so the brands in one chat are scored by one reader with one piece of context, which is what makes them comparable with each other. It is the only figure in Recomma that is a judgement rather than a count. Visibility, share of voice and position are arithmetic over text that either does or does not contain a name; sentiment is an opinion about tone, produced by a model, and worth reading with that in mind. ## An unscored chat shows a dash Not a 50. This distinction is deliberate and worth understanding, because the two look the same on a chart and mean opposite things: - **50** is a real reading — the chat named you neutrally. - **—** means the chat has not been scored. Averaging an unscored chat in as 50 would drag every real score toward the middle and make a well-liked brand look ordinary. ## How to read it **Read the chats, not just the number.** Sentiment is the metric where the aggregate is least useful on its own. A 71 average can be a hundred bland mentions or fifty warm ones and fifty hostile ones, and the second is an emergency. Sentiment is available per prompt on the [Prompts](/product/prompts) table, which is where you find the questions dragging it down. **Compare against the field, not against 100.** Models are not effusive. A category where the leader averages 76 is not a category where 76 is a bad score. The [Rankings](/product/overview#rankings) table puts your score next to everyone else's for exactly this reason. Rarely from a model disliking you. Usually from a chat repeating a criticism it read somewhere — a comparison page, a forum thread, a review with a caveat in it. [Sources](/product/sources) is where you find which page it was reading. ## Related --- # Share of voice Source: https://docs.recomma.ai/metrics/share-of-voice **Share of voice is your share of the chats that named anybody tracked.** [Visibility](/metrics/visibility) asks how often you appear. This asks how much of the conversation is yours when everyone named is counted. ``` share of voice = chats naming you ÷ Σ (chats naming each tracked brand) ``` **Repetition does not help.** The numerator is the same count visibility uses — chats naming you at least once — so a chat that names you three times contributes one, exactly as it does there. A chat naming you and two rivals adds one to each of the three, and three to the denominator. That is the part the name does not tell you. "Share of voice" sounds like loudness and is counted as presence: being mentioned more often *inside* an answer is not measured by this figure, and cannot be gamed into it. ## Why it is the harder number Visibility can be high while share of voice is low, and that combination is common enough to be worth naming: you are in the chat, but so are eleven other people. You have presence without preference. In the table above the top two are close on both columns: each is named in most chats and each takes a comparable share of the mentions. A brand named in 70% of chats that took 8% of mentions would be a different situation entirely — always present, never the point. ## It depends on your competitor list This is the metric most sensitive to setup. The denominator counts only **tracked** brands — a name the model said that nobody added is in no side of the fraction — so: - A rival you have not added does not dilute your share. - Adding a large, frequently-named competitor will lower your share of voice without anything changing in the world. Like the prompt set for visibility, the competitor set is the baseline here. Add a competitor and expect a step in the line. Add one deliberately, when you have decided they belong in the field you measure yourself against. Recomma proposes competitors it has actually seen the models naming next to you, which is a better starting list than the one your team would write from memory — the models routinely name rivals you do not think of as rivals. ## How to read a change A rise in share of voice with flat visibility means the same chats are naming fewer other brands, or naming you more prominently among them. That is usually a positioning win rather than a distribution one. A fall with flat visibility means the field got more crowded. Check the [Brands](/product/brands) page for a brand that has climbed. ## Related --- # Visibility Source: https://docs.recomma.ai/metrics/visibility **Visibility is the share of chats that name the brand at least once.** A chat naming you three times still counts once. This measures reach, not repetition — whether you made it into the conversation at all. ``` visibility = chats naming the brand ÷ answered chats in the window ``` The denominator is every chat that came back with an answer, including the ones that named nobody. A model that declined to recommend anything still counts as a chat you were not in. Two edges of that denominator are worth knowing, because both are decisions rather than accidents: - **A failed chat is not in it.** A model that did not reply has no text to count, so it is recorded, retried, and left out of the rate — see [Chats](/product/chats#failed-chats). - **An empty answer is.** A Google results page carrying no AI Overview is a successful sample of nothing: the answer does not exist, so nobody is visible in it, and that is a finding about the question rather than a fault in the sampling. It lands in the denominator like any other answered chat. ## Where you see it The trend line carries two series. The filled one is your brand. The plain line above it is the **category leader** for that day — whoever was most visible, which may not be the same brand each day. The gap between them is the thing to watch: your own line rising while the gap holds means the category grew, not that you did. It also appears as a column in the Rankings table, per brand, and on every row of the [Prompts](/product/prompts) table, per prompt. ## How to read it **A percentage, not a count.** 73% does not mean 73 chats. It means roughly three chats in four named you, out of however many were sampled — which is why the sample size sits next to it. **It is bounded by your prompt set.** Visibility is measured over the questions you chose to track. Adding ten easy questions you already win will raise it without anything changing in the world. This is not a flaw to work around; it is why the number belongs to a prompt set, and why changing the set breaks comparison with what came before. A visibility trend is only comparable across a period where the prompt set was stable. If you add or remove prompts, expect a step in the line that is about the change, not about the market. ## What moves it Visibility is downstream of whether the pages the models trust on your subject mention you. Two levers, in the order they usually pay: 1. **Be present where the chats are already looking.** [Opportunities](/product/opportunities) ranks the domains that are cited on your subject and say nothing about you. These are cheap because the model already trusts the site. 2. **Be quotable on your own pages.** If your own domain is cited but the chats still do not name you, the pages being cited are not the ones that say what you do. ## Related --- # Agent search Source: https://docs.recomma.ai/product/agent-search Every other page under Measure reads a chat assistant: a question was asked, an answer came back, and the answer named somebody. An assistant that can *search* does not work that way. It calls a search index, gets a ranked list of URLs back, and writes from what it was handed — and the indexes it calls are not the ones a person uses. This page is that layer, measured on the same questions as the rest. ## Why both indexes Two of those indexes can be measured directly, and they disagree. Over thirty tracked questions across three brands, Brave and Exa found a brand eleven times between them and **agreed on two of those eleven**. A single index would have reported four fifths of this wrongly — in either direction. So both are drawn, and neither is averaged into the other. There is no combined number on this page on purpose. Averaging an index that returns you at #1 with one that does not return you at all produces a figure that describes neither, and hides the only thing worth knowing: which of them an agent happened to call. ## Indexes The panel at the top carries two figures per index, and they have to be read together. | Figure | What it answers | | --- | --- | | **N of 20 questions** | Whether the index *hands your pages back* when a buyer asks | | **holds at least N pages** | Whether the index *has your pages at all* | The sentence above them says which case you are in, because the two combine into different problems with different fixes: - **Not held** — neither index has your pages, so no question can return them. That is a crawling problem before it is a content one, and [Crawlability](/product/site#crawlability) is where it starts. - **Held and never returned** — your pages are in the indexes and none of these questions reaches them. What the pages *say* is the thing to change, not whether they are there. Neither vendor sells a page count. Coverage is measured with a `site:` query, which returns one page of results and no total, so the figure reads "at least". Both indexes reporting the same number usually means both hit that cap, not that they hold the same amount. ## The questions One row per question, ordered by **where you are missing** rather than by where you win. Questions no index returns you for come first, then the ones only one does, then the places that could be better. A brand that wins sixteen of twenty and one that wins two are both read from the top of the same table. - **Where it ranks** — a chip per index, carrying its name and your place, or a dash. Every index appears on every row including the ones that returned nothing, because a row reading `Brave —` beside `Exa #2` is the disagreement this page exists to report. - **Who is there instead** — the hosts that came back where you did not, for that question. A row of dashes says you are missing; the same row with three domains on it says who to read to find out why. Open a row for the page an index actually returned: ranked as it came back, your own result tinted, a tracked rival marked. The row is a summary of that page, so the page is what it opens. ## How often it runs One project is checked each scheduler tick and each project is checked weekly, so a newly tracked brand waits its turn rather than being checked immediately. Projects are ordered by age — oldest first — so a queue, not a draw. If the deployment has no index key configured the page says so rather than reporting zero of twenty, which is a finding it has not earned. ## Related --- # Competitors Source: https://docs.recomma.ai/product/brands Competitors live in the project's **Settings**, one panel below the brand's own details, rather than in the rail. The list is not a report — nothing on it is read daily. It is the definition of the field that [share of voice](/metrics/share-of-voice) and [position](/metrics/position) are computed across, changed a few times in a project's life and consequential every time, which is what a setting is. The old address still works: anything pointing at a project's brands lands on this panel rather than on a dead page, because bookmarks and command-palette history outlive a move. ## Why the list changes your numbers Both metrics count across the tracked set: - **Share of voice** — your mentions ÷ every *tracked* brand's mentions. - **Position** — where you rank among the *tracked* brands named in a chat. So a rival you have not added does not dilute your share and does not push you down a position. The numbers are not wrong; they are answering a question about a field you defined. Add a large, frequently-named rival and both figures will fall without anything changing in the world. Add them deliberately, and expect the step. ## Suggested competitors Recomma proposes brands it has actually seen the models naming alongside you, in your chats. This is usually a better starting list than the one a team writes from memory: the models routinely name rivals nobody internally thinks of as rivals — adjacent tools, incumbents you thought you had moved past, and occasionally a category you did not know you were being put in. Each suggestion links out to the site it resolved to, so you can check what it actually is before accepting. Accepting one starts counting it. Rejecting one keeps it rejected, so it is not proposed again. ## Reading the table Every tracked brand with all four metrics, your own marked. The rows worth attention are the ones where a column disagrees with the others: - A brand with **lower visibility but a better position** than you is winning the chats it appears in. It is being recommended where you are being listed. - A brand with **higher visibility and lower sentiment** is widely known for something. Read the chats before deciding whether you want to be there too. - A brand climbing on **share of voice** while everyone's visibility holds is taking mentions from the rest of the field. Each row opens onto that brand's own page — its trend, the prompts it wins, and the sources that name it. The sources one is the useful one: it is a list of pages that discuss your category and have chosen someone else. Your own row opens [your own page](/product/you): where you are named, where you are not, and the sources behind each. ## Related --- # Chats Source: https://docs.recomma.ai/product/chats A **chat** is one model's reply to one tracked prompt, on one day, from one location. Everything else in Recomma is counted off these: visibility is the share of chats naming you, a citation is a link inside one, a gap is a source cited by chats that never name you. They are kept whole, not reduced to a score, which is the point. A number you cannot trace is not evidence — so when a figure surprises you, this is the page that says why. ## What a chat records | | | | --- | --- | | **Prompt** | The question that was asked | | **Model** | Which surface answered — ChatGPT, Perplexity, Gemini | | **Status** | Whether it came back, and the error if it did not | | **Fidelity** | Interface or API — see [models](/reference/models) | | **Location** | The market it was asked from | | **Brands mentioned** | Who was named, and where in the text | | **Sources** | Every page the model opened, cited or not | ## Narrowing the archive Search matches the prompt's text; the model menu keeps one surface's answers. The third control, **Names you**, is the one to reach for first: it keeps only the chats that named your brand, or only the ones that did not. The second is the list of answers being given about your category without you in them, which is where the work is. Both readings are counted on the server, so the total in the footer is the total of the narrowed set. The same control, with the same two readings, sits on [Sources](/product/sources#names-you) and [Prompts](/product/prompts), so it need only be learned once. It lives in the address, so "the 64 chats that never name us" is a link you can send. The narrowed set is what **Export CSV** writes, not the whole archive. A filtered view is a question somebody asked, and the export is the answer to that question rather than everything the project holds. ## Sources and citations are not the same Every citation is a source; most sources are not citations. - A **source** is any page the model reached for while answering. - A **citation** is a source it went on to reference in the text. A model can open a page, read it and quote nothing from it. That is a different fact from never finding the page at all, and the two are recorded separately all the way down — which is why [Sources](/product/sources) carries both `Retrieved` and `Citation rate` rather than one number standing in for both. A visibility figure that moved is a summary of these. Open two or three of the chats behind it before deciding what changed: it is often the question being read differently rather than the brand's standing moving. ## Reading the table Five columns: the prompt, the model that answered, its **Fidelity**, the date, and the status. Status carries a dot as well as the word. Ninety-two rows reading "succeeded" in the same grey as the date beside them is a column you have to read to find the one row that did not — the colour is the second way of saying it, never the only one. A failed row says what went wrong rather than only that something did. Open any row for the whole answer. ## Failed chats A model that does not reply produces a failed chat. It is counted, excluded from the metrics — there is no text to count — and retried on the next pass. The Overview reports the window's total beside the chat count and explains only the failures still failing, so a model that has since recovered drops off the explanation without changing the count. ## Related --- # Impact Source: https://docs.recomma.ai/product/impact Most visibility work is done on faith: you write the page, you wait, and later the number is different for reasons nobody can name. Impact closes that loop twice over — a reading of where the brand is going, and a verdict on each thing you did. ## Total impact Two lines, because the page is asking two questions. - **Visibility** (left axis) — whether the answers name you. The metric switcher reads [sentiment](/metrics/sentiment), [position](/metrics/position) and [share of voice](/metrics/share-of-voice) on the same axis. - **Used as a source** (right axis) — how often the engines reached for *your own site* while writing those answers. The second is the one worth watching while you work the [Owned](/product/opportunities#site-health-the-audit) queue. Fixing a canonical or serving your content in the HTML changes whether an engine can read you before it changes whether it names you, so the dashed line moves first and the solid one follows. A page drawing only visibility would report that work as nothing happening. Two axes rather than one, because the two are not on the same scale and forcing them together flattens whichever is smaller into the floor. Days, weeks or months through the D/W/M control, each bucket weighted by the chats behind it. Sampling is a backlog, so the days are not evenly spaced — a week nobody sampled is drawn as a week. An evenly spaced axis would make that week look like a week that did not move, and the days either side of it look like a cliff. ## Action tracker **In progress** is what somebody picked up: actions you accepted with *Todo*. An action nobody has answered yet stays on [Actions](/product/opportunities), where it can be accepted or declined — counting it here would fill the tab with everything the product has ever thought of. **Done** is the verdict, below. ## How a verdict is reached When an action is marked done, Recomma records the reading at that moment and then keeps sampling. Once there is enough on the other side, it reports: - **Before** — visibility over the window leading up to the change, with its [sample size](/concepts#sample-size). - **After** — the same measurement since. - **Change** — the difference, in percentage points. The wait is **fourteen days from the day you marked it done**, and the ticket carries that date while it counts down. A verdict read the morning after a change is a verdict about the sampling schedule rather than about the change, and fourteen days is long enough for the prompts the ticket targets to be asked again on every model. The one thing that can stop a verdict is nothing to compare with: if no answer has been recorded against those prompts since the baseline was frozen, the ticket says so rather than reporting no change. A re-measure that has not happened is not a result of zero. A move from 40% to 46% is six *points*. Calling it "up 15%" is technically defensible and consistently misread, so Recomma does not. ## Statuses | Status | Meaning | | --- | --- | | **Open** | Proposed, not started | | **In progress** | Being worked on | | **Done** | The work is finished; the baseline is frozen and the fourteen days start | | **Verifying** | Waiting for enough chats on the far side | | **Verified** | Measured, with a before and after | | **Failed** | Measured, and the number did not go up — including when it fell | | **Dismissed** | Declined — kept, so it is not proposed again | **Failed** is deliberately not hidden, and it covers both "nothing happened" and "it got worse" — the verdict asks whether the figure went up, not whether it stayed still. An action that did not work is the most useful row on the page: it is the cheapest way to learn that a kind of work does not pay in your category, and the alternative is doing it four more times. ## What it cannot tell you Impact reports a correlation over a window, not a controlled experiment. Other things move in that window — a competitor launches, a model changes its retrieval, the category gets more crowded. Two habits make it trustworthy anyway: 1. **Check the intervals.** A change smaller than the [confidence interval](/concepts#confidence-interval) on either side is not a change. 2. **Look for the mechanism.** If visibility rose, the source you acted on should now show a higher *with you* on [Sources](/product/sources). A number that moved with no matching change in the evidence behind it is a coincidence until proven otherwise. ## Related --- # Keywords Source: https://docs.recomma.ai/product/keywords Keywords is the evidence behind the [Market](/metrics/market) panel. Category value and prompt coverage are arithmetic over a table, and a customer who cannot read the table has been handed a figure to believe rather than one to check. So the table is the page, and the figures sit in a line above it saying what it adds up to. ## What is in the pool Two kinds of row, and the **Rivals** column says which one you are looking at. **Contested** keywords are the pool's spine: the ones **at least two of the tracked domains rank in the top 20 for**, with commercial or transactional intent, priced and cut at 95% of the total value. The [full recipe is on the Market value page](/metrics/market#the-pool), including what it deliberately throws away. **Searched** phrases are demand that recipe cannot see. A keyword no tracked rival ranks for produces no evidence of a contest — and people are still searching it about a topic you track. These are taken per topic, most searched first, and held to the same cuts as the rest: priced, buying intent, and not already in the pool under another spelling. The Rivals cell reads `searched` rather than a number, because zero rivals here is a different fact from a keyword nobody wants. The result is small on purpose. A pool of a few dozen keywords is normal; it is the contested commercial head of a category, not a keyword export. The header carries the version and the date it was built. A pool is rebuilt monthly and kept as a numbered version, so a figure you quoted last month can still be reproduced. ## The table One row per keyword, ranked by what it is worth: | Column | What it shows | | --- | --- | | **Keyword** | The query, after near-identical variants were merged into one row | | **Value** | Monthly searches × 0.3 × CPC — this keyword's share of the category value | | **Volume** | Monthly searches in the project's country, from Google | | **CPC** | What advertisers bid for a click, from Google Ads. A dash means it is unpriced | | **KD** | [Keyword difficulty](/concepts#keyword-difficulty), 0–100, banded by colour | | **Rivals** | How many tracked domains rank in the top 20 for it — two is the floor — or `searched` where none do and the phrase is in the pool on demand alone | | **Intent** | `commercial` to compare, `transactional` to buy | | **Topic** | The [topic](/concepts#topic) it was placed on, or **Not covered** | The three inputs follow Value in the order they multiply, so the arithmetic on a row can be checked across it rather than taken on faith. **Difficulty weights nothing.** It is shown because it changes what the work costs — under 30 is a page, over 60 is a project — but ranking is by value alone until difficulty has been tested against a real queue. ## Uncovered demand The topic filter has a **Not covered** option, and above the table sits the figure it belongs to: how much monthly value reaches no tracked topic at all. That is the one number on this page that is directly actionable. It is not a gap in your visibility — it is demand you are being scored on in *neither* direction, because no question asks about it. **Suggest prompts** hands those keywords to the same writer that turns an imported keyword list into questions. Everything it writes lands in **Suggested** on [Prompts](/product/prompts), which is the state that waits for a person before it starts spending credits — so this proposes work rather than committing your budget. If it reads the list and writes nothing, it says so. A category whose uncovered demand is four generic keywords genuinely has no question worth tracking behind them, and that is a finding rather than a failure. ## Before the first pool Pools are built on the schedule, about once a month, and a project needs at least one competitor with a domain — the pool is defined by what you and your rivals rank for, so with no rival there is nothing to contest. Until then the page says there is no pool, rather than showing an empty table. The same applies to the [Market](/metrics/market#when-a-figure-is-missing) panel on the Overview: it does not render until there is something to render. ## Related --- # Opportunities Source: https://docs.recomma.ai/product/opportunities Two different questions fill this queue, and it matters which one produced a ticket. **Where is the category being read without you?** [Sources](/product/sources) tells you which sites the models lean on; this narrows it to the ones cited on your subject **while saying nothing about you**. Those are the cheapest ground you can take, because the hard part is already done — the model trusts the site. **What is wrong with the pages you already have?** That question needs no rival and no gap. It is answered by reading your own site and holding each page to a fixed set of rules, and it has an answer on your first day, before a single chat has been sampled. The first question can only be asked once somebody is ahead of you. A brand with plenty of citations and no visible rival gets nothing from it — correctly, and unhelpfully, if it were the only question being asked. ## Earned and Owned The rail lists this page twice, because the work divides cleanly in two and the two are done by different people: - **Earned** — somebody else's site. A community you can take part in, or a publication you have to earn a mention in. The work is a pitch or a post. - **Owned** — a page you control, which splits again: - **Site health** — a page you already have that breaks a rule. The work is an edit, usually to a template. - **New pages** — a page you do not have yet. The work is writing it and shipping it. Both open the same queue scoped to their half, so each is an address you can send to whoever does that kind of work. The unscoped page is still the whole list, and it is the one to read when deciding what to do *first* — ranking is computed across everything, and two lists each ranked against themselves cannot say which of the two matters more. A rival's own site appears on the unscoped list and on neither half: it is context, not work, because you cannot publish there. The rail itself holds five branches, which is those four with the competitors beside them: | Branch | What is in it | | --- | --- | | **Earned · Community** | Communities you can take part in | | **Earned · Editorial** | Publications and references you have to earn a mention in | | **Owned · Site health** | Faults on pages you already have | | **Owned · New pages** | Pages you control — write it and ship it | | **Competitors** | A rival's own site: you cannot publish there | **Reference** has no branch of its own. Documentation and encyclopaedic sources sit under Earned · Editorial, because the work is the same one — you have to earn the mention — and a lane holding two tickets a quarter is a lane nobody opens. ## How a gap is scored A [gap](/concepts#gap) is a domain the chats cited without naming you in the same chat. There are two ways for one to qualify, and which applies depends on how visible you are overall. **If you appear in 15% of chats or more**, a gap is a source that treats you worse than the web does: ``` gap strength = your overall visibility − that source's coverage of you ``` The subtraction is the important part. A source that already mentions you about as often as the web at large is not a gap, however often it is cited — you are already as present there as you are anywhere. What ranks is the source that is *less* friendly to you than your average, weighted by how much the models actually lean on it. **Below 15%**, that subtraction cannot produce anything. Gap strength is at most your overall visibility, and a gap has to clear a floor of 15 points before it is worth a ticket — so a brand at 3% has no source that can qualify, whatever the data says. The test does not become strict; it becomes impossible. So below the floor the question changes to the only one that can be answered: ``` gap strength = how much of that source's reach goes to somebody else ``` A source qualifies when it shaped at least three of your chats and named you no more often than you are named anywhere. That is not a claim that the source is singling you out — at 3% visibility, three chats naming somebody else is not a surprising event. It is a claim that the chats demonstrably look there and you are not present, which is what `Get listed` and `Pitch editorial` have always meant. Tickets from the second mode say so, and quote your overall figure rather than a comparison they did not make. [Source type](/concepts#source-type) is part of the weighting: editorial coverage counts for substantially more than a corporate page, because it is harder to win and the models lean on it more. ## Kinds of opportunity Each one carries what sort of work it implies: | Kind | What it means | | --- | --- | | **Owned page** | Your own site, on a subject where it is not being cited | | **Editorial** | Press or a publication covering your category without you | | **Reference** | Documentation or an encyclopaedic source | | **UGC** | A forum or community thread | | **Competitor** | A rival's own site — a positioning job, not a page to write | | **Site health** | A page of yours that breaks one of the audit rules | The last is deliberately not actionable in the same way. It is listed because knowing that a model's chat rests on a competitor's own marketing is worth knowing, even though the action is not "go and edit their site". ## Filing by status Every action is in one of four states, and the bar at the top of the page holds them apart. | Tab | What is in it | | --- | --- | | **New** | Proposed, and nobody has answered yet | | **In progress** | You pressed *Todo* — it is also on [Impact](/product/impact) | | **Done** | Finished, and being re-measured | | **Declined** | You said no | Counts are taken inside whichever scope the page is showing, so a number never sends you to a tab that looks full and renders empty. **Declined is a real tab**, not a bin. A declined action is kept so it is not proposed again, and it can be restored from here — a decision made by accident should be reversible, and a decision made on purpose should be reviewable. ## Site health: the audit Press **Run audit** and Recomma reads your own pages — found through your sitemap, not through your citations, because the pages with problems are usually the ones nothing has quoted yet. A site with hundreds of pages in its sitemap typically has a handful that have ever been cited. The same rules, and the crawl behind them, are readable without a ticket on [Site](/product/site) — the state of your own site whether or not anybody has decided to act on it. A rule can fail there and carry no ticket here: a ticket is raised when a fault clears an impact bar, and a rule failing on a handful of pages may never clear it. Each page is held to fifteen rules. Every rule is a fact about the markup that you can check by viewing source, and every one has a fix that fits in a diff: | Rule | It fires when | | --- | --- | | Canonical points at itself | The canonical tag names a different address | | Canonical declared | There is no canonical tag at all | | Content boundary | Neither `main` nor `article` marks the page's own content | | One H1 | The page has two or more | | An H1 | The page has none | | Heading order | A level is skipped — an H2 followed by an H4 | | Publish date | A post carries no `time datetime` and no `datePublished` | | Last-updated date | Schema declares a publish date and never a modified one | | Current year in the title | A comparison or best-of list whose title names a past year | | Open Graph type | No `og:type` tag | | FAQ schema | Three or more question headings and no `FAQPage` block | | Contents list | A long, sectioned page with no in-page links | | Alt text | Images with no `alt` attribute | | Quote attribution | Two or more blockquotes naming nobody | | Content in the HTML | Plenty of markup, almost no prose — the page renders in JavaScript | | AI crawlers | A retrieval crawler is shut out in `robots.txt` | One ticket per rule, not per page. "Add alt text to the images that have none" is one job whether it touches one page or forty — and each ticket lists the pages it covers, with the markup on the page beside the markup to replace it with. ### What the audit will not tell you There is no rule for "move the author bio into an aside" and none for "improve the introduction". Both are real advice and neither can be decided from a shape. A finding you cannot verify costs more trust than the finding is worth, so the list above is the whole of it. Two things the rules are deliberately careful about: - **Documentation is not dated writing.** An API reference page is not stale for having no publish date, so it is never asked for one. - **Blocking a training crawler is a decision, not a fault.** Only the crawlers that fetch a page in order to answer a question count here. Keeping CCBot or Bytespider out costs you nothing in the engines this product measures. What your `robots.txt` says to each of them, agent by agent, is on [Site](/product/site#crawlability). ### Reading a partial audit A crawl is a backlog, so a ticket can be a true statement about the pages read so far and not yet about the whole site. Every audit ticket says how much of it is based on, beside the page count. A number that did not say so would make a partial reading look like a complete one. The same care applies inside a single page. Recomma reads up to 2MB of each one, and a page longer than that arrives as a fragment — so the rules that reason from *absence* decline to run on it. A rule that fires on something it saw (two H1s, a canonical pointing elsewhere, a skipped heading level) is telling the truth about a fragment as much as about a whole page. A rule that fires on something it did not see is not. ## Working them Each opportunity can be taken, moved along, or dismissed. Dismissing is a real decision and is kept, so it is not proposed again — the page should get shorter as you work, not repeat itself. Once something is done, it moves to [Impact](/product/impact), which watches the figure afterwards and reports whether it moved. ## When there is nothing here The two halves go empty for different reasons, which is why they are read separately. **Earned** has three quite different causes, and the page says which: 1. **Nothing has been sampled yet** — there are no chats to find gaps in. 2. **The gaps are there but not yet cut into tickets** — tickets are cut at the end of every sampling pass, so this lasts only until the next one; **Find gaps** cuts them now. 3. **Every cited source covers you** — no source is covering the category without covering you. In the third case the page still lists the three sources covering you least well. "Nothing to do" is where a page stops being worth opening; those three are the same numbers ranked the other way, and the first place you would lose ground. A single branch can be empty while the others are not — a category the models never discuss on Reddit has nothing under Community, however visible you are. An empty branch says so in a word rather than explaining itself. **Site health** goes empty for one reason: the pages read so far break none of the rules. The panel says how many that is. ## Related --- # Overview Source: https://docs.recomma.ai/product/overview The Overview is one screen that answers "where do we stand", scoped by the filter bar at the top. Everything on it reads from the same scope, which is why the filters live once at the top rather than being repeated per panel. ## The filter bar Four scopes, and each one changes the denominator of every figure below it: - **Period** — how far back the chats are drawn from. - **Model** — one model, or all of them. Models disagree; the all-models figure is an average over that disagreement, so it is worth checking a metric per model before concluding anything about it. - **Locations** — one market's answers, or all of them. The same question asked from two countries is two different answers, not one answer measured twice. - **Topic** — one [topic](/concepts#topic)'s prompts, or all of them. A filter appears only when there is more than one thing to filter by. A project measured in one market draws no locations filter, because a menu offering "All locations" and "US" is two choices that select the same rows. ## Visibility The headline is [visibility](/metrics/visibility) over the whole window, with its [sample size](/concepts#sample-size) and [confidence interval](/concepts#confidence-interval) beside it — those two are what make the percentage a reading rather than a number. The chart carries two series. The filled one is you; the plain line is the **category leader** on that day, which is not necessarily the same brand each day. `D` / `W` / `M` change the granularity. Below the chart, the panel says how many chats it is showing and how many failed. A failed chat is a model that did not reply — usually a timeout, and retried on the next pass. It is shown rather than hidden because a figure measured over most of the chats that were asked is a slightly different claim from one where everything came back. It also says what was left out. Answers belonging to a [paused prompt](/product/prompts) are not counted, and the caption names how many — so a figure that moved the morning somebody paused three prompts has its explanation on the same line rather than looking like a change in the market. ## Rankings Every tracked brand, yours marked, with all four metrics side by side. This is the panel to read when a single figure looks good — the interesting information is usually in the disagreement between columns. See [Metrics overview](/metrics#they-answer-different-questions) for the patterns worth recognising. ## Market What the questions above are drawn from, priced — and then narrowed twice. Three rows, each one a part of the row above it: - **Category value** — what advertisers pay per month for these intents, built from the keywords this brand and its rivals are contested on. The full width of the panel, because it is the whole. - **Tracked by your prompts** — how much of that value a topic you ask questions about reaches, in dollars and as a share of the category. What is left is named beneath it — untracked demand, and the part [Keywords](/product/keywords#uncovered-demand) gives a button for. - **Named in answers** — the [captured](/metrics/market#captured) share, drawn inside the tracked part rather than against the whole, because a share of money nobody asks about would not mean anything. The last row is drawn only when it is a reading. Before any answers have landed against a priced topic, or when the topics carrying it are too thin, the row says so in words instead of printing a figure — "51 chats — too few to read" rather than a number somebody would quote. The panel does not render at all until a pool has been built, which happens on the schedule. The panel says what share of a priced market the answers reach. It never prints a figure for "value captured", because being named in an answer is not a click. See [how a keyword is priced](/metrics/market#how-a-keyword-is-priced). ## Top domains The sites the chats actually leaned on, ranked. Each row carries: - **Retrieved** — the share of chats that reached for it at least once, cited or not. - **Citation rate** — citations ÷ the chats that retrieved it: how heavily a chat that opened it ends up quoting it. - **Type** — [what kind of site](/concepts#source-type) it is. The panel is ranked by `Retrieved`, and it is the same query the [Sources](/product/sources) page runs — rows here and rows there are the same domains with the same numbers, grouped the same way. The `Type` column is the one to scan. A category whose chats rest mostly on **Reference** and **Editorial** sources behaves differently from one resting on **UGC**: the first is won with documentation and coverage, the second in communities. Rows open into the source's own page. Full detail is on [Sources](/product/sources). ## Domain types The same citations, aggregated by kind — what proportion of the evidence behind your category's chats is corporate, editorial, reference, UGC, owned or competitor. This is a shape-of-the-category panel rather than a scoreboard. It tells you where effort pays before you have spent any. ## Latest chats The last panel, spanning the page: the answers the panels above are summaries of. Every figure on this screen is an aggregate, and an aggregate is worth whatever a reader believes about the evidence under it — so the evidence is on the same screen rather than a click away. It has its own filters, because it is a list rather than a figure: search the prompt text, and narrow by brand, by source domain or by model. Each of those is built from what has actually been sampled, so a filter with one real choice behind it is not drawn. Open a row for the whole answer, with the brands marked and the sources it used beside it. The full archive, paged and exportable, is on [Chats](/product/chats). --- # Prompts Source: https://docs.recomma.ai/product/prompts Prompts are the whole measurement. Every figure in Recomma is counted from chats for these questions, so the set you keep decides what the numbers mean. ## The table One row per tracked question, each with its own reading: | Column | What it shows | | --- | --- | | **Prompt** | The question, its [topic](/concepts#topic), [funnel stage](/concepts#funnel-stage) and market | | **Visibility** | The share of *this question's* chats that named you | | **Sentiment** | How favourably they spoke about you | | **Position** | How early you were named | | **Mentions** | Which brands were named, in order | This is where an Overview figure becomes actionable. A visibility of 73% across the project is a number; the six questions at 0% are a list of things to do. The default sort is worst-first, because the question you open this page with is "where am I losing". ### Names you The second band of controls carries **Names you**: only the questions whose answers named your brand in the window, or only those whose answers never did. It reads the same count the Visibility column is built from, so a question at 0% is a question the filter puts on the "doesn't name you" side. The same control sits on [Chats](/product/chats) and [Sources](/product/sources#names-you). ### In your words A question can quote your own site. A search-backed engine matches those phrases straight back to your pages, so the answer finds you because the words came from you — which is the site being *found*, not the brand being *recommended*. Those two are not the same measurement and should not be read as one. The toggle carries the count, and pressing it keeps only those questions. Read them separately: a set with several of them scores higher than the same brand would on questions a buyer wrote, and the gap between the two readings is worth more than either. ### Tags Tags are yours — a label on a prompt that means whatever your team needs it to mean: a campaign, a launch, a region, an owner. A prompt can carry several. Select rows and assign one to all of them at once. Assigning **adds**; it does not replace, because the rows in a selection rarely carry the same tags and quietly stripping them would destroy work nobody asked to touch. The tag menu in the filter bar narrows the table to one of them, with the number of prompts carrying each. ## The topic rail Topics on the left, prompts on the right. A prompt carries exactly one [topic](/concepts#topic), and the rail lists whatever topics the prompts carry — there is no separate list to maintain, and a topic with no prompts under it does not exist. Adding a topic and writing its first questions is therefore one action, not two. ## Tabs - **Active** — tracked and sampling. - **Suggested** — proposed but not yet tracked. These cost nothing while they sit here. Tracking one starts consuming credits on the next cycle. - **Inactive** — kept, not sampling. Their history is preserved. A prompt can move to Inactive without anybody pressing anything. When ten or more answers in a row name no tracked brand *and no other company*, the question is not measuring a market — it is being answered generically — and sampling it further spends credits on nothing. It is paused, and the row says so. Resume it if you want it sampled anyway; it will not be paused a second time. Coverage grows on purpose rather than by surprise. A discovered prompt sits in Suggested until a person accepts it, so nobody finds their bill has grown because the product found forty more questions worth asking. ## Adding prompts Four ways in, all landing in the same place: - **Add prompt** — write one yourself. - **Import keywords** — paste a list, typically from Search Console. Recomma turns them into questions; a bare keyword measures nothing, because models answer questions. - **Discover prompts** — Recomma reads what you already track and proposes questions you are missing. Suggestions cost nothing until accepted. - **Suggest prompts from uncovered demand** — on [Keywords](/product/keywords#uncovered-demand), the keywords your category is contested on that no tracked topic reaches. Same writer, same destination; the list comes from the market rather than from you. Adding a topic proposes its first questions in the same step, ticked by default, with the stage each one was assigned. What you untick is never stored. ## Writing a good prompt A prompt should be a question a buyer would actually type, specific enough that a useful chat names brands: | Weak | Better | Why | | --- | --- | --- | | `crm software` | `What's the best CRM for a small B2B sales team?` | A keyword is not a question | | `is Acme good` | `How does Acme compare to Salesforce for a 20-person team?` | Invites a comparison, which is what buyers ask | | `best software` | `What's the best project management tool for agencies?` | Unscoped questions produce unscoped chats | Cover the whole decision. A set that is all awareness questions tells you about category presence and nothing about whether you win the comparison — and the comparison is where deals are lost. ## Deleting a prompt Deleting removes its history. The readings you have built are per prompt, so a prompt deleted after a month takes that month with it. Prefer **Inactive** if you might want the question back. ## Related --- # Ranking Source: https://docs.recomma.ai/product/ranking The [Overview](/product/overview) carries this table cut to its top six and ranked on visibility, which answers "how am I doing against the field" and stops there. This is the rest of it: every tracked brand, and the ability to ask a different question of the same rows. Who leads on visibility is not who leads on sentiment, and a panel that is already a top-six cannot be asked which. ## The columns | Column | What it reads | | --- | --- | | **#** | Place in the current ordering, not a standing rank | | **Brand** | Your brand and every rival on [Brands](/product/brands) | | **[Visibility](/metrics/visibility)** | Share of answers that name the brand at all | | **[SOV](/metrics/share-of-voice)** | Share of all brand mentions that were this brand | | **[Sentiment](/metrics/sentiment)** | How the answers talk about it when they do | | **[Position](/metrics/position)** | Where in the answer it tends to appear | The four figures are all sortable, and the one you sort by is the question you are asking. A brand can be named in more answers than anybody and still be mentioned in passing at the end of each one — visibility and position disagreeing is a finding, not a contradiction. A rival nobody has measured yet has no position, and an unmeasured brand is not a brand that scored zero. It goes to the bottom whichever direction the column runs, rather than topping a list of "best positions" with an absence. ## Scope The same bar as the Overview and Sources: date range, engine, country and topic. Each filter is built from what has actually been sampled, so a project measured on one engine draws no engine filter. A filter with one thing to filter by is not a filter, and drawing it implies a choice that does not exist. Narrowing the scope re-reads every figure in the table under it. Visibility on one engine is a different number from visibility across all of them, and it is the engine-by-engine spread — not the average — that usually explains a figure somebody is arguing with. ## Where the numbers come from This page reads the same query the Overview does, under the same scope. Two consequences, both deliberate: the two pages cannot disagree about a figure, and moving between them costs nothing because the cached result is the same. Every figure is computed from the answers on [Chats](/product/chats). A number here that looks wrong is traceable to the answers behind it, which is the point of keeping them. ## Related --- # Site Source: https://docs.recomma.ai/product/site Every other page in Recomma is downstream of an answer. This one is not: it is the state of your own site whether or not a single chat has been sampled, and whether or not anybody has decided to act on it. It reads from two things the product was already collecting and neither of which had a home: the crawl of your sitemap, and the audit findings behind [Site health](/product/opportunities#site-health-the-audit) tickets. Findings could previously only be reached through a ticket, which meant the state of your site was legible only where somebody had already decided to do something about it. ## The strip Three figures across the top, each the worst number in the section under it: | Figure | What it reads | | --- | --- | | **Pages read** | Fetched against discovered, with the failures and the backlog beneath it | | **AI crawlers shut out** | How many are blocked outright, and how many more are kept off some paths | | **Markup faults** | Failing pages in total, over how many rules, and how many are ticketed | Pages are found from your sitemap rather than from your citations, because the pages with problems are usually the ones nothing has quoted yet. It is a backlog worked on the schedule, so a waiting count above zero is normal on a large site and is the reason an audit can be a true statement about part of a site. ## Crawlability What your `robots.txt` says about the crawlers that fetch pages in order to answer questions — GPTBot, ClaudeBot, PerplexityBot and the rest. Only findings are listed. Most sites carry housekeeping disallows that every crawler on the web falls under, and reporting those would say every site blocks every agent. A row is a **decision**, not a crawler. A `robots.txt` is a short list of decisions — "keep these bots out of that path" — so one rule that shuts nine crawlers out of one path is one row here rather than nine rows repeating the same path. The crawlers it governs are listed under it as chips, grouped by the company that runs them, which is how anybody thinks about who is allowed in; hover a chip to see the tokens behind it. - **Blocked** — shut out of the site. - **Partly blocked** — shut out of some paths, which are listed on the row. ### What changed `robots.txt` is re-read on a schedule, and every change is kept. Open the fold at the foot of the panel for the history: which crawler moved, which way, and on what day. A brand that lost its visibility the week somebody added a `Disallow` has the answer here rather than a coincidence. Only the crawlers that fetch a page in order to answer a question matter here. Keeping CCBot or Bytespider out costs you nothing in the engines this product measures — they are listed because a reader asking "who can read my site" wants the whole answer, not because they are a finding. If `robots.txt` could not be fetched, the panel says so rather than reporting the site as open. Unreachable is not permissive. ## Markup Every [audit rule](/product/opportunities#site-health-the-audit) the site currently fails, with how many pages fail it. Open a row and it gives the rule in a sentence, the pages it fires on, and the markup on each one. The **State** column is the link back to work: - **ticketed** — an action is open against this rule on [Opportunities](/product/opportunities). - **untriaged** — no ticket. Which is not the same as no problem: a ticket is raised when a fault clears an impact bar, and a rule failing on four pages of a large site may never clear it. Somebody reading their own site should see it either way. That distinction is why this page is read-only. A ticket is work somebody has decided to do; this is the site's condition whether anybody has decided anything, and the two answer different questions. Run the audit, take tickets and mark them done on [Opportunities](/product/opportunities). ## Pages The crawled inventory, worst first: pages that failed, then pages nothing has read yet, then the oldest readings. Each row carries the URL and the status the crawler got back. The table pages through the whole inventory rather than showing a sample of it. ## Related --- # Sources Source: https://docs.recomma.ai/product/sources A chat is not an opinion the model formed on its own. It is assembled from pages the model read while answering, and those pages are recorded. Sources is where [visibility](/metrics/visibility) stops being a symptom and becomes something you can act on: if the pages a model trusts on your subject do not mention you, no amount of writing on your own site will change the chat. Each of the two pages opens the same way — the scope bar, what moved, what the chats rest on, and then the table itself. The scope bar is the Overview's: period, model, locations and topic, each built from what has actually been sampled. Everything below it re-reads under the scope, so "which sites does Gemini trust in the UK" is the same page asked a narrower question. ## Retrievals over time The five sources the models reached for most, day by day, switchable to weeks or months. Everything else here is a stock take of how the field looks now; this is the only reading that says what *changed*, and a source the models started reaching for last week is the cheapest lead on the board because nobody has worked it yet. ## Movers The same rows read four ways. | Tab | What it lists | | --- | --- | | **Top** | Most retrieved in the window | | **New** | Retrieved in this window and never before it | | **Trending** | Retrieved more than in the window before this one | | **Losing** | Retrieved less than in the window before this one | Clicking a row filters the table below to it. **New**, **Trending** and **Losing** are claims against earlier history, so on a workspace younger than one window they say so rather than listing everything as new. ## Domain types, URL types Beside the movers, the same window split by kind: on Domains, whose site the chats rested on; on URLs, what shape of page. The two answer different questions and the hints say which — "whose site, not what shape of page", and the reverse — because the same chat is both a corporate domain and a comparison page, and reading one split as the other is the mistake the pair is arranged to prevent. This is a shape-of-the-category reading rather than a scoreboard. A field resting on reference and editorial pages is won with documentation and coverage; one resting on discussion is won in communities. ## Domains Every site the chats leaned on, ranked. The columns: | Column | What it counts | | --- | --- | | **Type** | [What kind of site](/concepts#source-type) it is, or **Unclassified** where nothing has placed it yet | | **Mentions** | Which of your tracked brands were named in the chats that used it — you first | | **Retrievals** | Every time a model reached for it, cited or not, counted in full | | **Retrieved** | Share of *all* chats in the window that reached for it | | **Retrieval rate** | Retrievals ÷ chats that retrieved it: how many of its pages a chat opens | | **Citation rate** | Citations ÷ chats that *retrieved* it: how heavily a chat that opened it ends up quoting it | **Mentions** is the column that turns this table into a to-do list. A domain retrieved in 40% of chats whose stack never shows your logo is being trusted on your subject while saying nothing about you. That is a [gap](/concepts#gap), and [Opportunities](/product/opportunities) ranks them for you. ### Domains and Hosts `stripe.com` and `docs.stripe.com` are one site and two hosts. The **Domains** tab rolls a site up from its hosts; **Hosts** splits them apart again. The rollup is the one you want first — without it a company's docs, blog and marketing site compete with each other for a row instead of adding up to one, and no row in the table answers "which sites do the models trust". Hosts is the one you want second, because "their docs are cited and their blog is not" is a different instruction from "their site is cited". ## URLs The same question one level down: not "which sites" but "which pages". This is what you need before you can do anything — "get mentioned on TechRadar" is not a task, but "this specific comparison page is retrieved in 60 chats and does not list us" is. Two of its columns are its own: - **URL type** — what shape the page is: article, product page, comparison, alternative, listicle, how-to, homepage, discussion, video. Separate from whose site it is on, and the only one of the two that says what to go and *write*. "A third of what the models read about us is comparison pages" is an instruction; "a third is on corporate domains" is a fact. - **You** — whether your brand was named in any chat that used this page. The shape is worked out from the URL and, where the page has been fetched, its title. It does not need the crawler to have succeeded: Reddit blocks crawlers and is the single most-cited source on some workspaces, and a column that shows a dash for a quarter of its rows is a column nobody reads. ## Names you Both tables carry a **Names you** control beside the type filters. It keeps only the sources whose answers named your brand, or only those whose answers never did — and the second is the to-do list: pages the models trust on your subject that are doing their work for somebody else. "Named" is decided across the window: one answer naming you while using the source is enough for it to count as named. The filter is applied in the query, so the pager's total is the total of the narrowed set, not of the page on screen. **Export CSV** writes that same narrowed set — every row the current scope and filters select, not only the page on screen and not the whole project. ## Read but not cited Where a model reports the pages it opened, Recomma records the ones it read and then did **not** cite. Retrieved and cited are separate figures throughout for exactly this reason: - **Never retrieved** — the model did not find the page. A discovery problem. - **Retrieved, not cited** — the model found it and did not think it worth quoting. A content problem. The two need opposite fixes, and a table with one number for both makes them look identical. ## Crawlability Each domain carries what its `robots.txt` says about AI crawlers — GPTBot, ClaudeBot and the rest. A site that blocks them has made a choice about being quotable, and one that blocks them while ranking well in classic search is a site whose influence in AI chats will fade. Worth checking on your own domain first — and [Site](/product/site#crawlability) is where to do it, because that one reads the whole agent list and keeps a history of what changed, while this is one domain's verdict beside its numbers. It appears in these tables as type **Owned**. If your own domain has a low retrieved figure on questions about your own category, that is the finding — the models are answering about you from other people's pages. ## Related --- # Traffic Source: https://docs.recomma.ai/product/traffic Every other page in Recomma measures what an engine *said*. Traffic measures what happened next: the sessions on your site that began at ChatGPT, Perplexity, Gemini and the rest, read from your own GA4 property once a day. It is the first figure in the product that is a visitor rather than a mention. Nothing is installed on your site and nothing is written to your Analytics. The connection is a read-only grant to one GA4 property, and the page reads rows Recomma pulled, so opening it costs your Analytics quota nothing. ## Connecting **Settings → Connect Google Analytics** sends you to Google's consent screen. Two moves, because Google does not say which property you meant: 1. Grant read-only access to Analytics. The same consent asks for Search Console, which a later page will read; granting it now means Google's review of the app happens once. 2. Choose the property — and the web stream, if the property has more than one. The first ninety days arrive on the next scheduled pull, usually within the hour, and every day after that the last three days are read again, because GA4 keeps revising a day for about that long. One property per project. A project whose site is measured under two properties connects the one that holds the pages assistants cite. Step two has two ways out, because the account you signed in with may be the wrong one and half a connection is not a place to be stuck. **Use another Google account** restarts the trip — there is no property to keep yet, and the reason to be there is that the account was wrong. **Disconnect** drops the grant entirely. If Google refuses the property list, the step says what Google said and offers to try again, rather than waiting on a list that is not coming. The usual cause is an API the operator has not enabled yet, and Google's own message names it. If Google stops honouring the grant — the account that connected it left the company, or the app was removed under the account's third-party access — the page says so and offers to reconnect with the property kept. The rows already pulled stay. ## Which sessions count Two rules, both applied: - **GA4's own flag.** Since May 2026 GA4 marks a session whose referrer is on its list of AI assistants with the medium `ai-assistant` — ChatGPT, Gemini, Deepseek, Copilot, Grok. - **Recomma's own list.** GA4's list leaves out Perplexity, Claude, Meta AI and You.com, whose visits arrive as ordinary referrals. Recomma matches the referrer host against its own list as well, so those count too. A session GA4 flagged from a host Recomma does not recognise is counted as **Other AI** rather than dropped: it is AI traffic, just not attributed to a name. A session neither rule matches is not AI traffic, as far as either can tell. Landing pages are folded to one path with the query dropped, because ChatGPT's `?utm_source=chatgpt.com` stamp is the assistant's mark rather than a second page. ## The Overview The sentence at the top names the leading assistant, its share of AI sessions, and what share of *all* the site's sessions AI sent. Under it, five tiles, each with its movement against the window before: | Tile | What it counts | | --- | --- | | **Sessions** | Sessions that began at an assistant, over the window | | **Key events** | GA4's key events (conversions) in those sessions | | **Conv. rate** | Key events ÷ sessions | | **Engagement** | Engaged sessions ÷ sessions, by GA4's definition — over ten seconds, a key event, or a second page | | **Revenue** | Purchase revenue attributed to those sessions | **A property that does not measure a thing shows a dash, not a zero.** A site with no key events set up has not converted zero visitors; it has not counted. The same for revenue on a property without e-commerce. A movement is shown only when both windows rest on at least twenty sessions. Under twenty sessions in the window the figures render greyed: they are real, and too thin to read a rate off. The chart stacks sessions by assistant at the day, week or month grain, so its height is the total and its bands are the split. ### The Channels table Every channel GA4 groups the site's sessions into, with the AI column saying what GA4 can and cannot attribute: | Channel | AI column | Why | | --- | --- | --- | | AI Assistant | **Measurable** | GA4 flags the referrer, and Recomma's list adds the assistants it misses | | Organic Search | **May hide AI** | Google's AI Overviews and AI Mode are counted as search, by GA4's own definition | | Direct | **May hide AI** | Assistant apps that send no referrer land here | So the AI sessions above are a **floor**. The honest reading of "AI sends 4% of your traffic" is "at least 4%, and the rest may be in these two rows". The table is drawn even before a connection exists, because it is the reason to connect. ## Pages Two lists from two tables. **Landing pages** are where an assistant's visitors arrived, with sessions, share of AI sessions, key events and conversion rate per page. **Conversions by page** are where their key events fired, which is often a later page than the one they landed on. After the five columns any GA4 reader shows come four that only Recomma can fill, because they join the landing page to what the product already measures: | Column | What it shows | | --- | --- | | **Cited by** | How many tracked prompts' answers have ever cited this page — click to list them, each tagged with whether the citation came from a model's API answer or the real interface. **Never cited** means an assistant sent people to a page no sampled answer has quoted: a page your prompt set does not know about | | **Topic** | The [topic](/concepts#topic) those prompts sit in | | **Pool value** | What that topic is worth per month in the [keyword pool](/product/keywords). Only drawn once a pool is built and placed; never a zero | | **Ticket** | Whether a [Site health](/product/opportunities#site-health-the-audit) ticket is open on this page | The two fidelities are kept apart on purpose. If most landing pages read **Never cited**, that is a finding about the prompt set — or about how far the URLs a model's API answer cites match the ones the real interface shows — and not a fault in the join. The filters at the top — window, assistant, device, country — narrow both views. Share of site is blank under a device or country filter, because the site-wide count carries neither and a share of the wrong whole is not a share. ## Settings The account, property and stream the page reads, when it was last pulled, and the last error if a pull failed. **Force reauthentication** takes a fresh grant from Google with the property kept. **Remove connection** deletes the grant and every row pulled under the project, and needs an admin: the last ninety days come back on a reconnect, but days GA4 has since aged out do not. ## Before a connection The page is the connect button and the Channels table's two *May hide AI* rows. It is never empty: the reason to connect is written where you are deciding whether to. --- # Your brand Source: https://docs.recomma.ai/product/you Every rival in [Competitors](/product/brands) opens onto a page that compares it with you. This is your own: the [Overview](/product/overview)'s four figures with how each moved since the window before, and then the two lists that turn a number into a place to look. Reach it from the **You** row on the Overview's Rankings, or from your own card under Settings → Competitors. It is not in the rail: it is your row, opened. ## The figures Visibility, share of voice, sentiment and average position, each against the same window immediately before this one. A change is shown only when both windows clear the sample floor; otherwise the tile says there is no earlier reading rather than inventing a rise from zero. ## Visibility over time Under the figures, the same share day by day. A tile says where you are; the line says whether you are going there — and a figure that has not moved since the window before can still be the flat end of a fall that happened inside it. ## Where you are named, and where you are not Two lists of questions, from the same prompt set the Overview measures: - **Where you are named** — questions whose answers named you at least once in the window, best first, with the share of that question's answers that did. - **Where you are not** — questions whose answers never named you, most asked first. This is the work: the engines are answering these about your category without you in the answer. Each list shows eight and links to the rest, which is the [Prompts](/product/prompts) page under its **Names you** filter. ## By model Your visibility on each model, with the chats behind it. Models disagree, and a brand at 40% overall is usually a brand at 70% on one model and 10% on another; this is where that shows. ## Sources behind your mentions, and sources that leave you out The sites cited in the chats that named you, and the sites cited in the chats that never did. "Cited while naming you" is not "mentions you" — nobody reads the page — but the second list is a list of sites the models trust on your subject that are doing their work for somebody else. Both link to [Sources](/product/sources#names-you) under the same filter. ## Recent chats naming you The newest answers that named you, so the figures can be read against what was actually said. The [Chats](/product/chats) page holds the rest under **Names you**. ## Related --- # Quickstart Source: https://docs.recomma.ai/quickstart Setup takes a few minutes. Getting a reading you can *act* on takes as long as the models take to chat — which is why the last step here is about waiting, and what to look at while you do. ## Add the brand Give Recomma your domain and the market you sell into. It reads the site and works out what you sell, who you sell against, and the language your buyers use for it. Two things come out of that read, and both are proposals rather than decisions: - **Prompts** — the questions Recomma thinks your buyers ask. - **Competitors** — the brands it expects to be named alongside you. Nothing is tracked until you approve it. A proposed prompt costs nothing while it sits there; it starts costing when you accept it, because accepting it means running it on every model, every cycle, from then on. ## Fix the prompt set before anything runs This is the step that decides whether the numbers are worth reading, and it is the one people skip. A prompt is a question a buyer would actually type. Not a keyword — models answer questions, so a bare noun phrase measures nothing: | Instead of | Write | | --- | --- | | `project management software` | `What's the best project management tool for a 10-person agency?` | | `ahrefs pricing` | `How much does Ahrefs cost compared to Semrush?` | | `seo tools` | `Which SEO tool should I use if I mostly care about backlinks?` | Three things worth doing before you accept the set: 1. **Cover the whole decision, not just the top of it.** Recomma marks each prompt with a [funnel stage](/concepts#funnel-stage) — awareness asks what exists, consideration compares options, decision is ready to choose. A set that is all awareness tells you about category presence and nothing about whether you win the comparison. 2. **Delete the ones you do not care about.** Every prompt you keep is sampled on every model on every cycle. A set of forty questions you will act on beats two hundred you will not read. 3. **Group them into [topics](/concepts#topic).** A topic is the unit you will later filter the whole Overview by, so it is worth naming them the way your team already talks about the product. Coverage is easy to add later and expensive to unwind: the history you build is per prompt, so deleting one in a month throws away a month of its readings. ## Check the competitors Recomma proposes the brands it saw the models naming next to you, and you can add any it missed. This matters more than it looks: [share of voice](/metrics/share-of-voice) and [position](/metrics/position) are both measured *against this list*. A rival that is not on it does not dilute your share, so the figure reads higher than the market really is. ## Let it sample Each cycle, every tracked prompt is asked on every model you have enabled, and each chat is stored whole. A project runs [daily or weekly](/reference/sampling) — daily if you are working actively on visibility, weekly if you are watching a trend, and the plan sets which of the two you can choose. The Overview will start showing figures after the first pass, but the first pass is not yet a reading. A percentage measured over a handful of chats moves several points on a single one, which is why Recomma shows you the [sample size](/concepts#sample-size) and a [confidence interval](/concepts#confidence-interval) beside every headline figure, and greys the figure out below twenty chats. ## Read the Overview Once the sample is real, the Overview answers five questions at a glance: - **Are we named?** — [Visibility](/metrics/visibility), and its trend against the category leader. - **How much of the conversation is ours?** — [Share of voice](/metrics/share-of-voice), in the Rankings table. - **How is it spoken about?** — [Sentiment](/metrics/sentiment). - **What is the chat built on?** — Top domains, and what kind of evidence they are. - **How much of the market is that?** — the [Market](/metrics/market) panel, once a keyword pool has been built for the project. ## Then go and change something Visibility is a symptom. The cause is which pages the models trust on your subject and whether those pages mention you. [Sources](/product/sources) ranks the sites the chats actually leaned on. [Opportunities](/product/opportunities) narrows that to the ones being trusted on your subject *while saying nothing about you* — the cheapest ground to go and be present on. [Impact](/product/impact) reads the figure back afterwards, so a change you made has a before and an after rather than a hunch. Two of those pages need no chat at all. [Site](/product/site) reads your own pages and says what the markup is missing, and [Keywords](/product/keywords) prices the market your questions are drawn from and says which part of it no question measures yet — that one waits for the first pool build, which runs on the schedule. ## What to read next --- # MCP server Source: https://docs.recomma.ai/reference/mcp Recomma speaks [MCP](https://modelcontextprotocol.io), so an assistant can read your workspace directly: what the models say about your brand, the chats themselves, which sources they lean on, the action queue, and what your category is worth. The interesting half is the last one. An assistant sitting in your own repository can ask which audit rules your site fails, get the pages and the markup to change, and make the change — without you copying anything out of a dashboard. Every tool calls the same procedures this product's own screens call, so a connection sees exactly what the person who made it sees, and nothing from another workspace. Reading is what a connection gets. Writing — proposing questions, pausing them, moving tickets — is a second permission you grant separately, and every write previews before it applies. Nothing can delete, and nothing starts sampling without saying first what it will cost. ## Connect The server lives at `https://api.recomma.ai/mcp`. There are two ways to authenticate, and clients differ in which they prefer. The quickest way in is **Settings → Connect AI** in the app: pick your client — Claude, ChatGPT, VS Code, Claude Code, Codex, Windsurf, Gemini CLI — and it gives you that client's shortest path, a one-click install where there is one. The same page lists every app you have connected and disconnects one at once. ### With your account ```bash claude mcp add --transport http --scope user recomma https://api.recomma.ai/mcp ``` The first call opens a browser, you sign in as normal, and a screen says what is being connected and what it may read. Approving it returns the client to its own callback with a token. The app then appears under **Settings → Connect AI → Connected apps**, where disconnecting it stops its very next call. A token acts as you, in the workspace you last had open in the app. If you belong to several, switch in the app and the connection follows on its next call — there is no separate workspace setting to keep in step. The screen lists what is being asked for. `recomma:read` is what every connection needs and is refused without; `recomma:write` is asked for only by a client that intends to change things, and the screen says so in different words when it is. A token that carries only identity scopes — because a client never asked to read the workspace — is refused with a challenge naming what was missing; a token that may read and calls a tool that writes gets the same kind of challenge naming `recomma:write`, which a client that supports it turns into a second approval rather than a failure. ### With a key For a CI job, an automation like n8n, or any client with no browser to open. Make a key in **Settings → Connect AI → API keys**; the secret is shown once, along with the config to paste it into. ```bash claude mcp add --transport http --scope user recomma https://api.recomma.ai/mcp \ --header "Authorization: Bearer recomma_YOUR_KEY" ``` ```bash export RECOMMA_API_KEY=recomma_YOUR_KEY codex mcp add recomma --url https://api.recomma.ai/mcp \ --bearer-token-env-var RECOMMA_API_KEY ``` A key issued before the product was renamed starts `plinth_` and still works — nothing about it changed but the prefix on new ones, so there is no need to rotate a key that is already in a CI secret. `x-api-key` works too, for clients that spell it that way. A key belongs to one workspace, acts as the person who made it, and stops working the moment it is revoked. A key can only read unless **Allow this key to write** was switched on when it was made. It is off by default, every time: a key is the credential most likely to end up in a log or a pasted snippet, and one that can only read cannot break anything. The keys list marks the ones that can write. ## The tools Every tool takes `brandId`, which comes from `list_brands`. Shares are fractions between 0 and 1, money is US dollars per month, and every rate carries the number of chats it was measured over. | Tool | What it answers | | --- | --- | | `list_brands` | Which brands this connection can see, and their ids | | `get_visibility` | How often the models name you, against your rivals, over a window | | `get_trend` | Which way that is going: a point per day, the window before, and what moved among the sources | | `list_prompts` | The tracked questions, worst first — where you are losing | | `get_prompt` | One question in full: its history, how every rival stands on it, what its answers cite, the latest answer per engine | | `read_answers` | The chats themselves: previews, or one answer in full. `you: "named"` or `"unnamed"` keeps only the answers that named the brand, or only those that did not | | `list_sources` | The sites the chats lean on, and whether they ever name you. `you: "unnamed"` lists only the ones that never do | | `get_source` | One site or one page: which questions reach for it, on which engines, and the page's own words | | `list_actions` | The work queue, ranked | | `get_action` | One ticket with its evidence: the questions it would move, the source's pages, or the rule and the failing markup | | `get_impact` | What the finished work moved: the brand's line, and a verdict per closed ticket | | `get_site_findings` | Which audit rules your own site fails, with the markup to change | | `get_market` | What your category is worth, how much of it you cover, how much names you | | `get_keywords` | The priced keywords behind that figure | | `get_referrals` | The people an assistant actually sent, from your own Google Analytics: sessions and conversions against the window before, the landing pages, and the channels AI can hide in | The `list_*` tools are the tables; each `get_*` beside one is the page a row opens onto. An assistant reads down the same way a person does: the queue, then the ticket; the sources, then the page. `list_brands` also says what the connection was granted — `scopes`, and `canWrite` — so a client can plan around what it may do rather than discover it from a refusal. ### The tools that write Four more, each needing `recomma:write`: | Tool | What it does | | --- | --- | | `create_prompts` | Proposes questions. They land as **Suggested** on the Prompts page; nothing is sampled until a person accepts them | | `set_prompt_status` | Activates or pauses questions. Activating starts sampling, so the preview prices it and refuses the large cases | | `set_action_status` | Moves a ticket: in progress, done, dismissed, back to open. Done freezes the reading the re-measure is judged against | | `suggest_prompts` | Has the product write questions itself — from the priced demand no question reaches, or from the brand — and files them as Suggested | They share three rules: - **Preview first.** Every write tool except `suggest_prompts` previews by default: the answer says what would change and changes nothing. Pass `apply: true` to act. `suggest_prompts` has no preview because the proposals *are* the preview — they wait for a person either way. - **Nothing deletes.** A question is paused, never removed; a ticket is dismissed, never removed; a finished ticket is never re-finished or reopened, because the reading frozen when it was marked done is the one it keeps. Anything destructive is done by a person in the product. - **Spending is said out loud, and capped.** The only write that spends is activating questions. Its preview says how many would start and roughly what that is per week; a call that would take more than half of what the plan has left is refused and sent to a person on the Prompts page, however it is asked. ### Workflows and the glossary A client that lists prompts is offered five ready-made workflows — a weekly brief, diagnosing a drop, how the rivals win, an audit of the prompt set, a site fix plan. Each arrives with the brand filled in and names the tools to call in order and how to read what comes back. Two resources travel with them: `recomma://glossary`, every term the tools use and the field names they use for it, and `recomma://methodology/market`, how the market figures are computed and what they are not. They are the docs pages you are reading, extracted at build time, so the two cannot drift. ### Following a figure down Some questions, and the tools that answer them: | Ask | Tools | | --- | --- | | "What happened to our visibility this month?" | `get_trend` — the daily points, the window before, and the delta only when both are readable | | "Why did we drop on Perplexity?" | `get_trend` with `engine`, then `list_prompts` for the questions that fell, then `read_answers` for what changed | | "Which sites keep getting cited without naming us?" | `list_sources` with `silentOnly`, then `get_source` for who they do name and what the page says | | "Is this ticket worth doing?" | `get_action` — the questions it targets and how you do on each, or the rule and the pages failing it | | "Did the work we finished last month change anything?" | `get_impact` — a verdict per closed ticket, or `pending` with the date it becomes one | | "Does any of this turn into visitors?" | `get_referrals` — sessions an assistant sent and what they did, with `state: disconnected` rather than zeros until a [Google Analytics property is connected](/product/traffic) | ### Reading the answers `read_answers` without a `runId` returns recent chats as previews, each with the brands it named in order, what it cited, and its `runId`. Pass one of those back as `runId` and you get that chat whole — cut at `maxChars`, with `truncated: true` when it was cut, so a shortened answer is never mistaken for a complete one. ### Acting on your own site `get_site_findings` with no `rule` lists every rule the site currently fails and how much of the site has been read. With a `rule` it returns why the rule exists, the pages that fail it, and for each one the markup as it is beside what it should be — which is enough for an assistant to make the change in your repository. ## What the figures mean The tools carry the product's rules with them, and an assistant reading them should carry them too: - **A rate without its sample is not a reading.** Every figure ships with `sampleN`. Below about twenty chats a percentage moves several points on one answer — see [when a figure is a reading](/metrics#when-a-figure-is-a-reading). - **Absent is not zero.** A prompt nothing has sampled has `visibility: null`; a project with no keyword pool gets `state: "missing"` rather than a market worth nothing; a window with no answers in it is `previous: null`, never a row of zeros that reads as a rise from nothing. - **A day is noise; a week is a reading.** `get_trend` and `get_impact` mark each daily point `reliable` or not. Read the direction over a week rather than the gap between two days. - **A verdict that has not been measured is not a verdict.** A ticket in `get_impact` says `pending` or `due` until it has been re-measured. Neither means "no change". - **Nothing is fetched on demand.** `get_source` returns a page's words only when the crawler has already read it, and says so when it has not. - **Money and shares are never multiplied.** `get_market` gives a category value and, separately, the share of it the answers name you in. There is no "value captured" figure, because [being named in an answer is not a click](/metrics/market#how-a-keyword-is-priced). ## Limits Lists are capped and default small — a client's context is the scarce resource, not the database. Every list tool takes `limit` and `offset`, and returns a `page` alongside its rows: ```json { "offset": 0, "limit": 20, "total": 57, "nextOffset": 20 } ``` Pass `nextOffset` back as `offset` for the next page; it is `null` on the last one. `total` is the count the page was drawn from — after any filter the tool applied. The tools return what the screens show rather than an export of everything behind them. Reading spends nothing: the read tools return chats that have already been sampled, and adding a connection does not change what a project costs. Of the write tools, only activating questions spends, and it says so before it does. ## Related --- # Models Source: https://docs.recomma.ai/reference/models Recomma samples five surfaces: | Surface | How it is asked | | --- | --- | | **ChatGPT** | Captured from the interface; the gateway's API as a fallback | | **Gemini** | Captured from the interface; the gateway's API as a fallback | | **Google AI Mode** | Captured from the results page | | **AI Overviews** | Captured from the results page | | **Perplexity** | Its own API, which returns the pages the answer stood on | Four more have a name in the product and are **not sampled**. Their answers are still in the archive, because measurements already taken do not stop being true: | Not sampled | Why | | --- | --- | | **Claude**, **Grok** | Four times the cost of a capture for no more signal, and an API answer is not what a reader was shown | | **DeepSeek** | Sold by the gateway, but no consumer search surface whose citations mean anything for a brand | | **Copilot** | A search surface, so no chat-completion gateway serves it at all | Which are enabled is a per-project choice. Every enabled model is asked every tracked prompt on every cycle, so the model list is one of the two multipliers on what a cycle costs — see [sampling](/reference/sampling). ChatGPT is a model in this sense; `gpt-4o-2024-08-06` is the build that answered on a given day. The first is what you track and filter by, because it is what your buyer opens. The second changes under it without warning and is recorded on each chat so a shift in the numbers can be traced to one. Where both appear — the archive, the CSV export — the surface is `model` and the build is `model_version`. ## Models disagree, a lot The single most common mistake in reading these numbers is treating the all-models figure as *the* figure. It is an average over models that frequently disagree: different retrieval, different training, different willingness to name brands at all. A brand can be named in most ChatGPT chats and almost no Gemini ones. The average is real, but it describes no model anyone actually uses. The model filter on the Overview exists for this. If a figure looks strange, split it by model first — the answer is usually that one model is behaving differently, not that the brand's position changed. ## Fidelity: interface or API How a chat was obtained is recorded on it, and there are two ways: - **Interface** — the model's own product, the way a person sees it. Web search runs, the product's own ranking applies, sources are attached as the product attaches them. - **API** — the build behind the product, called directly. A fallback, used when the interface cannot be reached. These are not the same measurement. ChatGPT the product and the build behind it answer differently, because most of what makes the product's reply is the retrieval and formatting wrapped around it. Interface chats are the truer measurement. API chats are marked as such rather than quietly mixed in, so a figure never rests on an unstated change in what was being asked. ## Failed chats A model that does not reply in time produces a failed chat. These are: - **counted and shown** on the Overview, so you can see how many of the chats asked for actually came back; - **excluded** from the metrics, because there is no text to count; - **retried** on the next pass. A small number is normal. A persistent one against a single model usually means that model is rate-limiting, and the figures for it will be measured over fewer chats — check the [sample size](/concepts#sample-size) when filtered to it. The Overview reports every failure in the window beside the chat count, and explains only the ones still failing. A model that timed out on Monday and has answered since drops off the explanation without changing the count. ## Related --- # How sampling works Source: https://docs.recomma.ai/reference/sampling Every number in Recomma is downstream of one loop. It is worth understanding because it explains both what the figures mean and what the project costs. ## One cycle On each cycle, for every **tracked** prompt, on every **enabled** model: ### Ask The question is put to the model — through its own interface where possible, through the model's API as a fallback. See [fidelity](/reference/models#fidelity-interface-or-api). ### Store the chat whole The text, the brands it named in the order it named them, and every source it cited or read. The chat is kept, not just a score derived from it, which is why every figure can be opened and read back. ### Count [Visibility](/metrics/visibility), [share of voice](/metrics/share-of-voice), [sentiment](/metrics/sentiment) and [position](/metrics/position) are counted from the stored chats and rolled up per day, per model, per market. ## Cadence A project samples **daily** or **weekly**, and the plan sets the ceiling: Starter is weekly, and every plan above it can run daily. - **Daily** while you are actively working on visibility — you want to see a change land. - **Weekly** when you are watching a trend. Four times fewer chats, and a reading that is four times slower to become trustworthy. ## What drives the volume ``` chats per cycle = tracked prompts × enabled models ``` That is the whole formula, and both terms are yours to choose within the plan's limits — Starter and Growth enable at most three of the [surfaces](/reference/models), and the plans above them are uncapped. Forty prompts on three surfaces is 120 chats a cycle; daily, that is about 840 a week. The same forty on all five is 200 a cycle and roughly 1,400 a week. This is why [suggested prompts](/product/prompts#tabs) wait for a person before they start running. Coverage should grow because somebody decided it should. [Sample size](/concepts#sample-size) is what makes a percentage a reading, and it accumulates per prompt over time. Twenty questions sampled daily reach a trustworthy reading far sooner than eighty sampled weekly — and you will actually read twenty. ## From chats to a reading A single chat is a coin flip. The metrics only mean something in aggregate, which is why Recomma is explicit about the aggregate everywhere: - **[Sample size](/concepts#sample-size)** — prompts × models × sampling days in the window. - **[Confidence interval](/concepts#confidence-interval)** — the range the true figure is likely to sit in. - **Below twenty chats**, the figure is greyed out. Not wrong — just moving too much on one chat for a difference between two readings to mean anything. ## What breaks comparison A trend line is only comparable over a period where the measurement did not change. Three things change it: | Change | Effect | | --- | --- | | Adding or removing **prompts** | Moves the visibility baseline — different questions | | Adding or removing **competitors** | Moves share of voice and position — different field | | Enabling or disabling an **model** | Moves everything — different mix of chats | None of these is wrong to do. But expect a step in the line at the point you did it, and do not read that step as the market moving. ## Related