# Topics

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

Topics group related prompts together. For example, you might have topics like "Technical SEO", "Content Marketing", or "Site Performance". Each topic can contain multiple prompts that are sent to AI providers.

## List topics

Retrieve topics for a project with visibility metrics. Requires `aiVisibilityBrandId` to specify which brand's perspective to use for metrics.

```graphql
query GetAiVisibilityTopics(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityTopics(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    dateRange: $dateRange
    first: 20
    orderBy: [{ field: avgVisibilityScore, direction: DESC }]
  ) {
    nodes {
      id
      rawId
      name
      totalPrompts
      avgVisibilityScore
      avgCitationQualityScore
      avgBrandMentionQualityScore
      totalBrandCitations
      totalBrandMentions
      topBrands {
        name
        type
        avgVisibilityScore
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
```

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

### Sorting

Topics can be sorted by: `name`, `avgVisibilityScore`, `totalPrompts`, `avgBrandMentionQualityScore`, `avgCitationQualityScore`, `totalBrandMentions`, `totalBrandCitations`.

Default sort is `avgVisibilityScore DESC` when a date range is provided, or `name ASC` when omitted.

### Metrics

Each topic includes these computed fields when a `dateRange` is provided:

| Field                         | Description                                           |
| ----------------------------- | ----------------------------------------------------- |
| `avgVisibilityScore`          | Composite visibility score for the topic              |
| `avgCitationQualityScore`     | Average citation quality across prompts in this topic |
| `avgBrandMentionQualityScore` | Average mention quality across prompts in this topic  |
| `totalBrandCitations`         | Total citations for the specified brand               |
| `totalBrandMentions`          | Total mentions for the specified brand                |
| `totalPrompts`                | Number of prompts in this topic                       |
| `topBrands`                   | Top 4 brands by visibility score across all brands    |

## Get a single topic

```graphql
query GetAiVisibilityTopic(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
) {
  getAiVisibilityTopic(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityTopicId: $aiVisibilityTopicId
  ) {
    id
    rawId
    name
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx"
}
```

## Search topics

Lightweight search for typeahead scenarios. Returns a simple array without pagination:

```graphql
query SearchAiVisibilityTopics(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $search: String!
) {
  searchAiVisibilityTopics(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      search: $search
    }
  ) {
    id
    rawId
    name
  }
}
```

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

## Create a topic

```graphql
mutation CreateAiVisibilityTopic(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $name: String!
) {
  createAiVisibilityTopic(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      name: $name
    }
  ) {
    aiVisibilityTopic {
      id
      rawId
      name
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "name": "Technical SEO"
}
```

## Update a topic

Rename an existing topic:

```graphql
mutation UpdateAiVisibilityTopic(
  $accountId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
  $name: String!
) {
  updateAiVisibilityTopic(
    input: {
      accountId: $accountId
      aiVisibilityTopicId: $aiVisibilityTopicId
      name: $name
    }
  ) {
    aiVisibilityTopic {
      id
      rawId
      name
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx",
  "name": "Advanced Technical SEO"
}
```

## Delete a topic

Soft-deletes a topic and cascades the deletion to all prompts under it.

```graphql
mutation DeleteAiVisibilityTopic(
  $accountId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
) {
  deleteAiVisibilityTopic(
    input: {
      accountId: $accountId
      aiVisibilityTopicId: $aiVisibilityTopicId
    }
  ) {
    aiVisibilityTopic {
      id
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx"
}
```

:::caution
Deleting a topic will also soft-delete all prompts within it. Existing prompt run data is preserved but no new runs will be created for those prompts.
:::

## Suggested topics

Use AI to generate topic suggestions based on your brand. Suggestions are cached per project and brand -- calling generate again replaces the previous suggestions.

### Get suggestions

```graphql
query GetAiVisibilitySuggestedTopics(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
) {
  getAiVisibilitySuggestedTopics(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
  ) {
    id
    name
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx"
}
```

### Generate suggestions

```graphql
mutation GenerateAiVisibilitySuggestedTopics(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
) {
  generateAiVisibilitySuggestedTopics(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      aiVisibilityBrandId: $aiVisibilityBrandId
    }
  ) {
    suggestions {
      id
      name
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx"
}
```

## Schema reference

- [`AiVisibilityTopic`](/docs/schema/objects/ai-visibility-topic.md) -- Topic type
- [`AiVisibilityTopicDetails`](/docs/schema/objects/ai-visibility-topic-details.md) -- Topic details type
- [`AiVisibilitySuggestedTopic`](/docs/schema/objects/ai-visibility-suggested-topic.md) -- Suggested topic type