# ChatGPT Search Visibility Tracker: Brand Mentions (API) (`venture_ace/chatgpt-search-visibility`) Actor

- **URL**: https://apify.com/venture_ace/chatgpt-search-visibility.md
- **Developed by:** [Venture Ace](https://apify.com/venture_ace) (community)
- **Categories:** AI, SEO tools, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

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

## ChatGPT Search Visibility Tracker (OpenAI API, your own key)

Asks ChatGPT's web search a list of questions through the official OpenAI Responses API (`web_search` tool) and reports, per prompt, whether your brand or domain is mentioned or cited.

- Input: `openaiApiKey` (yours, secret), `prompts` (one question per line), `brands` (names and/or domains, include competitors to compare), `maxPrompts` (50, hard cap 200), `model` (default `gpt-4.1-mini`), `country` (optional two-letter code), `searchContextSize` (low, medium, high).
- Output: one dataset row per prompt: `prompt, status, answer, citations[{url,title}], brands[{brand, mentioned, mentionCount, firstMentionChar, firstMentionRank, cited, citedUrls}], model, searches, inputTokens, outputTokens, timestamp, error`. Status is `ok`, `empty`, `key_rejected`, `failed` or `input_error`; a failed prompt does not fail the run (with no key, no prompts, no brands, or a key OpenAI rejects for every prompt the run still succeeds, with one `input_error` row that says what to fix).
- Matching: a brand name is mentioned when it appears as a whole word in the answer text (case-insensitive). A domain target counts its name part (`acme` for `acme.com`) or the full domain as a mention, and is cited when a cited URL is on that domain or a subdomain. `firstMentionRank` is the order in which your tracked targets first appear (1 = first). Simple text matching: it can miss a misspelling and cannot tell a recommendation from a warning.
- Your key: sent only to api.openai.com, never logged, never in the dataset or an error message. OpenAI bills you directly for web-search calls and tokens; this tool holds no model credit and makes no call without your key.
- Honest limit: this is the API with the web search tool, not the consumer ChatGPT app. Answers and citations can differ from what people see in the app (different model settings, personalisation, and search behaviour). Use it as a repeatable proxy, not a mirror.
- Pricing: no tool fee yet, you pay Apify platform usage (256 MB) plus OpenAI. Planned pay-per-event, not yet on: about US$5 per 1,000 prompts answered.
- Prompts run 3 at a time with retries on 429 and 5xx. Memory 256-512 MB.

Local test: `python -m unittest src.test_visibility` (httpx and apify installed; OpenAI is mocked, no key needed).

# Actor input Schema

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

Your own OpenAI API key. It is sent only to api.openai.com, is never written to the results or the log, and OpenAI bills you directly for the searches and tokens (web search is billed per call by OpenAI). Without a key the run stops and makes no call. Without a key the run ends with one input_error row and makes no call.

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

One question per line, as a customer would type it, for example 'best CRM for a small plumbing business'. Duplicates are dropped. Each prompt is one OpenAI web-search call.

## `brands` (type: `array`):

Brand names ('Acme') and/or domains ('acme.com'). A name counts as mentioned when it appears as a whole word in the answer text (case-insensitive). A domain counts as mentioned when its name part (acme for acme.com) or the full domain appears as a whole word in the text, and as cited when a cited URL is on that domain or a subdomain. Put competitors here too to compare.

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

Hard cap on prompts sent in this run; extra prompts are ignored with a log line.

## `model` (type: `string`):

Any model your key can use with the Responses API web search tool. Cheaper models cost you less per prompt at OpenAI.

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

Two-letter country code (for example AU, US, GB) passed as the approximate search location. Leave empty for no location.

## `searchContextSize` (type: `string`):

How much web content the search tool feeds the model. Higher costs you more at OpenAI.

## Actor input object example

```json
{
  "prompts": [
    "best project management tool for small teams"
  ],
  "brands": [
    "asana.com"
  ],
  "maxPrompts": 50,
  "model": "gpt-4.1-mini",
  "searchContextSize": "medium"
}
```

# Actor output Schema

## `prompts` (type: `string`):

One row per prompt: answer, cited URLs and, for each brand or domain, mentioned, cited and first-mention position.

# 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 = {
    "prompts": [
        "best project management tool for small teams"
    ],
    "brands": [
        "asana.com"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("venture_ace/chatgpt-search-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 = {
    "prompts": ["best project management tool for small teams"],
    "brands": ["asana.com"],
}

# Run the Actor and wait for it to finish
run = client.actor("venture_ace/chatgpt-search-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 '{
  "prompts": [
    "best project management tool for small teams"
  ],
  "brands": [
    "asana.com"
  ]
}' |
apify call venture_ace/chatgpt-search-visibility --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,venture_ace/chatgpt-search-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/kPajB6BhduaeVuaMa/builds/d0SHLfDEx0F5T7rhL/openapi.json