Skip to main content

Prompt Runs

A prompt run represents a single execution of a prompt against an AI provider. Each prompt run produces an answer that may contain citations (URL references) and brand mentions.

Status lifecycle​

Prompt runs progress through these statuses:

StatusDescription
pendingCreated and waiting to be processed
runningCurrently being processed by the AI provider
finishedSuccessfully completed with results
failedProcessing failed (see failureReason)

List prompt runs​

Retrieve prompt runs for a specific prompt with brand-specific metrics:

Operation: query GetAiVisibilityPromptRuns( $accountId: ObjectID! $aiVisibilityPromptId: ObjectID! $aiVisibilityBrandId: ObjectID! $dateRange: AiVisibilityDateRangeInput ) { getAiVisibilityPromptRuns( accountId: $accountId aiVisibilityPromptId: $aiVisibilityPromptId aiVisibilityBrandId: $aiVisibilityBrandId dateRange: $dateRange first: 20 orderBy: [{ field: createdAt, direction: DESC }] ) { nodes { id rawId status aiProviderType brandVisible totalBrandCitations totalBrandMentions bestBrandPosition avgBrandSentiment createdAt } pageInfo { hasNextPage endCursor } totalCount } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityPromptId": "QWlWaXNpYmlsaXR5UHJvbXB0MQ", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx", "dateRange": { "start": "2025-01-01", "end": "2025-01-31" } }
GetAiVisibilityPromptRunsTry in Explorer
GraphQL
query GetAiVisibilityPromptRuns(
  $accountId: ObjectID!
  $aiVisibilityPromptId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityPromptRuns(
    accountId: $accountId
    aiVisibilityPromptId: $aiVisibilityPromptId
    aiVisibilityBrandId: $aiVisibilityBrandId
    dateRange: $dateRange
    first: 20
    orderBy: [{ field: createdAt, direction: DESC }]
  ) {
    nodes {
      id
      rawId
      status
      aiProviderType
      brandVisible
      totalBrandCitations
      totalBrandMentions
      bestBrandPosition
      avgBrandSentiment
      createdAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Sorting​

Prompt runs can be sorted by: createdAt, status, totalBrandCitations, totalBrandMentions, bestBrandPosition, avgBrandSentiment.

Default sort is createdAt DESC.

Computed fields​

Each prompt run includes these brand-specific metrics (calculated for the brand specified by aiVisibilityBrandId, including any merged variants):

FieldDescription
brandVisibleWhether the brand appeared in the response (citations or mentions)
totalBrandCitationsNumber of citations referencing the brand
totalBrandMentionsNumber of times the brand was mentioned
bestBrandPositionBest (lowest) citation position for the brand
avgBrandSentimentAverage sentiment score for brand mentions

Get prompt run details​

Fetch the full details of a prompt run, including the AI response text, all citations, and all mentions:

Operation: query GetAiVisibilityPromptRunDetails( $accountId: ObjectID! $aiVisibilityPromptRunId: ObjectID! $aiVisibilityBrandId: ObjectID! ) { getAiVisibilityPromptRunDetails( accountId: $accountId aiVisibilityPromptRunId: $aiVisibilityPromptRunId aiVisibilityBrandId: $aiVisibilityBrandId ) { aiProviderType promptText topicName fullAnswerText brandVisible totalBrandCitations totalBrandMentions bestBrandPosition avgBrandSentiment visibilityScore brandCitations { url position citationQualityScore } brandMentions { brandName brandType brandMentionQualityScore sentiment sentimentJustification } otherBrandCitations { url position brandName brandType } createdAt } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityPromptRunId": "QWlWaXNpYmlsaXR5UHJvbXB0UnVuMQ", "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx" }
GetAiVisibilityPromptRunDetailsTry in Explorer
GraphQL
query GetAiVisibilityPromptRunDetails(
  $accountId: ObjectID!
  $aiVisibilityPromptRunId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
) {
  getAiVisibilityPromptRunDetails(
    accountId: $accountId
    aiVisibilityPromptRunId: $aiVisibilityPromptRunId
    aiVisibilityBrandId: $aiVisibilityBrandId
  ) {
    aiProviderType
    promptText
    topicName
    fullAnswerText
    brandVisible
    totalBrandCitations
    totalBrandMentions
    bestBrandPosition
    avgBrandSentiment
    visibilityScore
    brandCitations {
      url
      position
      citationQualityScore
    }
    brandMentions {
      brandName
      brandType
      brandMentionQualityScore
      sentiment
      sentimentJustification
    }
    otherBrandCitations {
      url
      position
      brandName
      brandType
    }
    createdAt
  }
}

The response includes:

  • fullAnswerText -- The complete AI-generated response
  • promptText -- The original prompt text
  • brandCitations -- Citations attributed to the specified brand
  • brandMentions -- Mentions of the specified brand
  • otherBrandCitations -- Citations attributed to other brands

Schema reference​