# AI Answer Visibility Tracker - Brand Mentions (`tidytools/ai-answer-visibility`) Actor

Ask live AI engines your buyer questions: brand mentions, mention order vs competitors and cited URLs, with a GEO fix plan link. Gemini is available; Perplexity needs its API key. $0.12 per successful query; failed queries free.

- **URL**: https://apify.com/tidytools/ai-answer-visibility.md
- **Developed by:** [Yukai Lin](https://apify.com/tidytools) (community)
- **Categories:** SEO tools, AI, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $120.00 / 1,000 successful ai engine queries

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 Answer Visibility Tracker

### What does it do?

Ask a live AI engine your buyers' questions and measure whether your brand appears. Gemini with Google Search grounding is available now. Perplexity support is prepared but **requires an API key to be enabled by the operator**; until then it returns a free `engine_unavailable` row. Each usable answer produces one `ANSWER` row. `SUMMARY` is saved to the key-value store and dataset.

### How to use

1. Enter your brand, website and up to 10 competitors.
2. Add up to 10 buyer questions. Category questions without your brand name (for example, "Which CDN should a small business use?") measure whether an engine recommends you. If left empty, 10 questions containing your brand name are generated to inspect how the engine describes you.
3. Choose `gemini` (default) and optionally `perplexity`. Set `samples` to 1–5 to repeat each question on each engine.
4. Run on a paid Apify plan. Review `brandMentioned`, `mentionPosition`, `citations` and `SUMMARY.shareOfVoice`. For missed mentions, follow `geoAuditUrl` to the GEO readiness audit.

Example: `{"brand":"Cloudflare","domain":"cloudflare.com","competitors":["Akamai","Fastly"],"queries":["Which CDN should a small business use?"],"engines":["gemini"],"samples":3}`.

### Input

- `brand`, `domain` (required): exact brand name and public website.
- `competitors`: up to 10 names.
- `queries`: up to 10 buyer questions; when empty, 10 brand questions are generated.
- `engines`: `gemini` (default); `perplexity` requires the operator's Worker API key.
- `samples`: 1–5 repeated answers per question and engine (default 1). Every successful sample is a separate engine query.

### Output

Each successful `ANSWER` has `brand`, `domain`, `query`, `engine`, `sample`, `checkedAt`, `success`, `brandMentioned`, `mentionPosition`, `competitorMentions`, `citations`, `answerSummary`, `grounded`, `providerCostUsd`, `geoAuditUrl`, and `charged`. Failed rows instead carry `errorType` and `error`. `mentionPosition` is the first appearance order among the monitored brand/domain and competitors in the answer text; it is **not** search-result rank. `citations` contains up to 20 source URLs. `charged` on a stored answer means charge eligible; confirmed charges are in the summary. `providerCostUsd` is the Perplexity API cost reported for that answer; Gemini has null.

`SUMMARY` has `status`, `queriesAttempted`, `successfulQueries`, `failedQueries`, `brandMentions`, `visibilityScore`, `competitors`, `shareOfVoice`, `brand`, `domain`, `engines`, `samples`, `chargedEvents`, `notProcessed`, `estimatedGrossUsd`, `geoAuditUrl`, `unavailableEngines`, and `availabilityNote`. `visibilityScore` is successful answers mentioning the brand divided by successful answers. `shareOfVoice` lists the brand and competitors with `name`, `mentions` and `sharePercent`; the denominator is all monitored-name mentions across successful answers, so one answer can count multiple brands. With no mentions, `sharePercent` is null. Failed samples are excluded.

### Cost and limitations

**$0.12 per successful engine query** (`engine-query`), including each repeated sample. Failed, unavailable, skipped and free-plan queries are free. A spending limit stops further queries. The default maximum is 10 questions × 1 engine × 1 sample = $1.20; selecting both engines and 5 samples makes the theoretical maximum $12.00.

Live engine calls require a **paid Apify plan**. Free-plan runs return up to three `paid_plan_required` explanation rows without contacting either provider or charging. Perplexity stays unavailable until its key is approved and installed. AI answers vary; repeated samples help expose variation but do not represent a search ranking. Exact-name matching does not count nicknames or misspellings. The GEO audit predicts readiness and cannot guarantee citation.

### FAQ

**Am I charged when an engine fails?** No. Only a saved, usable answer is charge eligible.

**Can I monitor weekly?** Yes. Save the input as a task, schedule it, and compare the summary over time.

# Actor input Schema

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

Exact public brand name to look for in answers.

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

Public domain or website URL.

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

Up to 10 exact brand names.

## `queries` (type: `array`):

Up to 10 questions. Leave empty to generate 10 from the brand and domain.

## `engines` (type: `array`):

gemini (live with Google Search). perplexity requires the Worker API key; without it, returns a free engine_unavailable row.

## `samples` (type: `integer`):

Repeat each buyer question 1–5 times per engine to measure answer variation. Each successful sample is one $0.12 event.

## Actor input object example

```json
{
  "brand": "Cloudflare",
  "domain": "cloudflare.com",
  "competitors": [
    "Akamai",
    "Fastly"
  ],
  "engines": [
    "gemini"
  ],
  "samples": 1
}
```

# Actor output Schema

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

No description

## `summary` (type: `string`):

No description

# 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": "Cloudflare",
    "domain": "cloudflare.com",
    "competitors": [
        "Akamai",
        "Fastly"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("tidytools/ai-answer-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": "Cloudflare",
    "domain": "cloudflare.com",
    "competitors": [
        "Akamai",
        "Fastly",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("tidytools/ai-answer-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": "Cloudflare",
  "domain": "cloudflare.com",
  "competitors": [
    "Akamai",
    "Fastly"
  ]
}' |
apify call tidytools/ai-answer-visibility --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tidytools/ai-answer-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/BedxKIqujmhiwJ4vg/builds/vPx3gp2I0HA0fJQfH/openapi.json