Skip to main content
v1.0GuidesGuidesAPI ReferenceAPI Reference

AI Visibility Server

Analyze how your brand appears in AI-generated answers across ChatGPT, Perplexity, Gemini, and more: ranking position, visibility rate, competitor share-of-voice, sentiment, the sources LLMs cite, and how AI crawlers and AI platforms interact with your own website pages.

Overview​

The AI Visibility Server exposes data about how a tracked brand shows up in the answers of LLM platforms (ChatGPT, Perplexity, Gemini, etc.). It covers brands, the platforms they're tracked on, the prompts tracked against them, individual LLM executions ("chats"), competitor rankings, the sources LLMs cite, and the pages of the brand's own website.

Server Details​

  • Server Name: ai-visibility-server
  • Version: 0.0.1
  • Endpoint: POST https://ask.sonalabs.com/mcp/ai-visibility
  • Transport: Streamable HTTP
  • Authentication: x-api-key header with your organization's Ask Your Data API Key. Other organization API keys are not accepted by the MCP server.
  • Scoping: All data is automatically scoped to the organization that owns the API key.

Purpose​

Answer questions about brand visibility in AI answers: ranking position and visibility rate per brand, competitor share-of-voice, sentiment of mentions, and which sources/domains influence what LLMs say.

Data Model​

  • Brands: the companies being tracked. Each brand has topics, and each topic has prompts.
  • Prompts: the questions asked to LLM platforms to measure brand visibility. A prompt can have fan-outs: sub-queries generated from it.
  • Platforms: the LLMs a brand is tracked on (e.g. ChatGPT, Gemini, Google AI Overview). They differ per brand, and their IDs are the llmProvider values the other tools filter by.
  • Chats: a single execution of a prompt against an LLM platform. Records the full LLM response, the brand's ranking position, the sub-brands mentioned with sentiment, and the sources cited.
  • Ranking position: the MAIN brand's position in a chat's answer. > 0 = mentioned at that rank (1 is best), 0 = not mentioned. Brand visibility = percentage of completed chats with position > 0.
  • Entities (sub-brands): the companies/products detected in LLM responses: the tracked brand itself (isMain) and its competitors (isWatched). This is the same data as the Rankings page in Sona.
  • Sources: URLs the LLM cited in a chat, classified by source type (corporate, editorial, UGC, reference, institutional, other).
  • Domains: cited page URLs rolled up to the site/domain level.
  • Site pages: the pages of the brand's own website (the Site Pages page in Sona), with AI crawler visits, visitors referred by AI platforms, a technical audit score, and the tracked keywords each page covers. Not the same as sources, which are what AI answers cite. Watched pages are the ones the brand monitors and audits; the rest were discovered on the site.
  1. Call Brands List to discover the organization's brands and get a brandId.
  2. Call Platforms List if you need to filter by platform. Use the returned IDs as llmProvider; never guess them.
  3. Call Entity List for competitor, rankings/leaderboard, and share-of-voice questions.
  4. Call Prompts List to find prompts for that brand (filter by topic, status, buying stage, metrics, or search text).
  5. Call Chats List to find LLM executions of a prompt, then Chat Detail to read the full response, mentions, and cited sources for one chat.
  6. For citation analysis (which sites influence AI answers), call Source Types List, then Sources List or Domain List.
  7. For questions about the brand's own website pages (AI crawler visits, AI-referred traffic, audit score and fixes, keyword coverage), call Site Pages List.

Every tool returns a formatted Markdown table with a one-line explanatory note underneath, so responses render directly in the assistant's answer without extra formatting work.

Available Tools​

1. brands-list-tool​

Purpose: List every tracked brand for the organization.

Input: None required.

Returns: id, name, URL, LLM providers tracked, topic count, prompt count.

When to use: Call this first in any AI Visibility conversation. Its id feeds every other tool.

2. platforms-list-tool​

Purpose: List the AI platforms currently enabled for a brand.

Input: brandId (required).

Returns: platform id and name (e.g. chatgpt / ChatGPT).

When to use: Before filtering by platform. The id is the llmProvider value for prompts-list-tool and chats-list-tool. Platform IDs differ per brand, so don't assume chatgpt/gemini/perplexity.

3. entity-list-tool​

Purpose: Rank the main brand and its competitors by performance (the same data as the Rankings page in Sona).

Input:

  • brandId (required)
  • startDate/endDate, topicId, tagId, promptId, isWatched, search, minVisibility/maxVisibility, minSentiment/maxSentiment, minShareOfVoice/maxShareOfVoice, limit (optional)

