# AI Brand Visibility & Citation Audit API (`overbifrost/ai-brand-visibility-citation-audit-api`) Actor

Audit how your brand and competitors appear in OpenAI and Claude web-search API answers. Capture mentions, citations, competitor gaps, cited domains, answer coverage, and inspectable evidence. BYOK. Only completed provider observations are billed

- **URL**: https://apify.com/overbifrost/ai-brand-visibility-citation-audit-api.md
- **Developed by:** [Lasse](https://apify.com/overbifrost) (community)
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $16.00 / 1,000 completed ai observations

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 Brand Visibility & Citation Auditor

**Audit brand and competitor visibility in AI API answers — with inspectable evidence.**

Run your exact prompts through supported provider APIs, capture the returned answer and citations,
and get structured findings linked to the evidence behind them. Every requested observation produces one
auditable row — including the ones that failed, were blocked, or could not
run, so nothing is silently dropped.

### How it works

1. **You provide the prompts** — verbatim; The Actor never generates, rewrites,
   or discovers prompts.
2. **You declare identities** — your brand (name, optional aliases and
   domains) and optionally explicit competitors. The Actor never guesses or
   discovers competitors.
3. **You choose automated provider surfaces** — and supply your own API key for each selected
   provider (BYOK). The Actor performs the acquisition for you.
4. **You get one row per observation** — answer text, normalized citations,
   requested vs. applied scope, coverage, findings, diagnostics, provenance.

### Public beta scope

The launch form intentionally exposes more than one provider, but only providers that have passed their live acceptance checks should be published. The current public-beta target is **OpenAI + Anthropic Claude**. Gemini and Perplexity remain implemented or reserved routes, not part of the public launch promise.

### Answer surfaces

| Surface ID | What it is | Status |
| --- | --- | --- |
| `OPENAI_SEARCH_API` | OpenAI Responses API + web search (BYOK) | **Public beta** — live acceptance still required before Store publication |
| `CLAUDE_WEB_SEARCH_API` | Anthropic Claude Messages API + web search (BYOK) | **Public beta** — live acceptance still required before Store publication |
| `GEMINI_GROUNDED_API` | Google Gemini API with Search grounding | **Not in public beta** — hidden pending commercial terms review |
| `PERPLEXITY_AGENT_API` | Perplexity Agent API (BYOK) | **Gated** — not in public beta pending live verification |
| `CHATGPT_CONSUMER` | ChatGPT consumer product | **Capture-only** — paste an observed answer; no automated acquisition |
| `GEMINI_CONSUMER` | Gemini consumer product | **Capture-only** — paste an observed answer; no automated acquisition |
| `PERPLEXITY_CONSUMER` | Perplexity consumer product | **Capture-only** — paste an observed answer; no automated acquisition |
| `CLAUDE_CONSUMER` | Claude consumer product | **Capture-only** — paste an observed answer; no automated acquisition |
| `COPILOT_CONSUMER` | Microsoft Copilot consumer product | **Capture-only** — paste an observed answer; no automated acquisition |
| `GOOGLE_AI_MODE_PUBLIC` | Public Google AI Mode product surface | **Capture-only**; automated acquisition remains disabled |
| `GOOGLE_AI_OVERVIEWS_PUBLIC` | Public Google AI Overviews surface | **Capture-only**; automated acquisition remains disabled |

Provider API output is provider API output — a run against
`OPENAI_SEARCH_API` is never presented as a captured ChatGPT consumer
session, and the same applies to the other surfaces.

### What each row contains

- `status` — `COMPLETE`, `PARTIAL`, `BLOCKED`, `FAILED`, `NOT_RUN`, or
  `UNSUPPORTED`.
- `answer.coverage` / `citations.coverage` — independent coverage states.
  A partial or failed observation can never become a "not mentioned" or
  "not cited" finding.
- `requestedScope` vs. `appliedScope` — scope is only claimed as applied
  where the surface actually supports it.
- `findings` — deterministic, evidence-tagged verdicts (e.g.
  `TARGET_BRAND_MENTIONED`, `COMPETITOR_CITED_WHILE_TARGET_NOT_CITED`,
  `REPEATED_CITED_DOMAIN_IN_CHECKED_SCOPE`).
- `upstreamProvenance` — provider, API family, model/preset, request ID,
  executed search queries, token usage.
- `diagnostics` — sanitized, structured reasons for anything that did not
  happen.

### Credentials and cost — read before running

- **BYOK is the standard workflow.** Public-beta providers require your own API key, supplied as an encrypted secret input field (`openaiApiKey` or `anthropicApiKey`). Keys are sent only to that provider's
  API and are never written to the Dataset, key-value store, logs, or
  diagnostics.
- **Two separate costs.** Provider usage (searches, tokens) is billed by the
  provider to *your* account and is reported back as provider-reported
  telemetry — it is outside this Actor's charge cap. Separately, the Actor
  uses Apify pay-per-event pricing: one `observation-evaluated` event per
  `COMPLETE` observation. `PARTIAL`, `BLOCKED`, `FAILED`, `NOT_RUN`, and
  `UNSUPPORTED` observations are never charged.
- An uncertain charge outcome is recorded as unknown and stops billing —
  the Actor prefers possible underbilling over any risk of a double charge.
  Every unit is recorded in the run's `CHARGE_JOURNAL`.

### Advanced import

`USER_SUPPLIED_CAPTURE` remains available through JSON/API for debugging, migration and importing
an answer that was observed elsewhere. It is intentionally hidden from the normal Console form and
is not presented as a free alternative to automated acquisition.

### Limits

Hard bounds always apply: 100 prompts, 25 competitors, 5 surfaces,
25 scopes, 5 samples, 500 observations and 500 provider requests per run,
3 retries per observation, 1-hour run deadline. The `limits` object can
tighten these further.

### What CiteGap is not

No dashboard, no prompt or persona generation, no competitor discovery, no
sentiment scoring, no recommendations, no cited-page crawling, no
monitoring, no universal "visibility score", and no claims about durable AI
rankings — single observations are single observations.

### Output

- **Dataset** — one row per requested observation (see *What each row
  contains*). Switch to the **Findings** view for one row per finding.
- **Key-value store** — `RUN_SUMMARY` (counts, outcomes, billing mode, cost
  state), `EVIDENCE_MANIFEST`, `CHARGE_JOURNAL`.

### Input reference (API / advanced use)

| Field | Type | Notes |
| --- | --- | --- |
| `captures` | object\[] | Advanced JSON/API import only for already-observed answers; hidden from the normal Console form |
| `prompts` | string\[] | Exact prompts for automated acquisition, 1–100; optional with captures |
| `target` | object | `{name, aliases?, domains?}` — the audited brand |
| `competitors` | object\[] | Optional explicit list, max 25 |
| `surfaces` | string\[] | Automated surface requests, 1–5; optional with captures |
| `scopes` | object\[] | Optional `{country?, region?, city?, timezone?, language?}`, max 25 |
| `samplesPerObservation` | integer | 1–5, default 1 |
| `openaiApiKey` / `anthropicApiKey` | string | Secret BYOK fields shown in Console for public-beta providers |
| `geminiApiKey` / `perplexityApiKey` | string | Hidden/reserved fields while those routes remain outside the public beta |
| `credentials` | object | Equivalent nested shape for API use |
| `limits` | object | Optional tightened caps |

### Permissions

The Actor runs with limited permissions: it writes only to its own run
storage. Automated observations make HTTPS calls only to the selected provider APIs. Advanced
user-supplied imports make no provider request. Customer web targets are never fetched. No browser
automation is used.

# Actor input Schema

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

Enter the exact questions you want the Actor to send to the selected provider APIs.

## `target` (type: `object`):

The brand or company to audit. Name is required; aliases and domains improve deterministic matching.

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

Optional competitors to compare against. Add one card per competitor; the Actor does not discover competitors automatically.

## `surfaces` (type: `array`):

Choose one or more launch providers for automated acquisition. These are API answer surfaces, not captured consumer-app sessions.

## `scopes` (type: `array`):

Optional market context. Leave this empty to use each provider's default context. CiteGap reports requested scope separately from what the provider actually accepted or confirmed.

## `samplesPerObservation` (type: `integer`):

How many independent API answers to collect for each prompt × surface × scope. Keep 1 for normal audits; higher values increase provider usage.

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

Required when OpenAI is selected. Create an API key in your OpenAI API account. The key is sent only to OpenAI and is never written to output or logs.

## `anthropicApiKey` (type: `string`):

Required when Anthropic Claude is selected. Create an API key in the Anthropic Console. The key is sent only to Anthropic and is never written to output or logs.

## `geminiApiKey` (type: `string`):

Reserved for the Gemini adapter. Hidden from the public beta form while the Google-grounded commercial terms review remains open.

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

Reserved for Perplexity Agent API. The surface is currently gated, so the key is not needed for normal runs.

## `credentials` (type: `object`):

Programmatic alternative to the top-level secret fields. Hidden from the Console form; API callers may still supply it.

## `limits` (type: `object`):

Optional stricter safety caps. Most users should keep the built-in defaults.

## `captures` (type: `array`):

Advanced JSON/API import path for already-observed consumer/public answers. Hidden from the normal Console form; this is not the standard CiteGap workflow.

## Actor input object example

```json
{
  "samplesPerObservation": 1
}
```

# Actor output Schema

## `observations` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

## `evidenceManifest` (type: `string`):

No description

## `chargeJournal` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("overbifrost/ai-brand-visibility-citation-audit-api").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("overbifrost/ai-brand-visibility-citation-audit-api").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 '{}' |
apify call overbifrost/ai-brand-visibility-citation-audit-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,overbifrost/ai-brand-visibility-citation-audit-api"
        }
    }
}
```

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/R3iy9ae9shh0ILJBY/builds/G3Mc3lIlBrR01SR7C/openapi.json