Skip to main content
Whether you’re evaluating Bluemoon for the first time or troubleshooting a specific behaviour, the questions below cover the most common things customers ask. Measurement questions come first, then the Agent Edge Network. If you’re just getting started on the edge side, the Edge Network overview walks through the full install.

​
Measurement

Every active tracked question is asked once a day, on each platform your plan covers. The day’s sweep starts at the time your workspace picks in Settings → Daily scan time (UTC), so you choose when the fresh answers land.Daily is a deliberate choice, not a throttle. An answer engine’s answer to a stationary question does not meaningfully change every few hours, so more frequent sweeps buy freshness nobody can perceive while multiplying the cost of every poll.If you need a fresh read sooner — you’ve just published something, or you’re validating a change — a workspace admin can trigger one with Run scan. The first answers are on screen within about 15 seconds, badged Preliminary: an instant answer from the platform’s own API, which the full collected answer replaces in place within about two minutes. Scores and the intent classification follow within about two minutes of each answer landing.
First check whether the platform is included in your plan at all — open Settings → Billing to see the platform count your plan covers, and Settings → scan configuration for the per-platform status. A platform your plan does not cover is never polled, so it will show nothing rather than an error.If it is included, then something went wrong on that poll. Bluemoon never writes a blank or invented answer to fill a gap: when a platform cannot be reached for a question, it records a failure with a reason instead, and that failure is visible per platform in Scan history.The reasons you’re most likely to see:
  • No AI Overview shown for these queries — Google did not render an AI Overview for that query. That is a real observation about the query, not an error.
  • Rate limit or quota reached / Too many parallel requests — the provider throttled the request.
  • Missing or invalid credentials or Account credit exhausted — a provider account problem, surfaced rather than hidden.
  • Source timed out — the poll will be retried on the next scan.
  • No fallback available for this platform — the primary source failed and this platform has no second route.
A failed poll is excluded from your rates entirely. It is not counted as a poll, and it is not counted as a miss — so a bad day on one platform cannot silently depress your visibility number.
A dash means not measured. Zero means measured, and you were not mentioned. They are different findings and Bluemoon never renders one as the other.You will see a dash when:
  • A commercial reach figure has no weight behind it, because every question in the slice sits in the ballast tier. There is no commercial signal to report, so the tile is omitted rather than showing 0%.
  • A question-shape rate has no question that clears the minimum of three recorded answers. A question polled once contributes a rate of exactly 0% or 100% — a coin flip wearing a percentage sign — so it is held out until it can disagree with itself.
  • A “core topics only” column exists for a shape you track no core-topic question of. Bluemoon cannot answer that question for that shape, which is not the same as answering zero.
  • Commercial reach has no commercial weight behind it — every question in the slice is peripheral calibration ballast. That slice carries no commercial signal; it is not 0% commercial visibility.
There is a third case worth knowing: a rate that is measured, non-zero, and would round to 0.0% is displayed as <0.1%. A measured handful of mentions is not the same finding as none at all.Finally, on the question-shape rates, answers that were recorded but not yet scored are excluded from both the numerator and the denominator. An unscored answer is not evidence of absence.
No. It is a weighting and prioritisation signal, and it should not be read as a forecast.This was measured rather than assumed. Across classified questions on several production domains over 90 days, commercial intent does correlate with visibility when you look at the whole library — but once the topic tier is held constant, the correlation collapses to something indistinguishable from nothing. Almost all of the apparent relationship is the tier speaking through the score. Inside a single tier, a question scored 80 is not more likely to mention you than one scored 30.What the score is genuinely good for is deciding what to work on first: it tells you which questions sit closest to a buying decision, and it labels its own evidence — ad prices (percentile-ranked Google Ads competition for the extracted keyword), read from the question (an LLM’s coarse 0–5 read of the wording), or topic estimate (the weakest fallback). Those are never mixed in the interface, because a number anchored on what advertisers actually pay and a number guessed from phrasing are not the same kind of claim.The axis that does survive the tier control is question shape. Best-of lists and comparison questions name brands; how-to questions explain a process instead. That difference holds inside a single tier, which is why it is the axis Bluemoon points you at.
Because the sample is too thin to support a claim, and saying so is the honest answer.When you mark an action done, Bluemoon snapshots a before picture: the mention rate over the trailing 21 days for the questions that action targets, plus the same rate for a control cohort made of your other topics. Later it recomputes both over an equivalent trailing window and reports the difference in differences — how much the targeted questions moved, net of how much your domain moved anyway — with a Wilson confidence interval and a two-proportion significance test.The status you see reflects what the arithmetic can actually support:
  • Not enough data — fewer than 8 recorded answers on the targeted questions in either the before or the after window. A lift computed on three polls is noise, and reporting it would be worse than reporting nothing.
  • Measuring — there is enough data, but fewer than 14 days have elapsed since completion. The number is shown, with the day count, and is not yet called measured.
  • Measured — the threshold and the elapsed time are both met.