Returns: mentions, visibility, position rank, share of voice, sentiment, and previous-period sentiment for each entity.

When to use: Competitor, leaderboard, and share-of-voice questions such as "what is our SOV?". Don't compute share of voice from chats; use this tool.

4. prompts-list-tool​

Purpose: List prompts (questions) tracked for a brand.

Input:

  • brandId (required)
  • topicId, tagId, status (active/archived/suggested), buyingStage, llmProvider, llmModel, volumeCompetition, mentionsSubBrandId, search, includeFanouts, parentId, minVisibility/maxVisibility, minPosition/maxPosition, minSov/maxSov, createdFrom/createdTo, rankedFrom/rankedTo, limit/offset (optional)

Returns: id, prompt text, topic, status, buying stage, visibility, position, share of voice, tags, fan-out count, created date.

5. chats-list-tool​

Purpose: List LLM executions ("chats") of prompts for a brand.

Input:

  • brandId (required)
  • promptId, topicId, tagId, llmProvider, llmModel, rankedFrom/rankedTo, minRankingPosition/maxRankingPosition, limit/offset (optional)

Returns: chat id, prompt, brand, provider, model, ranking position, ranked-at date.

Key concept: ranking_position is the MAIN brand's position, not a sub-brand's. > 0 = mentioned (1 = best), 0 = not mentioned. Use minRankingPosition=1 for chats that mention the brand only, or maxRankingPosition=0 for chats that don't.

6. chat-detail-tool​

Purpose: Get full detail of a single chat.

Input: chatId (required).

Returns: prompt text, LLM provider/model, ranking position, the full LLM response output, sub-brand mentions (position, sentiment score, sentiment keywords), and cited sources.

7. source-types-list-tool​

Purpose: List the source type taxonomy (corporate, editorial, UGC, reference, institutional, plus org-specific types).

Input: brandId (required).

Returns: id, name, scope, count of cited sources for the brand.

8. sources-list-tool​

Purpose: List cited sources, grouped by the entity each cited site belongs to.

Input:

  • brandId (required)
  • startDate/endDate, isMainMentioned, limit/offset (optional)

Returns: name, URL, domain type, retrieved %, citation rate, whether the main brand is mentioned, and other entities mentioned.

When to use: General citation analysis: "Which sites influence our AI visibility?"

9. domain-list-tool​

Purpose: List the same citations framed as domains.

Input: same as sources-list-tool. brandId required; startDate/endDate, isMainMentioned, limit/offset optional.

Returns: sub-brand id, domain, name, domain type, retrieved %, citation rate, whether the main brand is mentioned.

When to use: When the question is specifically about domains/sites ("top cited sites").

note

sources-list-tool and domain-list-tool read the same citation data and take the same filters. Use sources-list-tool for general citation analysis, and domain-list-tool when the question is specifically about domains or sites.

10. site-pages-list-tool​

Purpose: List the pages of the brand's own website (the same data as the Site Pages page in Sona).

Input:

  • brandId (required)
  • startDate/endDate (both or neither), search (URL, path, or title), watched (true/false), orderBy/orderDir, includeSuggestions, limit (max 100)/offset (rounded down to a multiple of limit) (optional)

Returns: page ID, URL, title, watched, HTTP status, audit score (0-100; empty = not audited yet), AI indexed (AI crawler visits), people referred (human visits referred by AI platforms), total and traditional referrals, bot referral % (people referred / AI indexed), Google search volume, and the tracked keywords the page covers. With includeSuggestions, also each page's latest audit issues and suggested fixes. Stats cover startDate–endDate, or all history when omitted.

When to use: Questions about your own pages, such as "which of our pages do AI bots crawl most?" or "which pages have the lowest audit score?". Sort by totalIndexed desc for the most AI-crawled pages, or pageScore asc for the weakest pages. For sites that AI answers cite, use sources-list-tool or domain-list-tool instead.

Notes​

  • All data is automatically scoped to the authenticated organization.
  • Free-text search params use contains-match by default; only exact-match when explicitly requested.
  • Dates are always YYYY-MM-DD.
  • Platform IDs differ per brand. Get them from platforms-list-tool rather than assuming chatgpt/gemini/perplexity.

Connecting a Client​

The AI Visibility Server is a remote HTTP MCP server. See the Claude Integration guide to connect it to Claude Code, Claude Desktop, or claude.ai, or the LLM Integration Guide for OpenAI.

Last updated on by Sona