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.
query GetAiVisibilityPrompts(
$accountId: ObjectID!
$aiVisibilityProjectId: ObjectID!
$aiVisibilityBrandId: ObjectID!
$dateRange: AiVisibilityDateRangeInput
$aiVisibilityTopicId: ObjectID
$branded: Boolean
) {
getAiVisibilityPrompts(
accountId: $accountId
aiVisibilityProjectId: $aiVisibilityProjectId
aiVisibilityBrandId: $aiVisibilityBrandId
dateRange: $dateRange
aiVisibilityTopicId: $aiVisibilityTopicId
branded: $branded
first: 20
orderBy: [{ field: avgVisibilityScore, direction: DESC }]
) {
nodes {
id
rawId
content
branded
topicName
avgVisibilityScore
avgCitationQualityScore
avgBrandMentionQualityScore
avgBrandPosition
avgBrandSentiment
totalRuns
totalBrandCitations
totalBrandMentions
topBrands {
name
type
avgVisibilityScore
}
}
pageInfo {
hasNextPage
endCursor
}
totalCount
}
}
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 |
Brand types
brandTypes restricts which brands may appear in each prompt's topBrands. Without it, the ranking spans every brand in the project, including Context brands (platforms and surfaces such as Google or ChatGPT); pass [Own, Competitor, Other] to keep them out of the top 4 so the next ranked brands take those slots. The argument never changes which prompts are returned or the specified brand's own metrics.
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.
mutation CreateAiVisibilityPrompt(
$accountId: ObjectID!
$aiVisibilityTopicId: ObjectID!
$content: String!
$branded: Boolean
) {
createAiVisibilityPrompt(
input: {
accountId: $accountId
aiVisibilityTopicId: $aiVisibilityTopicId
content: $content
branded: $branded
}
) {
aiVisibilityPrompt {
id
rawId
content
branded
}
}
}
Prompt creation is subject to two limits, both counting active (non-paused) prompts only, so resuming a paused prompt is subject to them too. If either is reached, the mutation returns AI_VISIBILITY_PROMPTS_LIMIT_REACHED with the limit that was hit in extensions.limit.
The per-project limit is AiVisibilityProject.effectivePromptsLimit. On managed accounts that carry a per-project cap it is based on your subscription, the number of AI providers, and the project's schedule cadence, and it is capped by the budget still available to the project when the account also has a per-account limit (the account limit minus active prompts on the account's other projects). Self-serve plans carry no per-project cap, so for them it is that remaining account budget on its own. Either way it is always the number of active prompts this project can hold right now.
The per-account limit is Account.aiVisibilityPromptsLimit, one budget shared by every project on the account. Self-serve plans always have it, and it is the only prompts limit they observe: the "prompts" figure on the plan is for the whole account, so one project may use all of it and the others share what is left. Managed accounts have it only when their package sets it, otherwise it is null and only the per-project limit applies. Account.aiVisibilityActivePromptsCount reports the prompts in use across the account, so aiVisibilityPromptsLimit - aiVisibilityActivePromptsCount is what can still be added anywhere on the account. Both fields are available before any project exists.
Before a project exists there is no effectivePromptsLimit to read, so sizing a setup flow uses Account.aiVisibilityNewProjectPromptsLimit(scheduleCadence: AiVisibilityScheduleCadence = Daily) instead: the number of active prompts a project created now, with that cadence, could hold. It applies whichever of the two limits the write path enforces for the account, so a setup flow that offers this number will not have its first createAiVisibilityTopicsBulk rejected. Pass the cadence the project will be created with; the default matches the creation default.
Branded and unbranded
branded records whether the prompt names the project's own (primary) brand:
- Branded -- the prompt names the brand ("is Acme worth it for a 200-page site?"). It measures how AI answers describe the brand when it is asked about directly.
- Unbranded -- the prompt does not name your brand ("best technical SEO platform for enterprise sites?"). It measures whether the brand surfaces at all for a category question. A prompt naming only a competitor is unbranded too: the tag is about your own brand alone, so generated prompts avoid competitor names, but one you write yourself may carry them.
The tag is always about the project's own brand, never about a competitor the prompt happens to name, so it means the same thing whichever brand a query is scoped to -- including suggestions generated in the context of a competitor brand.
It defaults to false on createAiVisibilityPrompt and on each prompt of
createAiVisibilityTopicsBulk, and every prompt created before the field existed is stored as
unbranded whatever its text says. That default is not a reading of the prompt, so a prompt written
before the tag existed that does name your brand stays out of branded: true results until you
correct it.
setAiVisibilityPromptBranded is how you correct one. It changes the tag alone -- the prompt keeps
its text, its schedule and its whole run history, and nothing is re-run -- so the metrics already
collected for that prompt simply move to the other side of the filter:
mutation {
setAiVisibilityPromptBranded(input: { accountId: "...", aiVisibilityPromptId: "...", branded: true }) {
aiVisibilityPrompt {
id
content
branded
}
}
}
A prompt's text cannot be edited; to reword one, delete it and create a replacement. The tag is the one part that can be changed in place.
Omitting branded while passing aiVisibilitySuggestedPromptId inherits that suggestion's tag, but
only while the tag still describes what is being saved: the suggestion must belong to the topic the
prompt is created under, and content must equal the suggestion's text. Edit the text, or name a
suggestion from another topic, and the new prompt is unbranded rather than carrying a tag that no
longer matches it -- so send branded explicitly whenever you edit a suggestion before saving it.
Pass branded: true or branded: false to getAiVisibilityPrompts to list one kind on its own;
omit it for both.
The same branded filter is accepted by every AI Visibility analytics surface that already scopes by
topic, prompt, AI platform and country -- visibility scores and their trend, topic visibility scores,
Share of Voice trend, top brands, the topics connection, citations, mentions, search queries, and the
theme sentiment scores, matrix, details and claims. Passing it there answers the question the tag
exists for: how the brand performs on category questions, separately from questions that name it.
Country
country (ISO 3166-1 alpha-2) is the market the prompt is executed against and is three-state:
- Omitted -- inherits the project's
country(nullwhen the project has none) - Explicit
null-- worldwide, even when the project has a country - String value (e.g.
"US") -- that country, validated and upper-cased
The value is fixed at creation. Changing the project's country later does not rewrite existing prompts or runs. The same rule applies to each prompt in createAiVisibilityTopicsBulk. Unknown or malformed codes are rejected as input validation errors.
Delete a prompt
Soft-deletes a prompt. Existing prompt run data is preserved.
mutation DeleteAiVisibilityPrompt(
$accountId: ObjectID!
$aiVisibilityPromptId: ObjectID!
) {
deleteAiVisibilityPrompt(
input: {
accountId: $accountId
aiVisibilityPromptId: $aiVisibilityPromptId
}
) {
aiVisibilityPrompt {
id
}
}
}
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
query GetAiVisibilitySuggestedPrompts(
$accountId: ObjectID!
$aiVisibilityProjectId: ObjectID!
$aiVisibilityBrandId: ObjectID!
$aiVisibilityTopicId: ObjectID!
) {
getAiVisibilitySuggestedPrompts(
accountId: $accountId
aiVisibilityProjectId: $aiVisibilityProjectId
aiVisibilityBrandId: $aiVisibilityBrandId
aiVisibilityTopicId: $aiVisibilityTopicId
) {
id
content
branded
}
}
Generate suggestions
mutation GenerateAiVisibilitySuggestedPrompts(
$accountId: ObjectID!
$aiVisibilityProjectId: ObjectID!
$aiVisibilityBrandId: ObjectID!
$aiVisibilityTopicId: ObjectID!
) {
generateAiVisibilitySuggestedPrompts(
input: {
accountId: $accountId
aiVisibilityProjectId: $aiVisibilityProjectId
aiVisibilityBrandId: $aiVisibilityBrandId
aiVisibilityTopicId: $aiVisibilityTopicId
}
) {
suggestions {
id
content
branded
}
}
}
What a suggestion looks like
Suggestions are written as the first message a person would type into an AI assistant: a single
question, optionally with one sentence of context. Every suggestion returned is at most 3 sentences
and 600 characters, and never a paragraph, checklist or multi-line brief. Prompts you create
yourself are only bound by the 2,500 character limit on content.
Generation aims for a mix: roughly a third of the suggestions name the brand and the rest are
category questions, and each carries its own branded flag. The split is what the generator is
asked for rather than a guarantee, so read each suggestion's flag instead of assuming the ratio.
Accepting a suggestion with createAiVisibilityPrompt carries that flag over unless the request
states one.
count is the number of suggestions requested, not a guarantee. A suggestion that comes back
outside those bounds is regenerated rather than trimmed, and one that is still unusable is dropped,
so a successful response can contain fewer suggestions than requested. Read the length of the
returned list rather than assuming count entries. If nothing usable survives, the mutation fails
with an error rather than returning an empty list -- retry it.
Schema reference
AiVisibilityPrompt-- Prompt typeAiVisibilityPromptDetails-- Prompt details with metricsAiVisibilitySuggestedPrompt-- Suggested prompt type