Alongside the statistical layer there are two fast directional signals that do not need the same sample size: whether a page you listed for the action started being cited after completion, and whether your brand got its first mention on a platform that was previously blind. Those are flags, not proof of cause.If an action stays at “not enough data” indefinitely, it usually means the targeted questions are rarely polled — a topic with very few active questions, for example. The before-window is frozen at the moment you marked the action Done and is never recomputed, so adding questions now will not rescue that action — it makes the next one measurable.
Bluemoon polls ChatGPT, Perplexity, Claude, Gemini, Google AI Overview, Google AI Mode, and Microsoft Copilot. Which of them run for your account is set by your plan, so a platform you don’t see in your breakdowns may simply not be included — check Settings → Billing for your plan’s platform count before treating it as a failure.Every recorded answer is scanned for your brand and for each tracked competitor, and classified as:
  • DIRECT — your domain, or one of your exact brand spellings, appears in the answer. This is the unambiguous case and carries full weight.
  • IMPLICIT — no exact spelling matched, but a token derived from your brand or domain did. The match is weaker, so it carries reduced weight in the GEO score.
  • ABSENT — nothing matched.
Your mention rate counts DIRECT and IMPLICIT together, over the answers that were actually recorded and scored. Keeping the two classes distinct is what lets you tell a confident match from a partial one instead of collapsing both into a single yes.Brand spellings matter here. Aliases are seeded automatically from your domain and brand name at setup, and you can add more — an abbreviation, a legal entity name, a localised spelling — so that a real mention is not scored as a partial one.One detail worth knowing about the competitive comparison: questions whose text contains your own brand are excluded from it. An AI asked directly about your brand will name your brand, so leaving those in would inflate your rate against competitors who were never asked about by name. They remain visible in the per-question breakdown; they just don’t count toward the headline comparison.
Not with certainty, and it will not pretend otherwise. Bluemoon measures what the AI said, not why it said it. It has no visibility into a model’s retrieval or ranking, and it does not know whether you publish content for a given question shape.What it gives you instead is the evidence to reason from: the recorded answers behind each tracked question, which competitors were named in them, which URLs were cited, and how the pattern breaks down by platform, topic, persona, and question shape. When best-of-list questions in your core topics almost never name you, that is a measured fact and a clear place to look. The causal step is yours to make, from answers you can read.

​
Agent Edge Network

Work through these in order:
  1. Is AEN_EDGE_TOKEN set as a Vercel environment variable? A local .env file is not enough. If the token is blank, the middleware returns NextResponse.next() on the very first line and does nothing — no detection, no telemetry.
  2. Is the middleware actually deployed? Confirm middleware.ts is at the root of your Next.js app and shows up as an Edge Function in your Vercel project’s Functions tab.
  3. Did you trigger a real browsing AI? Visiting your own site in a browser won’t generate a hit. You need to ask ChatGPT or Perplexity (with browsing enabled) a question that causes their crawler to fetch a URL on your domain.
Note on verification: the drop-in middleware records telemetry for any matched answer-engine agent, but only verified hits are ever served the optimized variant. A bot that matches by user-agent string alone — but whose source IP isn’t inside the vendor’s published CIDR ranges — is classified as UA_ONLY and is always passed through to your normal page.
In the drop-in middleware, every one of these must be true before the variant is served:
  1. The bot must be verified. The middleware verifies the request’s source IP against the vendor’s published CIDR ranges (IP_VERIFIED). A UA_ONLY match is never served the variant.
  2. The bot’s purpose class must be USER_TRIGGERED or RETRIEVAL. Other purpose classes pass through, even when the bot is verified.
  3. SERVE_MODE must be "default". The middleware ships in "shadow", which logs requests but always serves your normal page. Change the constant in middleware.ts to "default" and redeploy.
  4. An artifact must exist for the URL. If Bluemoon hasn’t generated one yet, the middleware degrades to your normal page — it never fabricates a response.
