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​

status is an AiVisibilityPromptRunStatus enum, not free text. Prompt runs progress through these statuses:

StatusTerminalDescription
PendingNoCreated and waiting to be processed
RunningNoCurrently being processed by the AI provider
SubmittedNoSent to the provider; the answer is still being collected
FinishedYesSuccessfully completed with results
FailedYesProcessing failed (see failureReason)
NoResponseYesThe provider returned no answer for the prompt

Each run also exposes isTerminal, which is true once the run has settled and no further work is expected. Prefer it over comparing status against a list of your own: Submitted in particular is still in progress, and if a status is added later isTerminal keeps classifying runs correctly.

Settled is not the same as immutable. A run can move between two settled statuses: if publishing a scheduled batch appears to fail, its runs are marked Failed, but the publish may have succeeded with only the response lost, and those runs are corrected to Finished once they complete. isTerminal stays true throughout, so it is safe to stop polling -- but do not treat a cached Failed as the last word if the result matters.

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 isTerminal 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
      isTerminal
      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, plus unattributed ones. Accepts a brandTypes argument, e.g. otherBrandCitations(brandTypes: [Own, Competitor, Other]), to leave Context brands (platforms such as Google or ChatGPT) out; unattributed citations are always included

Schema reference​