# Visibility Scores & Analytics

https://api-docs.lumar.io/docs/ai-visibility/ai-visibility-scores

## Visibility score formula

The visibility score is a composite metric (0-100) calculated from two components:

```
visibility_score = avg_citation_quality_score x appearance_rate x 0.25
                 + avg_brand_mention_quality_score x appearance_rate x 0.75
```

- **Citation weight**: 25%
- **Mention weight**: 75%
- **Appearance rate**: `sqrt(runs_where_brand_appeared / total_finished_runs)` -- the square root provides a softer penalty than linear scaling

The score rewards brands that appear consistently across prompt runs. A brand that appears in every run with a score of 80 will outrank one that appears in 10% of runs with a score of 100.

## Aggregated visibility scores

Get a single time-series trend of visibility scores across all topics in a project:

```graphql
query GetAiVisibilityVisibilityScores(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $timeBucket: AiVisibilityTimeBucket!
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityVisibilityScores(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    timeBucket: $timeBucket
    dateRange: $dateRange
  ) {
    date
    avgVisibilityScore
    avgCitationQualityScore
    avgBrandMentionQualityScore
    totalBrandCitations
    totalBrandMentions
  }
}
```

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

### Time bucketing

The `timeBucket` parameter controls the granularity of the time series:

| Value   | Description              |
| ------- | ------------------------ |
| `day`   | One data point per day   |
| `week`  | One data point per week  |
| `month` | One data point per month |

### Data points

Each data point in the time series includes:

| Field                         | Description                                  |
| ----------------------------- | -------------------------------------------- |
| `date`                        | Start of the time bucket (ISO 8601 date)     |
| `avgVisibilityScore`          | Combined visibility score for this period    |
| `avgCitationQualityScore`     | Average citation quality score component     |
| `avgBrandMentionQualityScore` | Average mention quality score component      |
| `totalBrandCitations`         | Total citations for the brand in this period |
| `totalBrandMentions`          | Total mentions for the brand in this period  |

### Optional filters

The aggregated query supports optional `aiVisibilityTopicId` and `aiVisibilityPromptId` filters to narrow the scope to a specific topic or prompt.

## Per-topic visibility scores

Get visibility score trends broken down by topic:

```graphql
query GetAiVisibilityTopicVisibilityScores(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $timeBucket: AiVisibilityTimeBucket!
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityTopicVisibilityScores(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    timeBucket: $timeBucket
    dateRange: $dateRange
  ) {
    aiVisibilityTopicId
    aiVisibilityTopicRawId
    topicName
    dataPoints {
      date
      avgVisibilityScore
      avgCitationQualityScore
      avgBrandMentionQualityScore
      totalBrandCitations
      totalBrandMentions
    }
  }
}
```

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

Each topic in the result includes its own array of `dataPoints` with the same fields as the aggregated query. This is useful for comparing how visibility varies across different topic areas.

## AI providers

### List all providers

Get all available AI providers and whether they are included in your subscription:

```graphql
query GetAiVisibilityAiProviders($accountId: ObjectID!) {
  getAiVisibilityAiProviders(accountId: $accountId, first: 10) {
    nodes {
      id
      rawId
      name
      type
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ"
}
```

Available provider types:

| Type                          | Name         |
| ----------------------------- | ------------ |
| `openai_api`                  | ChatGPT      |
| `perplexity_api`              | Perplexity   |
| `google_api`                  | Gemini       |
| `anthropic_api`               | Claude       |
| `google_ai_mode_serp_api`     | AI Mode      |
| `google_ai_overview_serp_api` | AI Overviews |

### List active providers

Get providers that had at least one finished prompt run in a project within a date range. Useful for populating filter dropdowns:

```graphql
query GetAiVisibilityActiveAiProviders(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityActiveAiProviders(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    dateRange: $dateRange
  ) {
    id
    rawId
    name
    type
  }
}
```

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

## Filtering by AI provider

All data-fetching queries accept an optional `aiProviderTypes` parameter. When provided, only data from prompt runs executed by the specified platforms is included:

```graphql
getAiVisibilityTopics(
  # ... other params
  aiProviderTypes: [openai_api, perplexity_api]
) {
  # Only data from ChatGPT and Perplexity runs
}
```

## Schema reference

- [`AiVisibilityVisibilityScoreDataPoint`](/docs/schema/objects/ai-visibility-visibility-score-data-point.md) -- Time-series data point
- [`AiVisibilityTopicVisibilityScoreTrend`](/docs/schema/objects/ai-visibility-topic-visibility-score-trend.md) -- Per-topic trend
- [`AiVisibilityAiProvider`](/docs/schema/objects/ai-visibility-ai-provider.md) -- AI provider type
- [`AiVisibilityAiProviderType`](/docs/schema/enums/ai-visibility-ai-provider-type.md) -- Provider type enum
- [`AiVisibilityTimeBucket`](/docs/schema/enums/ai-visibility-time-bucket.md) -- Time bucket enum