# AI Search Visibility Tracker for ChatGPT and Perplexity (`tan-solutions/ai-visibility`) Actor

Track how often AI search answers from the OpenAI and Perplexity APIs mention your brand vs competitors: mention rate, position, share of voice and cited sources, with trend runs. Bring your own API key. Pay per answer; failures are free. Not affiliated with OpenAI or Perplexity.

- **URL**: https://apify.com/tan-solutions/ai-visibility.md
- **Developed by:** [Tan Solutions](https://apify.com/tan-solutions) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 answers

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 Search Visibility Tracker for ChatGPT and Perplexity

See how AI search talks about your brand. Give your brand, up to 10 competitors and the questions your buyers ask.
Add your own **OpenAI** and/or **Perplexity** API key. The Actor asks each engine you gave a key for (the OpenAI API
with web search, the Perplexity Agent API with web search) each question several times and measures your **mention
rate**, **position** among the brands named, **share of voice** vs your competitors and the **sources the AI cites**.
Run it on a schedule with a monitor ID and every run reports the **change vs the previous run**.

Your key stays in your Apify account; Tan Solutions never receives it. It is stored encrypted as a secret input, used
only inside your own run to call the vendor, and never logged or written to the results.

The answers come from the OpenAI and Perplexity APIs with web search. They are close to, but not the same as, what
the ChatGPT and Perplexity apps show a logged-in user.

Use it for AI search visibility, a ChatGPT brand tracker, LLM brand monitoring or a Perplexity rank tracker (GEO / AEO).

Not affiliated with OpenAI or Perplexity.

### Run it from the API or on a schedule

Get the rows back in one call (replace the placeholder with your Apify token):

```bash
curl -X POST "https://api.apify.com/v2/acts/tan-solutions~ai-visibility/run-sync-get-dataset-items?token=<YOUR_APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"brand": "Acme CRM", "domain": "acme.example", "competitors": ["HubSpot", "Pipedrive", "Zoho CRM | Zoho"], "openaiApiKey": "<YOUR_OPENAI_KEY>", "prompts": ["What is the best CRM for a 10-person startup?", "Which CRM is easiest to set up?"], "engines": ["openai", "perplexity"], "repeats": 3, "country": "US", "monitorId": "acme-weekly"}'
```

Track the same prompts every Monday at 07:00 with an Apify schedule (replace `<ACTOR_ID>` with this Actor's ID from
the API tab):

```bash
curl -X POST "https://api.apify.com/v2/schedules?token=<YOUR_APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ai-visibility-weekly", "cronExpression": "0 7 * * 1", "timezone": "UTC", "isEnabled": true, "isExclusive": true,
       "actions": [{"type": "RUN_ACTOR", "actorId": "<ACTOR_ID>",
         "runInput": {"body": "{\"brand\": \"Acme CRM\", \"competitors\": [\"HubSpot\", \"Pipedrive\"], \"category\": \"CRM tools\", \"monitorId\": \"acme-weekly\"}", "contentType": "application/json"}}]}'
```

In Apify Console the same is: **Schedules**, **Create new**, cron `0 7 * * 1`, add this Actor with your input. Keep
the same **Monitor ID** and brand so each run is compared with the one before.

### What it does

- Asks each prompt **repeats** times per engine (AI answers vary from one ask to the next; default 3).
- **OpenAI** (with your OpenAI key): the Responses API with the web search tool switched on for every answer, so the
  answer reflects what the model finds on the web now. Default model `gpt-6-luna` (cheapest with web search);
  `gpt-6-astra` is the stronger option (`openaiModel`).
- **Perplexity** (with your Perplexity key): the Agent API with its `fast` preset (Perplexity picks the model; web
  search on). Or name a model in `perplexityModel`; web search stays on.
- Finds your brand and each competitor in the answer: whole words only, case and accents ignored, other names
  (aliases) included. "Notion" matches "notion" and "Notión" but not "notional".
- Reads the sources each answer cites and checks whether your own website (or a subdomain) is one of them.
- Writes one row per answer and one summary row per prompt and engine.

### Who it is for

- Marketing and SEO teams who need to know whether AI assistants recommend them, and who they recommend instead.
- Agencies reporting AI search visibility (GEO / AEO) to clients every week.
- Product teams checking which sources AI search trusts in their category, to know where to get mentioned.

### Quick start

1. Type your brand, your website and 3-10 competitors.
2. Add 5-20 questions a buyer would ask, or leave Prompts empty and type your category (for example "CRM tools").
3. Paste your OpenAI and/or Perplexity API key (each engine runs only with its key). Pick the number of repeats. Run.
   For a trend, set a Monitor ID and schedule the run.

With only a key and nothing else, it runs a small demo (one brand, 2 questions, 1 repeat). Without any key the run
ends at once with one free row: "Add your own OpenAI or Perplexity API key to run. Nothing was charged."

### Input

| Field | What it does |
| --- | --- |
| `brand` | Your brand name (required unless you run the demo). |
| `brandAliases` | Other names that count as your brand (at most 10). |
| `domain` | Your website; citations of it or its subdomains count as "brand site cited". |
| `competitors` | Up to 10 names; add other names after a bar, for example `Google Workspace \| Google Docs`. |
| `prompts` | Up to 50 questions, each at most 300 characters. |
| `category`, `promptTemplates` | Used when `prompts` is empty: built-in or own templates with `{category}`, `{brand}`, `{country}`. |
| `openaiApiKey` | Your own OpenAI API key (secret input, stored encrypted). Without it OpenAI is not asked. |
| `perplexityApiKey` | Your own Perplexity API key (secret input, stored encrypted). Without it Perplexity is not asked. |
| `openaiModel` | Optional; default `gpt-6-luna`, stronger `gpt-6-astra`. |
| `perplexityModel` | Optional; empty = Perplexity's `fast` preset, or a model such as `openai/gpt-6-luna`. |
| `repeats` | Asks per prompt and engine, 1-10 (default 3). |
| `concurrencyPerEngine` | Answers each engine works on at the same time, 1-8 (default 3). |
| `country` | 2-letter code for the web search location (default US; for Perplexity applied when a model is set). |
| `language` | Optional answer language. |
| `monitorId` | Name of a tracked series; the summary rows then carry the change vs the previous run. |

The system instructions and the search settings are fixed by the Actor; you choose only the model. It is a brand visibility
measurement, not a general way to send prompts to a model.

### Output

**Answer rows** (`rowType: "answer"`, one per answer, charged): `engine`, `model`, `prompt`, `repeat`,
`brandMentioned`, `position`, `competitorsMentioned`, `citedDomains`, `citedUrls` (clickable links), `brandCited`,
`answerExcerpt` (at most 500 characters around the first mention of your brand, as evidence).

**Summary rows** (`rowType: "summary"`, one per prompt and engine, free): `n`, `mentionRate`, `avgPosition`,
`shareOfVoice`, `citationRate`, `competitorMentionRates`, `topCitedDomains`, and with a monitor ID `change`
(`mentionRateDelta`, `avgPositionDelta`, `shareOfVoiceDelta`, `citationRateDelta`, `previousRunAt`).

**Error rows** (`rowType: "error"`, free): `NO_API_KEY`, `ENGINE_UNAVAILABLE`, `ENGINE_AUTH_FAILED` (key rejected),
`QUOTA_EXCEEDED` (no funds or quota on your vendor account), `MODEL_NOT_FOUND`, `RATE_LIMITED`, `TIMEOUT`,
`ENGINE_ERROR`, `BAD_RESPONSE` (the answer could not be read), `UNEXPECTED_RESPONSE` (the engine answered in a format this
Actor does not know, for example after an API change: no answer text or no list of sources). A rejected key, no funds or an
unknown model stop that engine for the rest of the run, and so do 2 `UNEXPECTED_RESPONSE` answers, so your vendor quota is
not spent on calls that would fail the same way. The run summary is in the key-value store as `SUMMARY`.

How the numbers are defined:

- **position**: 1 + the number of named competitors mentioned before your brand's first mention in that answer;
  empty when your brand is not mentioned.
- **mentionRate**: answers that mention the brand / answers.
- **avgPosition**: the mean position over the answers that mention the brand.
- **shareOfVoice**: answers mentioning the brand / the sum over every named brand (your brand and each competitor) of
  the answers mentioning it.
- **citationRate**: answers that cite the brand's domain (or a subdomain) / answers.
- **topCitedDomains**: the 5 domains cited by the most answers, with the number of answers.

### Pricing

Pay per answer: event `answer` per answer read from one engine for one question (see the Pricing tab; $8.00 per
1,000 answers on the free plan, $5.00 on GOLD). Summary rows, error rows and engines without a key are free.

You also pay your own OpenAI or Perplexity usage on your vendor account, at the vendor's prices (read 14 Nov 2026):
OpenAI web search $10.00 per 1,000 search calls plus model tokens; Perplexity web search $2.50 per 1,000 searches
($1.00 for the fast search type) plus model tokens. Your spending limit is checked before every question: the run stops cleanly when it is
reached.

### Limits

- At most 50 prompts x 10 repeats x 2 engines = 1,000 answers per run. Answers take about 5-60 seconds each; the two
  engines run side by side, each with 3 answers in progress at a time (`concurrencyPerEngine`, 1-8).
- Expected time with the default 3 per engine and both engines: **100 answers take about 6-17 minutes**;
  **1,000 answers take about 1-3 hours** (about 20-60 minutes with `concurrencyPerEngine` 8). Set the run timeout
  in the run options above the expected time; answers delivered before a stop stay in the dataset.
- If an engine answers "too many requests" (429) or has a server error, the Actor waits as long as the engine asks
  (Retry-After, at most 60 seconds) or 3, 6 seconds, then tries again; an answer that still fails is a free row.
- The answers come from the vendors' APIs with web search, not from the ChatGPT or Perplexity apps: they are close
  but can differ from what a logged-in user sees.
- Matching is by name. A brand with a common-word name (for example "Notion") is also counted when the word is used in
  its plain meaning; use a more specific name or an alias in such cases.

### FAQ

**Why repeats?** The same question gets different answers. Three or more asks per prompt give a stable mention rate.

**Do I need an OpenAI or Perplexity key?** Yes, at least one: each engine runs only with your own key. Your key
stays in your Apify account; Tan Solutions never receives it.

**What if my key is wrong or out of credit?** That engine stops after its first failed call and writes one free row
with the reason; the other engine goes on. Nothing is charged for it.

**How do I see a trend?** Set a Monitor ID and run on a schedule. The summary rows show the change vs the last run
with the same Monitor ID and brand.

### Related tools by Tan Solutions

- [Website Change Monitor](https://apify.com/tan-solutions/website-change-monitor): get told when a competitor's
  pricing, product or landing page changes.
- [Tech Stack Lookup](https://apify.com/tan-solutions/tech-stack): the technologies behind any website, with change
  alerts.
- [URL to Markdown](https://apify.com/tan-solutions/url-to-markdown): turn the pages AI search cites into clean
  Markdown for LLMs and RAG.
- [SEO Audit](https://apify.com/tan-solutions/seo-audit): on-page SEO checker with PageSpeed for any website.

### Your responsibilities

- You may not use the rows (answers, excerpts or metrics) to train or fine-tune AI models, or to build a product that
  resells AI answers.
- Cited sources are kept as links; keep them as links when you show them to others.
- No warranty: AI answers vary and can be wrong. Liability is capped at the fees you paid in the last 12 months.
- Not affiliated with OpenAI or Perplexity. ChatGPT is a trademark of OpenAI; Perplexity is a trademark of Perplexity AI.
- Questions and issues are answered within 14 days through the Actor's Issues tab.

Made by Tan Solutions.

# Actor input Schema

## `brand` (type: `string`):

Your brand or product name, as people write it (for example Notion). Matching ignores case and accents and needs whole words.

## `brandAliases` (type: `array`):

Optional other spellings or product names that count as your brand (at most 10).

## `domain` (type: `string`):

Optional. Your website (for example notion.com). Citations of this site or its subdomains count as 'brand site cited'.

## `competitors` (type: `array`):

Up to 10 competitor names. Add other names after a bar: 'Google Workspace | Google Docs'.

## `prompts` (type: `array`):

The questions your buyers ask an AI assistant, at most 50, each at most 300 characters. Leave empty to use the built-in questions for your category.

## `category` (type: `string`):

Used when Prompts is empty: your product category (for example 'CRM tools'). Fills the built-in questions such as 'What are the best {category}?'.

## `promptTemplates` (type: `array`):

Optional own templates used when Prompts is empty. Placeholders: {category}, {brand}, {country}.

## `openaiApiKey` (type: `string`):

Your own OpenAI API key (platform.openai.com). Needed to ask OpenAI. It is stored encrypted, used only inside your run and never logged or saved in the results. You pay OpenAI for your usage.

## `perplexityApiKey` (type: `string`):

Your own Perplexity API key. Needed to ask Perplexity. It is stored encrypted, used only inside your run and never logged or saved in the results. You pay Perplexity for your usage. Give at least one of the two keys.

## `openaiModel` (type: `string`):

Optional. Empty = gpt-6-luna (the cheapest model with web search). gpt-6-astra is the stronger option.

## `perplexityModel` (type: `string`):

Optional. Leave empty for Perplexity's fast preset (Perplexity picks the model; web search on). Or name a model such as openai/gpt-6-luna; web search stays on.

## `repeats` (type: `integer`):

AI answers change from one ask to the next. Each prompt is asked this many times per engine (1-10). Default 3.

## `concurrencyPerEngine` (type: `integer`):

How many answers each engine works on at the same time (1-8). Default 3. Higher is faster; if an engine answers 'too many requests', the Actor waits as the engine asks and tries again (failed answers are free).

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

2-letter country code for the web search location, for example US, GB or DE. Default US.

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

Optional. Ask for answers in this language, for example German.

## `monitorId` (type: `string`):

Optional name for a tracked series, for example 'notion-weekly'. Runs with the same ID and brand report the change vs the previous run. Letters, digits, '\_', '-' and '.' only.

## Actor input object example

```json
{
  "brand": "Notion",
  "domain": "notion.com",
  "competitors": [
    "Obsidian",
    "Evernote",
    "Coda"
  ],
  "prompts": [
    "What are the best note-taking apps for small teams?",
    "Which tool should a startup use for its internal wiki?"
  ],
  "repeats": 1,
  "concurrencyPerEngine": 3,
  "country": "US"
}
```

# Actor output Schema

## `results` (type: `string`):

One row per AI answer (brand mentioned, position, competitors, cited sources, short excerpt) and one summary row per prompt and engine (mention rate, average position, share of voice, top cited domains, change vs the last run).

## `summaries` (type: `string`):

Only the summary rows: mention rate, average position, share of voice, brand site citation rate, top cited domains and the change vs the previous run.

# 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 = {
    "brand": "Notion",
    "domain": "notion.com",
    "competitors": [
        "Obsidian",
        "Evernote",
        "Coda"
    ],
    "prompts": [
        "What are the best note-taking apps for small teams?",
        "Which tool should a startup use for its internal wiki?"
    ],
    "repeats": 1,
    "country": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("tan-solutions/ai-visibility").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 = {
    "brand": "Notion",
    "domain": "notion.com",
    "competitors": [
        "Obsidian",
        "Evernote",
        "Coda",
    ],
    "prompts": [
        "What are the best note-taking apps for small teams?",
        "Which tool should a startup use for its internal wiki?",
    ],
    "repeats": 1,
    "country": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("tan-solutions/ai-visibility").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 '{
  "brand": "Notion",
  "domain": "notion.com",
  "competitors": [
    "Obsidian",
    "Evernote",
    "Coda"
  ],
  "prompts": [
    "What are the best note-taking apps for small teams?",
    "Which tool should a startup use for its internal wiki?"
  ],
  "repeats": 1,
  "country": "US"
}' |
apify call tan-solutions/ai-visibility --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tan-solutions/ai-visibility"
        }
    }
}
```

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/yNbRVmtZuP3vf7gSG/builds/jZGRpzU7kLQ3gkU9t/openapi.json
