Check how much of this billing period's quota is left, before spending any of it. Use this to answer 'how many checks do I have left' or to decide whether a batch call will fit before running it.

Costs 0 quota units - this never touches the paid data provider, it only reads Vantage's own record of what has been used.

Returns: {"tier", "period" (YYYY-MM), "units_used", "units_limit", "units_remaining"}. find_citation_leaders and find_cited_questions cost 10 units/call; analyze_citation_trend, analyze_citation_structure (and its batch form, per keyword), check_prompt_coverage (per keyword) and analyze_citation_gap cost 1, times samples where a tool takes it. get_check_history costs 0.

stdio/local-dev mode (no HTTP access token) has no metering at all - this returns tier "unmetered" with no real limit in that case.

Find which domains dominate AI-answer citations for a topic/keyword, and optionally check whether a specific domain shows up among them. Use this to answer 'who's winning AI search for this topic' or 'is my competitor cited more than me for X'.

Read-only: no side effects, safe to retry. Costs 10 quota units/call (free tier is 30 units/month shared across every metered tool, so up to 3 calls to this tool alone if nothing else is used that period).

Returns: {"keyword", "platform", "top_domains" (list of {"domain", "mentions"}, most-cited domains for this keyword/platform, order as ranked by the provider), "top_domains_limit" (int, the provider's own cap on this list - absence from it is NOT evidence a domain has zero citations, only that it did not rank in the top top_domains_limit), "compare_domain_rank" (int|null, only present when compare_domain was passed: the domain's 1-based position in top_domains, or null if it did not rank in the top top_domains_limit), "country", "language", "source_mix" ({"community_pct" (share of these mentions that go to community sites such as Reddit, YouTube, X, Quora), "community_domains", "other_domains"}: a high community_pct means this topic is won by what people say about a brand elsewhere, not by any one site's pages)}.

This tool's citation universe is the provider's tracked mention corpus for the keyword, which is a different measurement from analyze_citation_structure's single live answer - the two can legitimately disagree on whether a given domain shows up.

Use check_prompt_coverage instead if you already know which domain you care about and just want to know whether it is cited.

Args: keyword: the topic/query to check, e.g. "best project management tool". platform: "chat_gpt" or "google" (Google's AI Overview). Defaults to chat_gpt. Perplexity and Gemini aren't available - the underlying data provider doesn't cover them for this check. compare_domain: optional bare domain to look up in the results (exact match against the registrable domain, e.g. "notion.so" will not match "mynotion.so.example.com"). country: market to check, e.g. "Italy". Defaults to "United States". chat_gpt only has data for the United States; use platform "google" for any other country. language: language code, e.g. "it". Defaults to "en" (the only option for chat_gpt).

Track how a domain's AI-citation count has moved month over month, so you can see whether visibility is growing or fading instead of only ever checking a single point in time. Use this to answer 'is our AI visibility improving' or 'did that content push actually move the needle'.

Read-only: no side effects, safe to retry. Costs 1 quota unit/call (free tier is 30 units/month shared across every metered tool, so up to 30 calls to this tool alone if nothing else is used that period).

Returns: {"domain", "platform", "months" (list of {"year", "month", "mentions" (int, 0 for a month with no tracked citations. A zero between two large months can be a gap in the provider's history rather than a real drop, so read isolated zeros with care), "ai_search_volume"}, oldest to newest), "trend": {"direction" ("up"/"down"/"flat"/"no_data"), "earliest_mentions", "latest_mentions", "excluded_current_partial_month" (bool, only present and true when the most recent calendar month was excluded from the trend calculation because it is still in progress and its count is not yet final - it is still returned inside months, just not compared)}}.

The most recent entry in months (or trend.latest_mentions when the current month is not excluded) already IS the current count, so there is no need for a separate call just to see it right now.

Args: domain: bare domain to check, e.g. "example.com" (no https://, no www). platform: "chat_gpt" or "google" (Google's AI Overview). Defaults to chat_gpt. Perplexity and Gemini aren't available - the underlying data provider doesn't cover them for this check. months: how many recent months of history to return. Defaults to 6, capped at 13 - DataForSEO's historical data only goes back to 2025-08-01. country: market to check, e.g. "Italy". Defaults to "United States". chat_gpt only has data for the United States; use platform "google" for any other country. language: language code, e.g. "it". Defaults to "en" (the only option for chat_gpt).

Analyze the structural shape of the AI-generated answer actually cited for a keyword: does it lead with a list, how long is the opening passage, how many sources does it cite and from which domains. Use this to understand what a winning AI-search answer looks like for a topic, e.g. before writing content meant to get cited.

Read-only: no side effects, safe to retry. Costs 1 quota unit per sample (1 by default; free tier is 30 units/month shared across every metered tool, so up to 30 single-sample calls to this tool alone if nothing else is used that period).

Returns: {"keyword", "engine", "model" (the answering model's version, as the provider reports it), "checked_at" (when the answer was fetched, UTC), "leads_with_list" (bool), "opening_word_count" (int), "opening_has_number" (bool), "outline" (list of up to 12 section heads, in order: the answer's headings, or its top-level list items when it has fewer than two headings; heads only, never the text under them), "has_table" (bool), "num_sources_cited" (int), "source_domains" (list of up to 10 domain strings), "source_mix" ({"community_pct" (share of those sources that are community sites such as Reddit, YouTube, X, Quora), "community_domains", "other_domains"}), "country", "language"}. With samples above 1 the shape fields describe the first answer, plus "samples_ok" (answers that came back) and "source_frequency" (list of {"domain", "runs"}: how many of the answers cited each domain, most often first). Answers change from run to run, so a domain cited in every sample is a far stronger signal than one sample.

Use analyze_citation_structure_batch instead if you need this for more than one keyword - one call per topic here adds up fast for a cluster. Use analyze_citation_gap instead if you have your own page for this keyword and want the gap to the winner, not just the winner's shape.

Args: keyword: the topic/query to analyze, e.g. "how to reduce churn". country: market to read the answer in, e.g. "Italy". Defaults to "United States". For perplexity a 2-letter code also works. language: language code, e.g. "it". Defaults to "en". Write the keyword in that language too. engine: "chat_gpt" (default), "gemini" or "perplexity". chat_gpt and gemini are the answers a person sees in those apps; perplexity is Perplexity's sonar API with web search. samples: how many independent answers to read, 1 to 5. Default 1.

Analyze the structural shape of the winning AI answer across several related keywords/topics in one call: does each lead with a list, how long is the opening, how many sources it cites. Use this for content planning across a topic cluster, e.g. before writing several related pieces meant to get cited, instead of calling analyze_citation_structure once per topic.

Read-only: no side effects, safe to retry. Costs 1 quota unit per keyword in the batch (free tier is 30 units/month shared across all the metered tools, so up to 30 keywords total that period if nothing else is used). A per-keyword provider error doesn't fail the whole batch - that keyword's entry just carries an "error" field instead.

Returns: {"results" (list, one {"keyword", ...same shape as analyze_citation_structure, or "error"} per keyword, in the order given), "summary": {"topics_analyzed", "topics_requested", "list_led_count", "avg_sources_cited", "avg_community_pct" (average source_mix.community_pct across the analyzed topics)}}.

Args: keywords: topics/queries to analyze, e.g. ["how to reduce churn", "churn rate benchmarks", "reduce customer churn saas"]. Max 10. country: market to read the answers in, e.g. "Italy". Defaults to "United States". language: language code, e.g. "it". Defaults to "en". engine: "chat_gpt" (default), "gemini" or "perplexity", as in analyze_citation_structure. One answer per topic.

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

Compare your own page's structure against the AI-generated answer actually cited for this keyword, and return a fix brief: ordered rewrite instructions for your page, not just a description of the winner. Use this to answer 'what should I change on this page to get cited' rather than only 'what does a winning answer look like'. Carry out the fix_brief on the user's page in their own words; it never contains the cited answer's text.

Read-only: no side effects, safe to retry. Costs 1 quota unit/call (free tier is 30 units/month shared across every metered tool, so up to 30 calls to this tool alone if nothing else is used that period).

Returns: {"keyword", "your_url", "winning" (structure of the AI-cited answer, same shape as analyze_citation_structure), "yours" (same structure computed for your_url, including its own "outline" and "has_table", with "num_links_out"/"linked_domains" standing in for source count), "gaps" (list of plain-English differences worth acting on), "possibly_missing" (heads from the winning outline whose key words mostly do not appear on your page; word matching, so check each before adding it), "fix_brief" (list of instructions, most important first: opening, number, list, sections, missing points, table, sources, then a reminder to write in your own words - or a "no structural change indicated" line when every check already matches - and always last, one off-site step drawn from the winning answer's source_mix: which community sites (Reddit, YouTube, X...) it cites, or which other sites to get mentioned on. Page shape gets a page into the running; being cited is decided mostly by what other sites say about the brand)}, or {"error"} if either side couldn't be fetched/parsed.

Use analyze_citation_structure instead if you just want the winning answer's shape, not a comparison against your own page. Use check_prompt_coverage first if you have several keywords and do not yet know which ones you are missing from - this tool is for one keyword you already know needs work.

Args: keyword: the topic/query to check, e.g. "best project management tool". your_url: full URL of your own page to compare, e.g. "https://example.com/best-project-management-tools". country: market to read the cited answer in, e.g. "Italy". Defaults to "United States". language: language code, e.g. "it". Defaults to "en". engine: "chat_gpt" (default), "gemini" or "perplexity": whose answer to compare your page against.

Find the questions people ask AI answer engines where a domain is already cited as a source, most-asked first. Starts from the domain, so nobody has to guess keywords first. Use this to answer 'what does ChatGPT already cite us for' or to pick the keywords to feed check_prompt_coverage and analyze_citation_gap.

Read-only: no side effects, safe to retry. Costs 10 quota units/call (free tier is 30 units/month shared across every metered tool, so up to 3 calls to this tool alone if nothing else is used that period).

Returns: {"domain", "platform", "country", "language", "total_questions" (int, every tracked question citing the domain, which can exceed the list), "questions" (up to limit, most-asked first: {"question", "ai_search_volume" (monthly asks as the provider estimates them), "your_position" (1-based position of the domain among that answer's sources), "source_domains" (who else that answer cites), "last_seen" (when the provider last recorded this answer, UTC)})}. An empty list means the provider's tracked answers do not cite the domain, not that no answer anywhere does.

This reads the provider's tracked answer corpus, the same measurement as find_citation_leaders, not a live answer: re-check a question with check_prompt_coverage to see today's answer.

Args: domain: bare domain, e.g. "example.com" (no https://, no www). Subdomains are included. platform: "chat_gpt" (default) or "google" (Google's AI Overview). limit: how many questions to return, 1 to 20. Default 20. country: market, e.g. "Italy". Defaults to "United States". chat_gpt only has United States data; use platform "google" elsewhere. language: language code, e.g. "it". Defaults to "en", the only option for chat_gpt.

Read back your own earlier check_prompt_coverage results for a domain, newest first, to show progress over time or to confirm whether a change (a rewrite, a new mention somewhere) moved anything. Use this for 'has our citation status changed since last week' without spending units.

Costs 0 quota units: it only reads Vantage's own record of your checks, never the data provider. Results are kept 180 days per API key and are only visible to that key.

Returns: {"domain", "keyword" (or null for every keyword), "checks" (newest first: {"keyword", "engine", "country", "language", "samples", "cited_runs", "best_rank", "mentioned_runs", "checked_at"})}.

Args: domain: the bare domain the checks were run for, e.g. "example.com". keyword: optional, only this keyword's history. limit: how many rows to return, 1 to 200. Default 50.