# Brands

https://api-docs.lumar.io/docs/ai-visibility/ai-visibility-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.

```graphql
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
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "dateRange": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  }
}
```

### 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:

```graphql
query SearchAiVisibilityBrands(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $search: String!
) {
  searchAiVisibilityBrands(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      search: $search
    }
  ) {
    id
    rawId
    name
    type
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "search": "competitor"
}
```

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

```graphql
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
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx",
  "dateRange": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  }
}
```

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`:

```graphql
mutation UpdateAiVisibilityBrand(
  $accountId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $type: AiVisibilityBrandType!
) {
  updateAiVisibilityBrand(
    input: {
      accountId: $accountId
      aiVisibilityBrandId: $aiVisibilityBrandId
      type: $type
    }
  ) {
    aiVisibilityBrand {
      id
      name
      type
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQy",
  "type": "Competitor"
}
```

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

```graphql
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
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilitySourceBrandIds": ["QWlWaXNpYmlsaXR5QnJhbmQz", "QWlWaXNpYmlsaXR5QnJhbmQ0"],
  "aiVisibilityTargetBrandId": "QWlWaXNpYmlsaXR5QnJhbmQy"
}
```

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.

```graphql
mutation UnmergeAiVisibilityBrand(
  $accountId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
) {
  unmergeAiVisibilityBrand(
    input: {
      accountId: $accountId
      aiVisibilityBrandId: $aiVisibilityBrandId
    }
  ) {
    aiVisibilityBrand {
      id
      name
      isMerged
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQz"
}
```

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

```graphql
mutation PromoteAiVisibilityBrand(
  $accountId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
) {
  promoteAiVisibilityBrand(
    input: {
      accountId: $accountId
      aiVisibilityBrandId: $aiVisibilityBrandId
    }
  ) {
    promotedBrand {
      id
      name
      isMerged
    }
    previousMainBrand {
      id
      name
      isMerged
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQz"
}
```

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`](/docs/schema/objects/ai-visibility-brand.md) -- Brand type
- [`AiVisibilityBrandListItem`](/docs/schema/objects/ai-visibility-brand-list-item.md) -- Brand list item with metrics
- [`AiVisibilityBrandType`](/docs/schema/enums/ai-visibility-brand-type.md) -- Brand classification
- [`AiVisibilityBrandDomain`](/docs/schema/objects/ai-visibility-brand-domain.md) -- Associated domains