Skip to main content

Prompts

Prompts are the questions sent to AI providers. Each prompt belongs to a topic and is executed against all AI providers linked to the project. When created, prompts are automatically queued for execution and continue to run based on the project's schedule cadence.

List prompts​

Retrieve prompts with analytics metrics. Requires aiVisibilityBrandId to specify which brand's perspective to use. Optionally filter by topic using aiVisibilityTopicId.

Operation: query GetAiVisibilityPrompts( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityBrandId: ObjectID! $dateRange: AiVisibilityDateRangeInput $aiVisibilityTopicId: ObjectID ) { getAiVisibilityPrompts( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityBrandId: $aiVisibilityBrandId dateRange: $dateRange aiVisibilityTopicId: $aiVisibilityTopicId first: 20 orderBy: [{ field: avgVisibilityScore, direction: DESC }] ) { nodes { id rawId content topicName avgVisibilityScore avgCitationQualityScore avgBrandMentionQualityScore avgBrandPosition avgBrandSentiment totalRuns 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" } }
GetAiVisibilityPromptsTry in Explorer
GraphQL
query GetAiVisibilityPrompts(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $dateRange: AiVisibilityDateRangeInput
  $aiVisibilityTopicId: ObjectID
) {
  getAiVisibilityPrompts(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    dateRange: $dateRange
    aiVisibilityTopicId: $aiVisibilityTopicId
    first: 20
    orderBy: [{ field: avgVisibilityScore, direction: DESC }]
  ) {
    nodes {
      id
      rawId
      content
      topicName
      avgVisibilityScore
      avgCitationQualityScore
      avgBrandMentionQualityScore
      avgBrandPosition
      avgBrandSentiment
      totalRuns
      totalBrandCitations
      totalBrandMentions
      topBrands {
        name
        type
        avgVisibilityScore
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Sorting​

Prompts can be sorted by: content, topicName, avgVisibilityScore, avgCitationQualityScore, avgBrandMentionQualityScore, avgBrandPosition, avgBrandSentiment, totalRuns, totalBrandMentions, totalBrandCitations.

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

Metrics​

Each prompt includes these computed fields when a dateRange is provided:

FieldDescription
avgVisibilityScoreComposite visibility score for this prompt
avgCitationQualityScoreAverage citation quality score
avgBrandMentionQualityScoreAverage mention quality score
avgBrandPositionAverage citation position
avgBrandSentimentAverage sentiment of brand mentions
totalRunsTotal number of completed prompt runs
totalBrandCitationsTotal citations for the specified brand
totalBrandMentionsTotal mentions for the specified brand
topBrandsTop 4 brands by visibility score

Create a prompt​

Create a prompt under a topic. The prompt is automatically queued for execution against all configured AI providers. Maximum content length is 2,500 characters.

Operation: mutation CreateAiVisibilityPrompt( $accountId: ObjectID! $aiVisibilityTopicId: ObjectID! $content: String! ) { createAiVisibilityPrompt( input: { accountId: $accountId aiVisibilityTopicId: $aiVisibilityTopicId content: $content } ) { aiVisibilityPrompt { id rawId content } } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx", "content": "What are the best tools for technical SEO auditing?" }
CreateAiVisibilityPromptTry in Explorer
GraphQL
mutation CreateAiVisibilityPrompt(
  $accountId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
  $content: String!
) {
  createAiVisibilityPrompt(
    input: {
      accountId: $accountId
      aiVisibilityTopicId: $aiVisibilityTopicId
      content: $content
    }
  ) {
    aiVisibilityPrompt {
      id
      rawId
      content
    }
  }
}
note

Prompt creation is subject to a per-project limit based on your subscription, the number of AI providers, and the schedule cadence. If the limit is reached, the mutation returns AI_VISIBILITY_PROMPTS_LIMIT_REACHED.

Delete a prompt​

Soft-deletes a prompt. Existing prompt run data is preserved.

Operation: mutation DeleteAiVisibilityPrompt( $accountId: ObjectID! $aiVisibilityPromptId: ObjectID! ) { deleteAiVisibilityPrompt( input: { accountId: $accountId aiVisibilityPromptId: $aiVisibilityPromptId } ) { aiVisibilityPrompt { id } } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityPromptId": "QWlWaXNpYmlsaXR5UHJvbXB0MQ" }
DeleteAiVisibilityPromptTry in Explorer
GraphQL
mutation DeleteAiVisibilityPrompt(
  $accountId: ObjectID!
  $aiVisibilityPromptId: ObjectID!
) {
  deleteAiVisibilityPrompt(
    input: {
      accountId: $accountId
      aiVisibilityPromptId: $aiVisibilityPromptId
    }
  ) {
    aiVisibilityPrompt {
      id
    }
  }
}

Suggested prompts​

Use AI to generate prompt suggestions for a specific topic and brand. Suggestions are cached -- calling generate again replaces the previous suggestions for that topic.

Get suggestions​

Operation: query GetAiVisibilitySuggestedPrompts( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityBrandId: ObjectID! $aiVisibilityTopicId: ObjectID! ) { getAiVisibilitySuggestedPrompts( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityBrandId: $aiVisibilityBrandId aiVisibilityTopicId: $aiVisibilityTopicId ) { id content } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx", "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx" }
GetAiVisibilitySuggestedPromptsTry in Explorer
GraphQL
query GetAiVisibilitySuggestedPrompts(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
) {
  getAiVisibilitySuggestedPrompts(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    aiVisibilityTopicId: $aiVisibilityTopicId
  ) {
    id
    content
  }
}

Generate suggestions​

Operation: mutation GenerateAiVisibilitySuggestedPrompts( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $aiVisibilityBrandId: ObjectID! $aiVisibilityTopicId: ObjectID! ) { generateAiVisibilitySuggestedPrompts( input: { accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId aiVisibilityBrandId: $aiVisibilityBrandId aiVisibilityTopicId: $aiVisibilityTopicId } ) { suggestions { id content } } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx", "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx" }
GenerateAiVisibilitySuggestedPromptsTry in Explorer
GraphQL
mutation GenerateAiVisibilitySuggestedPrompts(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
) {
  generateAiVisibilitySuggestedPrompts(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      aiVisibilityBrandId: $aiVisibilityBrandId
      aiVisibilityTopicId: $aiVisibilityTopicId
    }
  ) {
    suggestions {
      id
      content
    }
  }
}

Schema reference​