Skip to main content

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.

Operation: 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: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx", "dateRange": { "start": "2025-01-01", "end": "2025-01-31" } }
GetAiVisibilityTopicsTry in Explorer
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
  }
}

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:

FieldDescription
avgVisibilityScoreComposite visibility score for the topic
avgCitationQualityScoreAverage citation quality across prompts in this topic
avgBrandMentionQualityScoreAverage mention quality across prompts in this topic
totalBrandCitationsTotal citations for the specified brand
totalBrandMentionsTotal mentions for the specified brand
totalPromptsNumber of prompts in this topic
topBrandsTop 4 brands by visibility score across all brands

Get a single topic​

Operation: query GetAiVisibilityTopic( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityTopicId: ObjectID! ) { getAiVisibilityTopic( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityTopicId: $aiVisibilityTopicId ) { id rawId name } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx" }
GetAiVisibilityTopicTry in Explorer
GraphQL
query GetAiVisibilityTopic(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
) {
  getAiVisibilityTopic(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityTopicId: $aiVisibilityTopicId
  ) {
    id
    rawId
    name
  }
}

Search topics​

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

Operation: query SearchAiVisibilityTopics( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $search: String! ) { searchAiVisibilityTopics( input: { accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId search: $search } ) { id rawId name } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "search": "SEO" }
SearchAiVisibilityTopicsTry in Explorer
GraphQL
query SearchAiVisibilityTopics(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $search: String!
) {
  searchAiVisibilityTopics(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      search: $search
    }
  ) {
    id
    rawId
    name
  }
}

Create a topic​

Operation: mutation CreateAiVisibilityTopic( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $name: String! ) { createAiVisibilityTopic( input: { accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId name: $name } ) { aiVisibilityTopic { id rawId name } } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "name": "Technical SEO" }
CreateAiVisibilityTopicTry in Explorer
GraphQL
mutation CreateAiVisibilityTopic(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $name: String!
) {
  createAiVisibilityTopic(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      name: $name
    }
  ) {
    aiVisibilityTopic {
      id
      rawId
      name
    }
  }
}

Update a topic​

Rename an existing topic:

Operation: mutation UpdateAiVisibilityTopic( $accountId: ObjectID! $aiVisibilityTopicId: ObjectID! $name: String! ) { updateAiVisibilityTopic( input: { accountId: $accountId aiVisibilityTopicId: $aiVisibilityTopicId name: $name } ) { aiVisibilityTopic { id rawId name } } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx", "name": "Advanced Technical SEO" }
UpdateAiVisibilityTopicTry in Explorer
GraphQL
mutation UpdateAiVisibilityTopic(
  $accountId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
  $name: String!
) {
  updateAiVisibilityTopic(
    input: {
      accountId: $accountId
      aiVisibilityTopicId: $aiVisibilityTopicId
      name: $name
    }
  ) {
    aiVisibilityTopic {
      id
      rawId
      name
    }
  }
}

Delete a topic​

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

Operation: mutation DeleteAiVisibilityTopic( $accountId: ObjectID! $aiVisibilityTopicId: ObjectID! ) { deleteAiVisibilityTopic( input: { accountId: $accountId aiVisibilityTopicId: $aiVisibilityTopicId } ) { aiVisibilityTopic { id } } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx" }
DeleteAiVisibilityTopicTry in Explorer
GraphQL
mutation DeleteAiVisibilityTopic(
  $accountId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
) {
  deleteAiVisibilityTopic(
    input: {
      accountId: $accountId
      aiVisibilityTopicId: $aiVisibilityTopicId
    }
  ) {
    aiVisibilityTopic {
      id
    }
  }
}
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​

Operation: query GetAiVisibilitySuggestedTopics( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityBrandId: ObjectID! ) { getAiVisibilitySuggestedTopics( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityBrandId: $aiVisibilityBrandId ) { id name } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx" }
GetAiVisibilitySuggestedTopicsTry in Explorer
GraphQL
query GetAiVisibilitySuggestedTopics(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
) {
  getAiVisibilitySuggestedTopics(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
  ) {
    id
    name
  }
}

Generate suggestions​

Operation: mutation GenerateAiVisibilitySuggestedTopics( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityBrandId: ObjectID! ) { generateAiVisibilitySuggestedTopics( input: { accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityBrandId: $aiVisibilityBrandId } ) { suggestions { id name } } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx" }
GenerateAiVisibilitySuggestedTopicsTry in Explorer
GraphQL
mutation GenerateAiVisibilitySuggestedTopics(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
) {
  generateAiVisibilitySuggestedTopics(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      aiVisibilityBrandId: $aiVisibilityBrandId
    }
  ) {
    suggestions {
      id
      name
    }
  }
}

Schema reference​