Skip to main content

Citations and Mentions

AI provider responses may contain citations (URL references to web pages) and mentions (textual references to brand names). These are extracted and stored for each prompt run.

Brand citations​

Brand citations are aggregated by URL, giving you a view of which pages are most frequently cited for a brand. Each result includes the AI providers and topics that cited the URL.

Operation: query GetAiVisibilityBrandCitations( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityBrandId: ObjectID! $dateRange: AiVisibilityDateRangeInput ) { getAiVisibilityBrandCitations( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityBrandId: $aiVisibilityBrandId dateRange: $dateRange first: 20 orderBy: [{ field: totalBrandCitations, direction: DESC }] ) { nodes { pageId canonicalUrl url title aiProviderTypes topicNames avgBrandPosition totalBrandCitations avgCitationScore } pageInfo { hasNextPage endCursor } totalCount } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx", "dateRange": { "start": "2025-01-01", "end": "2025-01-31" } }
GetAiVisibilityBrandCitationsTry in Explorer
GraphQL
query GetAiVisibilityBrandCitations(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityBrandCitations(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    dateRange: $dateRange
    first: 20
    orderBy: [{ field: totalBrandCitations, direction: DESC }]
  ) {
    nodes {
      pageId
      canonicalUrl
      url
      title
      aiProviderTypes
      topicNames
      avgBrandPosition
      totalBrandCitations
      avgCitationScore
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Fields​

FieldDescription
pageIdStable id for the cited page, shared with every other AI Visibility query
canonicalUrlCanonical form of the cited URL; the key rows are grouped by
urlA representative raw cited URL, for linking
titleSearch-result title for the page, or null if SERP discovery has never seen it
aiProviderTypesArray of AI providers that cited this URL
topicNamesArray of topic names associated with this URL's citations
avgBrandPositionAverage citation position across all appearances
totalBrandCitationsTotal number of times this URL was cited
avgCitationScoreAverage citation quality score (nullable)
brandThe brand the citations are attributed to (see below)

Each node is one page, not one URL spelling: citations of https://example.com/p?ref=chat and https://example.com/p aggregate into a single row, and totalCount counts pages. Join a row to page scores, discovered pages and page runs on pageId — see Page Identity.

Cited pages across all brands​

Omit aiVisibilityBrandId to list the pages cited for every brand in the project at once. A citation is attributed to the brand recognised as the cited page's publisher, so each row is one page and one publisher, with that brand in brand:

Operation: query GetAiVisibilityCitedPagesAcrossBrands( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityPromptId: ObjectID $brandTypes: [AiVisibilityBrandType!] $dateRange: AiVisibilityDateRangeInput ) { getAiVisibilityBrandCitations( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityPromptId: $aiVisibilityPromptId brandTypes: $brandTypes dateRange: $dateRange first: 20 ) { nodes { pageId canonicalUrl url title brand { id name type } totalBrandCitations avgBrandPosition avgCitationScore } pageInfo { hasNextPage endCursor } totalCount } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityPromptId": "QWlWaXNpYmlsaXR5UHJvbXB0MQ", "brandTypes": ["Own", "Competitor"], "dateRange": { "start": "2025-01-01", "end": "2025-01-31" } }
GetAiVisibilityCitedPagesAcrossBrandsTry in Explorer
GraphQL
query GetAiVisibilityCitedPagesAcrossBrands(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityPromptId: ObjectID
  $brandTypes: [AiVisibilityBrandType!]
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityBrandCitations(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityPromptId: $aiVisibilityPromptId
    brandTypes: $brandTypes
    dateRange: $dateRange
    first: 20
  ) {
    nodes {
      pageId
      canonicalUrl
      url
      title
      brand {
        id
        name
        type
      }
      totalBrandCitations
      avgBrandPosition
      avgCitationScore
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
  • A page normally has one publisher, so it is normally one row. It appears once per brand when AI answers attributed it to different publishers; totalCount counts these rows.
  • Merged brands are shown as their merge target.
  • Citations whose publisher was not recognised as any brand are a row with brand: null.
  • brandTypes limits the rows to pages published by brands of those types, for example [Own, Competitor], and leaves out pages with no recognised publisher. It is only accepted when aiVisibilityBrandId is omitted.
  • previousPeriod compares each row with the same page and brand in comparisonDateRange.

Across a whole project the result covers every cited page, so scope it with aiVisibilityPromptId or aiVisibilityTopicId and a dateRange where you can.

When aiVisibilityBrandId is given, brand is that brand on every row.

Sorting​

Citations can be sorted by: url, avgBrandPosition, totalBrandCitations, avgCitationScore. The url field sorts on canonicalUrl.

Default sort is totalBrandCitations DESC, canonicalUrl ASC. Across all brands, rows for the same page are then ordered by brand.

Filtering​

All parameters that filter brand citations:

ParameterTypeDescription
aiVisibilityProjectIdObjectID!Required. Scopes to a project
aiVisibilityBrandIdObjectIDOptional. The brand (including merged variants); omit for all brands
brandTypes[AiVisibilityBrandType]Optional. All brands only: limit to these publisher brand types
aiVisibilityTopicIdObjectIDOptional. Filter to a specific topic
aiVisibilityTopicIds[ObjectID]Optional. Filter to any of these topics (maximum 100)
aiVisibilityPromptIdObjectIDOptional. Filter to a specific prompt
dateRangeAiVisibilityDateRangeInputOptional. Defaults to last 30 days
aiProviderTypes[AiVisibilityAiProviderType]Optional. Filter by AI platform
searchStringOptional. Search the cited page's canonical URL
citedByAiProviderTypes[AiVisibilityAiProviderType]Optional. Pages cited by at least one of these AI platforms
notCitedByAiProviderTypes[AiVisibilityAiProviderType]Optional. Pages cited by none of these AI platforms
totalBrandCitationsAiVisibilityIntFilterInputOptional. Compare the page's totalBrandCitations
avgCitationScoreAiVisibilityFloatFilterInputOptional. Compare the page's avgCitationScore
avgBrandPositionAiVisibilityFloatFilterInputOptional. Compare the page's avgBrandPosition

search drops pages whose canonical URL does not contain the text, without changing the metrics of the pages it keeps, and totalCount counts only the matching pages — see Searching pages.

aiVisibilityTopicIds scopes the query the way aiVisibilityTopicId does, but to several topics: only citations from prompts in those topics count, so every metric changes with it. Pass one or the other, not both.

Filtering on what a page reports​

The remaining filters choose which pages are returned without changing any page's metrics, and totalCount counts only the pages that match:

Operation: query GetAiVisibilityFilteredCitedPages( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityBrandId: ObjectID! $aiVisibilityTopicIds: [ObjectID!] $citedByAiProviderTypes: [AiVisibilityAiProviderType!] $totalBrandCitations: AiVisibilityIntFilterInput $avgCitationScore: AiVisibilityFloatFilterInput $dateRange: AiVisibilityDateRangeInput ) { getAiVisibilityBrandCitations( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityBrandId: $aiVisibilityBrandId aiVisibilityTopicIds: $aiVisibilityTopicIds citedByAiProviderTypes: $citedByAiProviderTypes totalBrandCitations: $totalBrandCitations avgCitationScore: $avgCitationScore dateRange: $dateRange first: 20 ) { nodes { pageId canonicalUrl aiProviderTypes topicNames totalBrandCitations avgCitationScore } pageInfo { hasNextPage endCursor } totalCount } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx", "aiVisibilityTopicIds": ["QWlWaXNpYmlsaXR5VG9waWMx", "QWlWaXNpYmlsaXR5VG9waWMy"], "citedByAiProviderTypes": ["ChatgptUi", "GeminiUi"], "totalBrandCitations": { "ge": 5 }, "avgCitationScore": { "ge": 40, "lt": 60 }, "dateRange": { "start": "2025-01-01", "end": "2025-01-31" } }
GetAiVisibilityFilteredCitedPagesTry in Explorer
GraphQL
query GetAiVisibilityFilteredCitedPages(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $aiVisibilityTopicIds: [ObjectID!]
  $citedByAiProviderTypes: [AiVisibilityAiProviderType!]
  $totalBrandCitations: AiVisibilityIntFilterInput
  $avgCitationScore: AiVisibilityFloatFilterInput
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityBrandCitations(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    aiVisibilityTopicIds: $aiVisibilityTopicIds
    citedByAiProviderTypes: $citedByAiProviderTypes
    totalBrandCitations: $totalBrandCitations
    avgCitationScore: $avgCitationScore
    dateRange: $dateRange
    first: 20
  ) {
    nodes {
      pageId
      canonicalUrl
      aiProviderTypes
      topicNames
      totalBrandCitations
      avgCitationScore
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
  • citedByAiProviderTypes keeps a page when any of the listed AI platforms cited it; notCitedByAiProviderTypes keeps it when none of them did. Both test the platforms in the page's aiProviderTypes. This differs from aiProviderTypes, which leaves the other platforms' citations out of every metric.
  • totalBrandCitations, avgCitationScore and avgBrandPosition take the comparisons eq, ne, lt, le, gt and ge. Every comparison you set must hold, so { ge: 40, lt: 60 } selects a band. Averages are compared as returned, rounded to one decimal place, so a page shown with avgCitationScore: 60 is not kept by { gt: 60 }.
  • Filters on different fields, and every other argument, combine with AND.

Brand mentions​

Brand mentions return individual mention rows with full details including the mention text, its position in the response, and sentiment analysis.

Operation: query GetAiVisibilityBrandMentions( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityBrandId: ObjectID! $dateRange: AiVisibilityDateRangeInput ) { getAiVisibilityBrandMentions( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityBrandId: $aiVisibilityBrandId dateRange: $dateRange first: 20 orderBy: [{ field: brandMentionQualityScore, direction: DESC }] ) { nodes { rawId text textSpan { start end } position brandName brandType sentiment sentimentJustification brandMentionQualityScore aiProviderType createdAt } pageInfo { hasNextPage endCursor } totalCount } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx", "dateRange": { "start": "2025-01-01", "end": "2025-01-31" } }
GetAiVisibilityBrandMentionsTry in Explorer
GraphQL
query GetAiVisibilityBrandMentions(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityBrandMentions(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    dateRange: $dateRange
    first: 20
    orderBy: [{ field: brandMentionQualityScore, direction: DESC }]
  ) {
    nodes {
      rawId
      text
      textSpan {
        start
        end
      }
      position
      brandName
      brandType
      sentiment
      sentimentJustification
      brandMentionQualityScore
      aiProviderType
      createdAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Fields​

FieldDescription
rawIdUnique mention identifier
textThe mention text
textSpanCharacter offset range (start and end) within the full response
positionPosition of the mention within the answer
brandNameOriginal brand name (preserved even for merged brands)
brandTypeBrand type (own, competitor, other)
sentimentSentiment score
sentimentJustificationExplanation for the sentiment rating
brandMentionQualityScoreQuality score (0-100)
aiProviderTypeWhich AI provider generated this mention
createdAtWhen the prompt run was created
citationsCitations the answer used to support this mention (see below)

Citations behind a mention​

citations lists the sources the answer used to support each mention, in answer order. These are the citations placed in the passage that names the brand, or those the AI platform itself reported as backing it. A citation's publisher is not necessarily the mentioned brand: a review site can support a mention of your competitor, and publisherBrandName tells you who publishes the page.

Each citation carries:

FieldDescription
positionPosition of the citation within the answer
url / canonicalUrlThe cited URL as returned, and its canonical page key
domainHost of the cited page, lowercased and without www.
domainOwnershipOwn, Competitor or Other, checked against your brands' domains
publisherBrandNameBrand that publishes the cited page, when one was recognised
sourceTypeAuthoritative, Listicle or Weak: the kind of page the source is
backingHow the citation was tied to the passage: Grounded (reported by the platform), Inline, Marker or None
citationQualityScoreCitation quality score (0-100)

domainOwnership compares the cited page's host with the domains of your project's own and competitor brands. A brand domain covers subdomains only when includeSubdomains is set on it, and www. is ignored on both sides. When a domain belongs to both an own and a competitor brand, it counts as Own.

citations is empty when the answer's sources could not be tied to the passage. Some AI platforms, such as Google AI Overviews and AI Mode, never report where their sources sit, so their mentions have no backing citations. Mentions from runs processed before citations were linked to mentions are also empty.

sourceType can differ between two runs that cite the same page, so compare it across many mentions rather than reading a single citation's value as settled.

Operation: query GetAiVisibilityBrandMentionsFromIndependentSources( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityBrandId: ObjectID! $dateRange: AiVisibilityDateRangeInput ) { getAiVisibilityBrandMentions( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityBrandId: $aiVisibilityBrandId dateRange: $dateRange citationSource: NonOwnDomain first: 20 ) { nodes { rawId text sentiment brandMentionQualityScore aiProviderType citations { position url domain domainOwnership publisherBrandName sourceType backing } } pageInfo { hasNextPage endCursor } totalCount } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx", "dateRange": { "start": "2025-01-01", "end": "2025-01-31" } }
GetAiVisibilityBrandMentionsFromIndependentSourcesTry in Explorer
GraphQL
query GetAiVisibilityBrandMentionsFromIndependentSources(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityBrandMentions(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    dateRange: $dateRange
    citationSource: NonOwnDomain
    first: 20
  ) {
    nodes {
      rawId
      text
      sentiment
      brandMentionQualityScore
      aiProviderType
      citations {
        position
        url
        domain
        domainOwnership
        publisherBrandName
        sourceType
        backing
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Sorting​

Mentions can be sorted by: id, position, brandMentionQualityScore, createdAt.

Default sort is brandMentionQualityScore DESC.

Filtering​

Same filtering parameters as brand citations (project, brand, topic, prompt, date range, AI provider types), plus filters on the citations behind each mention:

ArgumentDescription
citationSourceCited, Uncited, OwnDomain, NonOwnDomain (backed by a page outside your own domains) or ThirdPartyDomain (outside own and competitor domains)
citationSourceTypesOnly mentions backed by a citation of these source types
citationDomainsOnly mentions backed by a citation on one of these domains or their subdomains, such as reddit.com
answerMentionsOwnBrandtrue or false: whether the same answer also mentions one of your own brands

citationSource, citationSourceTypes and citationDomains must all hold for the same backing citation: citationSource: NonOwnDomain with citationSourceTypes: [Listicle] returns mentions backed by a listicle outside your domains. Combining Uncited with either of the other two returns no mentions. totalCount reflects every filter.

To find competitor mentions in answers that leave your brand out, sourced from independent pages, query the competitor's mentions with answerMentionsOwnBrand: false and citationSource: ThirdPartyDomain.

Schema reference​