Brands
Brands are discovered automatically from AI provider responses. When an AI response cites a URL or mentions a brand name, the system resolves it against existing brands (case-insensitive) or creates a new one.
Each brand has a type:
| Type | Description |
|---|---|
own | Your brand (the primary brand) |
competitor | A known competitor |
other | Any other brand (default for newly discovered brands) |
List brands
Retrieve brands for a project with visibility metrics. The aiVisibilityBrandId parameter specifies which brand's perspective to use for calculating metrics.
query GetAiVisibilityBrands(
$accountId: ObjectID!
$aiVisibilityProjectId: ObjectID!
$dateRange: AiVisibilityDateRangeInput
) {
getAiVisibilityBrands(
accountId: $accountId
aiVisibilityProjectId: $aiVisibilityProjectId
dateRange: $dateRange
first: 20
orderBy: [{ field: avgVisibilityScore, direction: DESC }]
) {
nodes {
id
rawId
name
type
primary
avgVisibilityScore
avgCitationQualityScore
avgBrandMentionQualityScore
avgBrandPosition
avgBrandSentiment
totalBrandCitations
domain
}
pageInfo {
hasNextPage
endCursor
}
totalCount
}
}
Sorting
Brands can be sorted by: name, domain, avgVisibilityScore, avgCitationQualityScore, avgBrandMentionQualityScore, avgBrandPosition, avgBrandSentiment, totalBrandCitations, type.
Default sort is avgVisibilityScore DESC when a date range is provided, or name ASC when omitted.
Metrics
When a dateRange is provided, each brand includes these computed metrics:
| Field | Description |
|---|---|
avgVisibilityScore | Composite score (0-100) combining citation and mention quality |
avgCitationQualityScore | Average quality score for citations |
avgBrandMentionQualityScore | Average quality score for brand mentions |
avgBrandPosition | Average citation position in responses |
avgBrandSentiment | Average sentiment score for brand mentions |
totalBrandCitations | Total number of citations |
domain | Primary domain associated with the brand |
Search brands
Search brands by name without requiring date range or brand ID parameters:
query SearchAiVisibilityBrands(
$accountId: ObjectID!
$aiVisibilityProjectId: ObjectID!
$search: String!
) {
searchAiVisibilityBrands(
input: {
accountId: $accountId
aiVisibilityProjectId: $aiVisibilityProjectId
search: $search
}
) {
id
rawId
name
type
}
}
Top brands
Get the top brands ranked by visibility score. Returns a fixed-size result set (up to ~8 brands) with the focus brand always included. Useful for leaderboard-style displays.
query GetAiVisibilityTopBrands(
$accountId: ObjectID!
$aiVisibilityProjectId: ObjectID!
$aiVisibilityBrandId: ObjectID!
$dateRange: AiVisibilityDateRangeInput
) {
getAiVisibilityTopBrands(
accountId: $accountId
aiVisibilityProjectId: $aiVisibilityProjectId
aiVisibilityBrandId: $aiVisibilityBrandId
dateRange: $dateRange
) {
totalRankedBrands
brands {
id
rawId
name
type
rank
avgVisibilityScore
avgCitationQualityScore
avgBrandMentionQualityScore
totalBrandCitations
totalBrandMentions
avgBrandPosition
avgBrandSentiment
domain
}
}
}
The totalRankedBrands field indicates how many brands were ranked in total. Each brand includes a rank field showing its position.
You can scope top brands to a specific topic or prompt using the optional aiVisibilityTopicId or aiVisibilityPromptId parameters.
Update brand type
Classify a brand as own, competitor, or other:
mutation UpdateAiVisibilityBrand(
$accountId: ObjectID!
$aiVisibilityBrandId: ObjectID!
$type: AiVisibilityBrandType!
) {
updateAiVisibilityBrand(
input: {
accountId: $accountId
aiVisibilityBrandId: $aiVisibilityBrandId
type: $type
}
) {
aiVisibilityBrand {
id
name
type
}
}
}
You cannot update the type of a merged brand directly. Update the target brand instead, and all merged brands will be synced automatically.
Merge brands
When the same entity appears under different names (e.g. "Lumar" and "Deepcrawl"), you can merge them. Merged brands are excluded from the brand list but their data is included in the target brand's aggregations.
mutation MergeAiVisibilityBrands(
$accountId: ObjectID!
$aiVisibilitySourceBrandIds: [ObjectID!]!
$aiVisibilityTargetBrandId: ObjectID!
) {
mergeAiVisibilityBrands(
input: {
accountId: $accountId
aiVisibilitySourceBrandIds: $aiVisibilitySourceBrandIds
aiVisibilityTargetBrandId: $aiVisibilityTargetBrandId
}
) {
targetBrand {
id
name
type
}
sourceBrands {
id
name
isMerged
mergedIntoAiVisibilityBrandId
}
}
}
You can merge multiple source brands into a single target in one operation. Cascading merges are handled automatically -- if a source brand already has other brands merged into it, those are redirected to the new target.
Validation rules
- Cannot merge the primary brand
- Cannot merge an already-merged brand
- Cannot merge into a brand that is itself merged
- Cannot merge a brand into itself
- Source and target must be in the same project
Unmerge a brand
Separate a previously merged brand. The brand reappears in the brand list with its original data.
mutation UnmergeAiVisibilityBrand(
$accountId: ObjectID!
$aiVisibilityBrandId: ObjectID!
) {
unmergeAiVisibilityBrand(
input: {
accountId: $accountId
aiVisibilityBrandId: $aiVisibilityBrandId
}
) {
aiVisibilityBrand {
id
name
isMerged
}
}
}
Promote a merged brand
Promote a merged brand to become the new "main" brand in a merge group. All sibling brands are redirected to point to the newly promoted brand.
mutation PromoteAiVisibilityBrand(
$accountId: ObjectID!
$aiVisibilityBrandId: ObjectID!
) {
promoteAiVisibilityBrand(
input: {
accountId: $accountId
aiVisibilityBrandId: $aiVisibilityBrandId
}
) {
promotedBrand {
id
name
isMerged
}
previousMainBrand {
id
name
isMerged
}
}
}
For example, if brands A and B are merged into C, promoting A makes it the new main with B and C merged into A.
Schema reference
AiVisibilityBrand-- Brand typeAiVisibilityBrandListItem-- Brand list item with metricsAiVisibilityBrandType-- Brand classificationAiVisibilityBrandDomain-- Associated domains