Check which of several prompts/keywords actually cite a specific
domain, and which ones don't. This is usually the first real question
in an AI-answer-engine audit - not "what does a winning answer look
like" (analyze_citation_structure) or "who wins this one topic"
(find_citation_leaders), but "out of everything we care about, where do
we already show up, and where are we invisible." Use this first, then
use analyze_citation_gap on whichever keywords come back not cited to
see what to actually change.
Read-only for the caller, safe to retry. Costs 1 quota unit per keyword
per sample (1 sample by default; free tier is 30 units/month shared
across every metered tool, so up to 30 keyword checks that period if
nothing else is used). A per-keyword provider error doesn't fail the
whole call - that keyword's entry just carries an "error" field instead.
On the hosted endpoint each keyword's result is remembered for 180 days
against your API key, so the next check of the same domain and keyword
reports what changed (see "previous" and "change"); get_check_history
reads that record back for free.
Returns: {"domain", "engine", "samples", "keywords_checked" (int,
excludes any that errored), "keywords_cited" (int), "coverage_pct"
(float, 0-100), "not_cited" (list of the keyword strings where domain
was not cited - the actionable list), "newly_cited" and "no_longer_cited"
(keywords whose status flipped since your last check of them), "results"
(one entry per keyword, in the order given: {"keyword", "cited" (bool:
cited in at least half of the samples), "cited_runs" (how many sampled
answers cited it), "samples_ok" (how many answers came back), "rank"
(int|null, best 1-based position among the answers' sources, null when
never cited), "num_sources_cited", "source_domains" (who IS cited, for a
keyword you are not in), "source_mix" (how much of that is community
sites such as Reddit, YouTube, X - where to get discussed to close the
gap), "source_frequency" (only with samples above 1: {"domain", "runs"}
per domain), "leads_with_list", "opening_word_count", "mentioned" (bool -
the answer's text names the domain or brand in at least half of the
samples, whether or not it links to it), "model", "checked_at",
"previous" ({"checked_at", "cited_runs", "samples", "best_rank"} from
your last check of this domain and keyword on the same engine and
market with the same number of samples, or null), "change" ("first_check", "up", "down" or "same",
comparing citation rates)}, or {"keyword", "error"} for one that
failed), "keywords_mentioned" (int), "mentioned_not_cited" (keywords
where the answer names you but does not cite you - the model already
knows you, it just isn't linking you), "mention_terms" (exactly what was
looked for in the answer text)}. "Cited" and "mentioned" are separate
claims and are never merged. Answers change from run to run: with
samples=1 a single answer decides "cited", so use samples=3 before
telling someone they are or are not cited.
Args:
domain: bare domain to check, e.g. "example.com" (no https://, no www).
keywords: prompts/topics to check it against, e.g.
["best project management software", "asana alternatives",
"free project management tool"]. Max 10.
brand: optional brand name to look for in the answer text, e.g.
"Notion". Without it, the domain's first label is used ("notion"
for notion.so), which can match an ordinary word by accident for
a dictionary-word domain, so pass the real brand when known.
country: market to read the answers in, e.g. "Italy". Defaults to
"United States".
language: language code, e.g. "it". Defaults to "en". Write the
keywords in that language too.
engine: "chat_gpt" (default), "gemini" or "perplexity", as in
analyze_citation_structure.
samples: independent answers to read per keyword, 1 to 5. Default 1.