Separately, classic search bots (Googlebot / Bingbot / Applebot) are always passed through by the cloaking firewall, no matter what — see the SEO question below.
Yes — and this is enforced in code, not left to configuration. The serve rule contains an explicit cloaking firewall: if an incoming bot is flagged isSearchIndex in the Bluemoon botset, the middleware immediately returns your normal page without branching. Googlebot, Bingbot, and Applebot always get your normal page, full stop. The control plane also strips SEARCH_INDEX from a site’s enabled purposes defensively, so it can never be turned on.This matters especially because Google’s AI Overviews run on Googlebot and the same search index as Google Search. Serving Googlebot a different version would be cloaking Google Search itself — a clear policy violation. Bluemoon never does this.For the non-search answer-engine agents that Bluemoon does serve (such as OAI-SearchBot, Claude-SearchBot, and PerplexityBot), the artifact is a pure extraction-and-restructure of your existing page — the same substance, reformatted into answer-first markdown and JSON-LD. A strict-parity grounding guardrail rejects any artifact that introduces content the source page didn’t contain, so nothing is added or invented.See the cloaking firewall guide for the full rule.
Yes. Besides the Next.js edge middleware, there are drop-ins for Cloudflare Workers and WordPress / PHP, plus a custom integration with copy-paste snippets for any other stack. A zero-code CNAME reverse-proxy is on the roadmap and not yet available. Reach out via in-app chat to discuss your stack.
The edge token (AEN_EDGE_TOKEN) is a separate, site-scoped credential, distinct from your Bluemoon account credentials. It has the format aen_..., is scoped to exactly one domain, and can be rotated at any time — re-provisioning the site mints a fresh token without affecting the rest of your account.Its job is to authenticate the middleware’s calls to the Bluemoon control plane (Authorization: Bearer <edgeToken>): fetching the botset, fetching artifacts, and posting telemetry hits. Because it’s site-scoped and revocable, the blast radius of a leaked token is limited to that one site’s edge configuration.The token is returned in full only once, at provision time, so copy it straight into Vercel’s environment variable store rather than committing it to your repository. If you lose it, re-provision the site to mint a new one.
Shadow mode (SERVE_MODE = "shadow") is the default in the downloadable middleware.ts. In this mode the middleware runs the full detection and verification pipeline on every request and logs what it would have served, but always delivers your normal page to every visitor — human or bot.Starting in shadow mode lets you confirm that:
  • The middleware is deployed and receiving requests.
  • AEN_EDGE_TOKEN is set and the control plane is reachable.
  • Verified AI crawler hits are appearing in Agent Analytics.
  • The artifacts Bluemoon has generated look right — the Agent Analytics artifacts list shows each optimized page with its status and citability score.
Once you’re satisfied, flip the constant to "default" and redeploy to start serving the variant. The middleware.ts constant only accepts "shadow" or "default"; richer serve modes such as canary rollouts are configured from the Bluemoon platform (off / shadow / canary:<pct> / default).
Bluemoon maintains a botset — a list of known AI agents with their user-agent tokens, published IP CIDR ranges, and a purpose classification. The middleware fetches it from the control plane and caches it on the edge for up to one hour.Tracked agents include:
  • OpenAI: ChatGPT-User (USER_TRIGGERED), OAI-SearchBot (RETRIEVAL), GPTBot (TRAINING)
  • Anthropic: Claude-User (USER_TRIGGERED), Claude-SearchBot (RETRIEVAL), ClaudeBot (TRAINING)
  • Perplexity: Perplexity-User (USER_TRIGGERED), PerplexityBot (RETRIEVAL)
  • Mistral: MistralAI-User (USER_TRIGGERED)
  • Classic search (firewall-protected, never served): Googlebot, Bingbot, Applebot
Detection matches the request’s user-agent token against the botset, then verifies the source IP against the vendor’s published CIDR ranges. A match on user-agent alone yields UA_ONLY, which is never served the variant; IP confirmation yields IP_VERIFIED. The core also defines a higher SIGNED tier backed by Web Bot Auth (RFC 9421 HTTP Message Signatures, Ed25519); the shipped drop-in verifies by IP range.Bluemoon maintains the botset centrally, so you don’t need to track vendor crawler tokens or IP ranges yourself.
Every bot in the botset carries a purpose class describing why it’s crawling:
  • USER_TRIGGERED — A human is actively waiting. When a ChatGPT user asks a question with browsing enabled, ChatGPT-User fetches your page in real time to inform the answer.
  • RETRIEVAL — The crawler is building or refreshing an index for future queries. OAI-SearchBot and PerplexityBot fall here.
Both classes are enabled for variant serving by default. Other classes are not served:
  • TRAINING crawlers (e.g. GPTBot, ClaudeBot, CCBot) pass through to your normal page.
  • SEARCH_INDEX bots (Googlebot / Bingbot / Applebot) always pass through via the cloaking firewall.
You control which purposes are eligible per site (SEARCH_INDEX can never be enabled).
No — for human visitors there is no perceptible latency. The overwhelming majority of your traffic is human, and if no bot user-agent is matched the middleware calls NextResponse.next() and steps aside immediately.For a verified AI crawler request the middleware does a little extra work: it fetches the pre-generated artifact from the control plane. This is completely separate from any human session. The botset is cached on the edge for up to one hour, so that lookup does not hit the control plane on every request.
Bluemoon never puts an LLM call on the request path. Artifacts are generated offline — pure extraction-and-restructure of your existing page — and cached, so serving one is just a fetch, never a model round-trip.
Artifacts are built from a snapshot of your page content, so editing your page does not automatically rebuild them.To refresh one:
  1. Open Agent Analytics in the Bluemoon app.
  2. Find the page you’ve edited.
  3. Use the Regenerate action, which flags the artifact stale so the engine rebuilds it from your page’s current content.
Because the drop-in middleware fetches artifacts per request from the control plane (it keeps no local edge cache), the rebuilt version is served to the next qualifying crawler with no redeploy on your side. While a page is queued for regeneration its status shows as stale and the edge passes crawlers through to your normal page until the engine rebuilds it back to fresh — you can watch that status flip (and the updated citability score) in the artifacts list. See the Agent Analytics guide for the served → cited loop.