# Citations and Mentions

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

```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 {
      url
      aiProviderTypes
      topicNames
      avgBrandPosition
      totalBrandCitations
      avgCitationScore
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
```

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

### Fields

| Field                 | Description                                               |
| --------------------- | --------------------------------------------------------- |
| `url`                 | The cited URL                                             |
| `aiProviderTypes`     | Array of AI providers that cited this URL                 |
| `topicNames`          | Array of topic names associated with this URL's citations |
| `avgBrandPosition`    | Average citation position across all appearances          |
| `totalBrandCitations` | Total number of times this URL was cited                  |
| `avgCitationScore`    | Average citation quality score (nullable)                 |

### Sorting

Citations can be sorted by: `url`, `avgBrandPosition`, `totalBrandCitations`, `avgCitationScore`.

Default sort is `totalBrandCitations DESC, url ASC`.

### Filtering

All parameters that filter brand citations:

| Parameter               | Type                           | Description                                     |
| ----------------------- | ------------------------------ | ----------------------------------------------- |
| `aiVisibilityProjectId` | `ObjectID!`                    | Required. Scopes to a project                   |
| `aiVisibilityBrandId`   | `ObjectID!`                    | Required. The brand (including merged variants) |
| `aiVisibilityTopicId`   | `ObjectID`                     | Optional. Filter to a specific topic            |
| `aiVisibilityPromptId`  | `ObjectID`                     | Optional. Filter to a specific prompt           |
| `dateRange`             | `AiVisibilityDateRangeInput`   | Optional. Defaults to last 30 days              |
| `aiProviderTypes`       | `[AiVisibilityAiProviderType]` | Optional. Filter by AI platform                 |

## Brand mentions

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

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

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

### Fields

| Field                      | Description                                                         |
| -------------------------- | ------------------------------------------------------------------- |
| `rawId`                    | Unique mention identifier                                           |
| `text`                     | The mention text                                                    |
| `textSpan`                 | Character offset range (`start` and `end`) within the full response |
| `position`                 | Position of the mention within the answer                           |
| `brandName`                | Original brand name (preserved even for merged brands)              |
| `brandType`                | Brand type (`own`, `competitor`, `other`)                           |
| `sentiment`                | Sentiment score                                                     |
| `sentimentJustification`   | Explanation for the sentiment rating                                |
| `brandMentionQualityScore` | Quality score (0-100)                                               |
| `aiProviderType`           | Which AI provider generated this mention                            |
| `createdAt`                | When the prompt run was created                                     |

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

## Schema reference

- [`AiVisibilityCitationListItem`](/docs/schema/objects/ai-visibility-citation-list-item.md) -- Citation aggregation type
- [`AiVisibilityMentionListItem`](/docs/schema/objects/ai-visibility-mention-list-item.md) -- Mention row type
- [`AiVisibilityTextSpan`](/docs/schema/objects/ai-visibility-text-span.md) -- Text span type
- [`AiVisibilityCitationQualityScoreComponent`](/docs/schema/objects/ai-visibility-citation-quality-score-component.md) -- Citation quality breakdown
- [`AiVisibilityMentionQualityScoreComponent`](/docs/schema/objects/ai-visibility-mention-quality-score-component.md) -- Mention quality breakdown