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, and the sources LLMs cite.

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, and the sources LLMs cite.

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

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.

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