# Prompts

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

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

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

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

| Field                         | Description                                |
| ----------------------------- | ------------------------------------------ |
| `avgVisibilityScore`          | Composite visibility score for this prompt |
| `avgCitationQualityScore`     | Average citation quality score             |
| `avgBrandMentionQualityScore` | Average mention quality score              |
| `avgBrandPosition`            | Average citation position                  |
| `avgBrandSentiment`           | Average sentiment of brand mentions        |
| `totalRuns`                   | Total number of completed prompt runs      |
| `totalBrandCitations`         | Total citations for the specified brand    |
| `totalBrandMentions`          | Total mentions for the specified brand     |
| `topBrands`                   | Top 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.

```graphql
mutation CreateAiVisibilityPrompt(
  $accountId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
  $content: String!
) {
  createAiVisibilityPrompt(
    input: {
      accountId: $accountId
      aiVisibilityTopicId: $aiVisibilityTopicId
      content: $content
    }
  ) {
    aiVisibilityPrompt {
      id
      rawId
      content
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx",
  "content": "What are the best tools for technical SEO auditing?"
}
```

:::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.

```graphql
mutation DeleteAiVisibilityPrompt(
  $accountId: ObjectID!
  $aiVisibilityPromptId: ObjectID!
) {
  deleteAiVisibilityPrompt(
    input: {
      accountId: $accountId
      aiVisibilityPromptId: $aiVisibilityPromptId
    }
  ) {
    aiVisibilityPrompt {
      id
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityPromptId": "QWlWaXNpYmlsaXR5UHJvbXB0MQ"
}
```

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

```graphql
query GetAiVisibilitySuggestedPrompts(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
) {
  getAiVisibilitySuggestedPrompts(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
    aiVisibilityBrandId: $aiVisibilityBrandId
    aiVisibilityTopicId: $aiVisibilityTopicId
  ) {
    id
    content
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx",
  "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx"
}
```

### Generate suggestions

```graphql
mutation GenerateAiVisibilitySuggestedPrompts(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $aiVisibilityBrandId: ObjectID!
  $aiVisibilityTopicId: ObjectID!
) {
  generateAiVisibilitySuggestedPrompts(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      aiVisibilityBrandId: $aiVisibilityBrandId
      aiVisibilityTopicId: $aiVisibilityTopicId
    }
  ) {
    suggestions {
      id
      content
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "aiVisibilityBrandId": "QWlWaXNpYmlsaXR5QnJhbmQx",
  "aiVisibilityTopicId": "QWlWaXNpYmlsaXR5VG9waWMx"
}
```

## Schema reference

- [`AiVisibilityPrompt`](/docs/schema/objects/ai-visibility-prompt.md) -- Prompt type
- [`AiVisibilityPromptDetails`](/docs/schema/objects/ai-visibility-prompt-details.md) -- Prompt details with metrics
- [`AiVisibilitySuggestedPrompt`](/docs/schema/objects/ai-visibility-suggested-prompt.md) -- Suggested prompt type