# Prompt Runs

https://api-docs.lumar.io/docs/ai-visibility/ai-visibility-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:

| Status     | Description                                  |
| ---------- | -------------------------------------------- |
| `pending`  | Created and waiting to be processed          |
| `running`  | Currently being processed by the AI provider |
| `finished` | Successfully completed with results          |
| `failed`   | Processing failed (see `failureReason`)      |

## List prompt runs

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

```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
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityPromptId": "QWlWaXNpYmlsaXR5UHJvbXB0MQ",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx",
  "dateRange": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  }
}
```

### 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):

| Field                 | Description                                                        |
| --------------------- | ------------------------------------------------------------------ |
| `brandVisible`        | Whether the brand appeared in the response (citations or mentions) |
| `totalBrandCitations` | Number of citations referencing the brand                          |
| `totalBrandMentions`  | Number of times the brand was mentioned                            |
| `bestBrandPosition`   | Best (lowest) citation position for the brand                      |
| `avgBrandSentiment`   | Average 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:

```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
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityPromptRunId": "QWlWaXNpYmlsaXR5UHJvbXB0UnVuMQ",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx"
}
```

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

- [`AiVisibilityPromptRunListItem`](/docs/schema/objects/ai-visibility-prompt-run-list-item.md) -- Prompt run list item
- [`AiVisibilityPromptRunDetails`](/docs/schema/objects/ai-visibility-prompt-run-details.md) -- Full prompt run details
- [`AiVisibilityPromptRunStatus`](/docs/schema/enums/ai-visibility-prompt-run-status.md) -- Status enum
- [`AiVisibilityPromptRunCitation`](/docs/schema/objects/ai-visibility-prompt-run-citation.md) -- Citation in a run
- [`AiVisibilityPromptRunMention`](/docs/schema/objects/ai-visibility-prompt-run-mention.md) -- Mention in a run