# AI Visibility Prompt Research & Panel Builder (`aitorsm/geo-prompt-research`) Actor

Discover and prioritize buyer questions into reusable, versioned prompt panels for AI visibility tracking and generative engine optimization (GEO).

- **URL**: https://apify.com/aitorsm/geo-prompt-research.md
- **Developed by:** [Aitor Sanchez-Mansilla](https://apify.com/aitorsm) (community)
- **Categories:** AI, SEO tools, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 accepted versioned prompts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## AI Visibility Prompt Research: Build Reusable GEO Panels

[![GEO Prompt Research status](https://apify.com/actor-badge?actor=aitorsm/geo-prompt-research)](https://apify.com/aitorsm/geo-prompt-research)

Find the questions buyers ask about your category, turn them into a prioritized prompt
panel, and reuse it to measure whether AI assistants recommend your brand. This is
prompt research for generative engine optimization (GEO), answer engine optimization
(AEO), large language model optimization (LLMO), and AI search visibility.

GEO Prompt Research gives you:

- buyer questions grounded in live search-query evidence;
- natural AI-ready prompt wording;
- intent labels for commercial, comparison, evaluation, informational, and support needs;
- duplicate removal, so closely related questions do not crowd the panel;
- transparent priority scores and optional search-demand metrics;
- a stable panel identity and version label for repeat tracking;
- exportable candidate and audit data for content planning.

### Who it is for

- **GEO and AEO teams** building repeatable AI visibility programs
- **SEO and content teams** choosing high-value pages, FAQs, and comparisons
- **Brand and product marketers** monitoring recommendation visibility
- **Agencies** creating consistent prompt sets for multiple clients or markets
- **Research teams** comparing buyer questions across countries, languages, or personas

### What you can do

#### Track AI visibility over time

Build a fixed prompt panel, run those prompts through your preferred AI visibility tool,
and compare results on a schedule. The version label helps you see when the accepted
prompt set has changed.

#### Plan GEO and AEO content

Use intent and priority to turn buyer questions into a backlog:

- commercial prompts → buying guides and category pages;
- comparison prompts → alternatives and versus pages;
- evaluation prompts → proof, reviews, and case studies;
- troubleshooting prompts → help-center content;
- informational prompts → FAQs and educational articles.

#### Research competitors and alternatives

Add your brand name to discover comparison-style queries around your category without
forcing your brand into every final prompt.

#### Build localized or persona-specific panels

Create separate panels for each country, language, or audience, such as “a solo founder”
or “an IT manager at a mid-size company.”

### Simple GEO → AI workflow

1. Enter one or more category or product topics.
2. Choose a market, language, audience, and desired panel size.
3. Run GEO Prompt Research.
4. Review the accepted prompts and excluded candidates.
5. Use the accepted prompts in ChatGPT, Perplexity, Gemini, or an AI visibility tracker.
6. Repeat on a schedule and compare the panel version and visibility results.
7. Turn high-priority gaps into new comparison pages, buying guides, FAQs, or support content.

### Quick start

Use this input:

```json
{
  "seeds": ["project management software", "eventbrite alternative"],
  "brandName": "Acme PM",
  "country": "us",
  "language": "en",
  "audiencePersona": "a small business owner",
  "maxPrompts": 25,
  "enrichDemand": true
}
```

Then open the run results:

- **Prompt panel** contains the accepted, ordered prompts and their version label.
- **Panel and candidate audit** shows accepted prompts, filtered candidates,
  near-duplicates, scores, reasons, and inclusion status.
- **Raw dataset** is available for JSON, CSV, or spreadsheet workflows.

### Input

| Field | Type | Description |
|---|---|---|
| `seeds` | string array, required | 1–25 topics, products, or categories; up to 200 characters each. |
| `brandName` | string | Optional brand or product name for comparison discovery. |
| `brandDomain` | string | Optional display metadata. The website is not visited. |
| `country` | string | Optional two-letter country code such as `us`, `gb`, `es`, or `de`. |
| `language` | string | Optional two-letter language code. Default: `en`. |
| `audiencePersona` | string | Optional audience context added to prompt wording. |
| `includeTerms` | string array | Keep candidates containing at least one selected term. Up to 50 terms. |
| `excludeTerms` | string array | Remove candidates containing selected terms. Up to 50 terms. |
| `intents` | string array | Keep only selected intents: `informational`, `comparison`, `commercial`, `troubleshooting`, or `evaluation`. |
| `maxPrompts` | integer | Maximum accepted prompts. Default: `20`; maximum: `500`. |
| `enrichDemand` | boolean | Add available monthly search volume, CPC, and competition. Default: `false`. |
| `maxCostUsd` | number | Optional research budget guard from `0` to `1000`. `0` returns an empty structured panel without starting research. |
| `maxRuntimeSecs` | integer | Runtime budget from `30` to `3600` seconds. Default: `300`. |
| `deterministic` | boolean | Optional focused mode. Default: `false`, which uses broader A-Z discovery. Set `true` for a smaller, faster sweep. |

Inputs outside the published limits are rejected rather than silently shortened.

### Output

Every run returns a prompt panel and a candidate audit.

#### Prompt panel example

```json
{
  "schemaVersion": 1,
  "status": "succeeded",
  "panelId": "panel_3f9a1c7b2e4d5a10",
  "panelVersion": "9c2b7a41f0e3d6c8",
  "createdAt": "2026-09-22T10:15:00.000Z",
  "settings": {
    "seeds": ["project management software"],
    "country": "us",
    "language": "en",
    "maxPrompts": 20
  },
  "warnings": [],
  "errors": [],
  "prompts": [
    {
      "promptId": "8b1e4f9a2c7d31",
      "order": 1,
      "text": "What is the best project management software for a small business owner?",
      "intent": "commercial",
      "priorityScore": 0.87,
      "keyword": "best project management software",
      "componentScores": {
        "intentWeight": 1,
        "prominenceScore": 0.95,
        "coverageScore": 0.6,
        "demandScore": 0.81
      },
      "demand": {
        "searchVolume": 8100,
        "cpc": 4.2,
        "competition": "MEDIUM",
        "competitionIndex": 55
      }
    }
  ]
}
```

#### Candidate audit

The candidate table includes:

- source keyword and AI-ready prompt text;
- intent, priority, and component scores;
- optional demand metrics;
- duplicate group and representative status;
- accepted order or exclusion reason;
- panel identity and version for reliable exports;
- plain-language scoring reasons and run warnings.

A run can report `succeeded`, `partial`, or `failed`. Partial results remain clearly
labeled, with warnings explaining missing or limited research.

### Pricing

The recommended Store price is **$0.025 per accepted prompt**.

Examples:

| Accepted prompts | Price |
|---:|---:|
| 10 | $0.25 |
| 20 | $0.50 |
| 50 | $1.25 |
| 100 | $2.50 |

There is no separate panel or report surcharge. Platform usage charges may still apply
according to your Apify plan.

### Practical limits

- 1–25 seeds per run
- up to 500 accepted prompts
- up to 50 include terms and 50 exclude terms
- optional demand data may be unavailable for some keywords
- live query and demand data can change between runs
- broader discovery explores more keyword variations and may take longer
- budget or runtime limits can return a smaller, clearly labeled partial panel
- invalid or empty seed input is rejected before research begins

### Privacy and safety

- Your website is **not crawled**.
- `brandDomain` is stored only as context in the result.
- No website login, API key, or customer credential is requested.
- Prompts are derived from search-query evidence and fixed wording rules, not from a
  generative model inventing questions.

### FAQ

#### Does this ask an AI model to invent prompts?

No. Prompt wording is created from discovered search questions using consistent rules.
This keeps every prompt traceable to query evidence.

#### Why is `demandScore` sometimes `null`?

Demand enrichment may be off, limited by your budget or runtime, or unavailable for a
specific keyword. Missing demand is shown as `null`, not as zero.

#### Will the same input always produce the same panel?

The ranking and formatting process is repeatable, but the underlying search and demand
data is live. Broad A-Z discovery is enabled by default to find more long-tail variants.
Enable focused discovery only when you prefer a smaller, faster sweep. Use the panel
version to identify a changed accepted prompt set.

#### Can I focus only on buyer-ready questions?

Yes. Use:

```json
{
  "seeds": ["accounting software"],
  "intents": ["commercial", "comparison", "evaluation"],
  "maxPrompts": 30
}
```

#### Can I run separate panels by market?

Yes. Use a different `country`, `language`, or `audiencePersona` for each market. Each
configuration receives its own panel identity.

#### What happens if research is incomplete?

The result is labeled `partial` and includes plain-language warnings. Available prompts
remain exportable, while unavailable demand stays `null`.

### Related Actors

- [Keyword Fan-out](https://apify.com/aitorsm/keyword-fanout) — discover raw long-tail
  keywords and questions.
- [Keyword Search Volume](https://apify.com/aitorsm/keyword-volume) — retrieve search
  volume, CPC, and competition for keyword lists.
- **AI Visibility Tracker** — run the accepted panel against AI assistants and monitor
  brand mentions, citations, and recommendations over time.

If GEO Prompt Research is useful, bookmark it on Apify for quick scheduled runs.

# Actor input Schema

## `seeds` (type: `array`):

Required topic or category phrases. Empty input is rejected before research begins.

## `brandName` (type: `string`):

Display/discovery context only; never fetched.

## `brandDomain` (type: `string`):

Display metadata only; never fetched.

## `country` (type: `string`):

Two-letter country code. Omit or leave blank for worldwide.

## `language` (type: `string`):

Two-letter language code.

## `audiencePersona` (type: `string`):

Audience context appended to generated prompts.

## `includeTerms` (type: `array`):

Keep candidates containing at least one term.

## `excludeTerms` (type: `array`):

Drop candidates containing any term.

## `intents` (type: `array`):

Restrict the panel to selected intents; empty means all.

## `maxPrompts` (type: `integer`):

Hard cap on charged, delivered prompts.

## `enrichDemand` (type: `boolean`):

Add available search volume, CPC, and competition. Missing data remains null.

## `maxCostUsd` (type: `number`):

Limits the size of this research run under the published cost assumptions. Zero returns an empty structured panel; omit for the standard limits.

## `maxRuntimeSecs` (type: `integer`):

Stops research within the selected time budget while leaving time to save available results.

## `deterministic` (type: `boolean`):

Leave this off for broad coverage (recommended), including A-Z keyword expansions. Turn it on only for a smaller, faster research sweep.

## Actor input object example

```json
{
  "seeds": [
    "project management software",
    "eventbrite alternative"
  ],
  "country": "us",
  "language": "en",
  "maxPrompts": 20,
  "enrichDemand": false,
  "maxRuntimeSecs": 300,
  "deterministic": false
}
```

# Actor output Schema

## `promptPanel` (type: `string`):

Accepted prompts, panel identity and version, run status, settings, and warnings.

## `overview` (type: `string`):

Accepted and excluded candidates with panel version, scores, demand, reasons, and result status.

## `dataset` (type: `string`):

Complete panel summary and candidate rows for export or integration.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "seeds": [
        "project management software"
    ],
    "country": "us",
    "language": "en",
    "maxPrompts": 20,
    "enrichDemand": false,
    "deterministic": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("aitorsm/geo-prompt-research").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "seeds": ["project management software"],
    "country": "us",
    "language": "en",
    "maxPrompts": 20,
    "enrichDemand": False,
    "deterministic": False,
}

# Run the Actor and wait for it to finish
run = client.actor("aitorsm/geo-prompt-research").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "seeds": [
    "project management software"
  ],
  "country": "us",
  "language": "en",
  "maxPrompts": 20,
  "enrichDemand": false,
  "deterministic": false
}' |
apify call aitorsm/geo-prompt-research --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,aitorsm/geo-prompt-research"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/P2f4zZZuyR43Z5skE/builds/r0NhwLo1VRYdqZQLu/openapi.json