# Gemini Brand Visibility Tracker - Share of Voice & Citations (`tidytools/gemini-brand-visibility`) Actor

Ask Google-Search-grounded Gemini the category questions your buyers ask and see which brands it names: your brand vs competitors, mention order, cited URLs. $0.12 per successful query; failed queries free.

- **URL**: https://apify.com/tidytools/gemini-brand-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

## Gemini Brand Visibility Tracker — Share of Voice & Citations

### What does it do?

**Ask Google Gemini the category questions your buyers ask, and see which brands it recommends.** Each question ("What is the best issue tracker for a startup engineering team?") is sent to **Gemini with Google Search grounding**. For every answer you get whether your brand is named, its mention order against your competitors, which competitors were named, the source URLs Gemini cited and a short answer excerpt. `SUMMARY` adds up your **visibility score** and how many answers named each competitor: your share of voice in Gemini. Successful answers cost $0.12 each; failed answers are free.

This is a focused version of [AI Answer Visibility Tracker](https://apify.com/tidytools/ai-answer-visibility): the same engine and price, set up for brand-vs-competitor comparison on category questions written without your brand name.

### How to use

1. Enter **Your brand**, its website and up to 10 **Competitors to compare**.
2. Write up to 10 **Category questions** a buyer would ask, *without* your brand name. The prefilled example (Linear vs Jira, Asana and ClickUp) shows the format.
3. Run it on a paid Apify plan. Sort the dataset by `brandMentioned`, read `competitorMentions` to see who Gemini names instead of you, and open `citations` to see which pages it trusts.
4. Where your brand is missing, `geoAuditUrl` opens a GEO readiness audit for a fix plan. Save the input as a task and schedule it weekly to track `SUMMARY.visibilityScore` over time.

### Input

- `brand` and `domain` (required): your exact brand name and public website. The domain also counts as a mention when the answer text names it.
- `competitors`: up to 10 exact brand names.
- `queries`: up to 10 category questions. Questions without your brand name measure whether Gemini recommends you. Left empty, 10 questions that name your brand are generated ("What is Linear?", "What are alternatives to Linear?", ...); those show how Gemini describes you, not whether it recommends you.
- `engines`: keep the default `gemini`.

Example:

```json
{
  "brand": "Linear",
  "domain": "linear.app",
  "competitors": ["Jira", "Asana", "ClickUp"],
  "queries": ["What is the best issue tracker for a startup engineering team?"]
}
```

### Output

Each answer is one `ANSWER` row with `brand`, `domain`, `query`, `engine`, `checkedAt`, `success`, `brandMentioned`, `mentionPosition`, `competitorMentions`, `citations`, `answerSummary`, `grounded`, `geoAuditUrl` and `charged`. Failed rows have `success: false`, `errorType` and `error`.

```json
{
  "type": "ANSWER", "brand": "Linear", "domain": "linear.app",
  "query": "What is the best issue tracker for a startup engineering team?", "engine": "gemini",
  "success": true, "brandMentioned": true, "mentionPosition": 1, "competitorMentions": ["Jira"],
  "citations": ["https://..."], "answerSummary": "For a startup engineering team, Linear is ...",
  "grounded": true, "geoAuditUrl": null, "charged": true
}
```

The row above is an illustration (shortened excerpt and citations). In the engine's paid test on 2026-10-23 this question was answered with Google Search grounding and 9 cited sources, and the answer named both Linear and Jira.

- `mentionPosition` is the order of first appearances among your brand (or its domain) and the competitors in the answer text; it is **not** a search result rank.
- `citations` are the source URLs Gemini used (up to 20). Check `grounded` and `citations` before treating an answer as web evidence.
- `SUMMARY` (key-value store and the last dataset row) has `status`, `queriesAttempted`, `successfulQueries`, `failedQueries`, `brandMentions`, `visibilityScore` (`brandMentions / successfulQueries × 100`), `competitors` (each with its number of answers that named it), `chargedEvents`, `notProcessed` and `estimatedGrossUsd`.

### Control your cost

**$0.12 per successful Gemini answer** (`engine-query`, the same event and price as AI Answer Visibility Tracker). A question that gets no usable answer, fails or is skipped is not charged. Answers are saved before charging; `charged` in the dataset means charge eligible and `SUMMARY.chargedEvents` is the confirmed count. A spending limit stops further questions. The most one run can cost is 10 questions × $0.12 = $1.20; the prefilled example has 3 questions ($0.36).

Live Gemini answers need a **paid Apify plan**: each one is a paid, search-grounded model call. On the free plan, and when the untouched example input is run as is (Apify's automated test of the form), the run returns up to three free `paid_plan_required` rows and makes no Gemini call. Change the brand, a competitor or a question to run live answers.

### Limitations

- Gemini only (grounded with Google Search). ChatGPT, Perplexity and Claude are not covered; for them, use a tracker built for that engine.
- AI answers change between runs and between users; one run is a sample, not a ranking. Repeat the same questions over time to see a trend.
- Mentions are exact-name matches (case-insensitive, whole words); nicknames or misspellings are not counted.
- Up to 10 questions and 10 competitors per run.

### FAQ

**How is this different from AI Answer Visibility Tracker?** Same engine and price. This version is set up for share of voice: category questions without your brand, a competitor list, and a view that puts your brand next to the competitors Gemini named.

**Why did my run return `paid_plan_required` rows on a paid plan?** The input was the untouched example, which is kept free for Apify's automated tests. Change any field and run again.

**Am I charged when Gemini fails?** No. Only saved, usable answers are charged.

# Actor input Schema

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

Exact public brand name to look for in Gemini's answers.

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

Public domain or website URL; it also counts as a mention when the answer text names it.

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

Up to 10 exact brand names. Each answer shows which of them Gemini named and in what order, next to your brand.

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

Up to 10 questions a buyer would ask Gemini, written without your brand name, so the answers show whether Gemini recommends you. Each successful answer is one $0.12 query. Left empty, 10 questions that name your brand are generated (they check how Gemini describes you, not whether it recommends you).

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

gemini: a live Gemini answer grounded with Google Search. Keep the default.

## Actor input object example

```json
{
  "brand": "Linear",
  "domain": "linear.app",
  "competitors": [
    "Jira",
    "Asana",
    "ClickUp"
  ],
  "queries": [
    "What is the best issue tracker for a startup engineering team?",
    "Which project management tool do software teams switch to from Jira?",
    "What is a good bug tracking tool for a small SaaS company?"
  ],
  "engines": [
    "gemini"
  ]
}
```

# Actor output Schema

## `answers` (type: `string`):

No description

## `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": "Linear",
    "domain": "linear.app",
    "competitors": [
        "Jira",
        "Asana",
        "ClickUp"
    ],
    "queries": [
        "What is the best issue tracker for a startup engineering team?",
        "Which project management tool do software teams switch to from Jira?",
        "What is a good bug tracking tool for a small SaaS company?"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("tidytools/gemini-brand-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": "Linear",
    "domain": "linear.app",
    "competitors": [
        "Jira",
        "Asana",
        "ClickUp",
    ],
    "queries": [
        "What is the best issue tracker for a startup engineering team?",
        "Which project management tool do software teams switch to from Jira?",
        "What is a good bug tracking tool for a small SaaS company?",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("tidytools/gemini-brand-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": "Linear",
  "domain": "linear.app",
  "competitors": [
    "Jira",
    "Asana",
    "ClickUp"
  ],
  "queries": [
    "What is the best issue tracker for a startup engineering team?",
    "Which project management tool do software teams switch to from Jira?",
    "What is a good bug tracking tool for a small SaaS company?"
  ]
}' |
apify call tidytools/gemini-brand-visibility --silent --output-dataset

```

## MCP server setup

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