Skip to main content

Page Runs (Content Evaluation)

Page runs are content evaluation crawls that analyze URLs cited by AI providers. They measure content quality, relevance, brand positioning, and other metrics to help you understand why certain pages are (or aren't) being cited.

How page runs work​

Page runs can be triggered in two ways:

  1. Automatically -- When a prompt run finishes and the project has autoCrawlEnabled = true, citation URLs matching your brand's domains are automatically crawled. URLs are skipped if they were recently crawled within the freshnessThresholdDays window.

  2. Manually -- Trigger a content evaluation for any URL via the API.

Each page run uses the Single Page Requester (SPR) to crawl the URL and run content evaluation metrics.

Status lifecycle​

StatusDescription
pendingCreated and waiting to be crawled
crawlingCurrently being crawled by SPR
completedSuccessfully crawled with metrics
failedCrawl failed (see failureReason)

List page runs​

Retrieve page runs for a project. Optionally filter by URL:

Operation: query GetAiVisibilityPageRuns( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! ) { getAiVisibilityPageRuns( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId first: 20 ) { nodes { rawId url status precisionScore recallScore qualityScore trustScore brandMentionScore brandSentimentScore brandPositionScore failureReason createdAt updatedAt } pageInfo { hasNextPage endCursor } totalCount } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE" }
GetAiVisibilityPageRunsTry in Explorer
GraphQL
query GetAiVisibilityPageRuns(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
) {
  getAiVisibilityPageRuns(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    first: 20
  ) {
    nodes {
      rawId
      url
      status
      precisionScore
      recallScore
      qualityScore
      trustScore
      brandMentionScore
      brandSentimentScore
      brandPositionScore
      failureReason
      createdAt
      updatedAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Score fields​

Completed page runs include these numeric scores (0-100 scale):

ScoreDescription
precisionScoreHow precisely the content matches the intended topic
recallScoreHow comprehensively the content covers the topic
uniquenessScoreHow unique the content is compared to other sources
qualityScoreOverall content quality
trustScoreTrustworthiness of the content
brandMentionScoreHow well the brand is mentioned in the content
brandSentimentScoreBrand sentiment within the content
brandPositionScoreHow prominently the brand is positioned
topicalOpportunityScoreOpportunity to improve topical coverage
evergreenHealthScoreHow well the content maintains relevance over time
qdfScoreQuery Deserves Freshness score
gscQueryScoreGoogle Search Console query relevance

Additional fields include boolean metrics (e.g. hasPageChanged, domainInResults), text analysis fields (e.g. primaryPageIntent, topicalOpportunityReasoning), and detailed JSONB evaluation arrays.

Trigger a page run​

Manually trigger a content evaluation for a URL:

Operation: mutation TriggerAiVisibilityPageRun( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $url: String! ) { triggerAiVisibilityPageRun( input: { accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId url: $url } ) { aiVisibilityPageRun { rawId url status sprRequestId createdAt } } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "url": "https://example.com/my-page" }
TriggerAiVisibilityPageRunTry in Explorer
GraphQL
mutation TriggerAiVisibilityPageRun(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $url: String!
) {
  triggerAiVisibilityPageRun(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      url: $url
    }
  ) {
    aiVisibilityPageRun {
      rawId
      url
      status
      sprRequestId
      createdAt
    }
  }
}
note

Triggering a page run consumes ContentEvals credits from your account. The mutation validates credit availability before creating the run.

Page scores (aggregated)​

Get aggregated scores across multiple page runs, grouped by URL. Useful for understanding average content quality over time:

Operation: query GetAiVisibilityPageScores( $accountId: ObjectID! $aiVisibilityProjectId: ObjectID! $dateRange: AiVisibilityDateRangeInput ) { getAiVisibilityPageScores( accountId: $accountId aiVisibilityProjectId: $aiVisibilityProjectId dateRange: $dateRange ) { url avgPrecisionScore avgRecallScore avgQualityScore avgTrustScore avgBrandMentionScore avgBrandSentimentScore avgBrandPositionScore totalRuns latestRunAt } }Variables: { "accountId": "TjAwN0FjY291bnQxMjM0NQ", "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE", "dateRange": { "start": "2025-01-01", "end": "2025-01-31" } }
GetAiVisibilityPageScoresTry in Explorer
GraphQL
query GetAiVisibilityPageScores(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $dateRange: AiVisibilityDateRangeInput
) {
  getAiVisibilityPageScores(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    dateRange: $dateRange
  ) {
    url
    avgPrecisionScore
    avgRecallScore
    avgQualityScore
    avgTrustScore
    avgBrandMentionScore
    avgBrandSentimentScore
    avgBrandPositionScore
    totalRuns
    latestRunAt
  }
}

Page scores return average values for each score field, along with totalRuns and latestRunAt. Results are limited to 10,000 URLs.

Automatic crawling setup​

To enable automatic page run creation when AI providers cite your brand's pages:

  1. Set autoCrawlEnabled: true on your project (see Projects)
  2. Optionally adjust freshnessThresholdDays (default: 7 days)

The system will:

  • Filter citation URLs to match your primary brand's domains (including subdomains)
  • Skip URLs that have a recent page run within the freshness threshold
  • Skip URLs that already have an in-flight page run (pending or crawling)

Schema reference​