AI Visibility Competitor Share of Voice

Turn AI-answer observations you already own into one deterministic competitive visibility report. Compare your target brand with up to ten competitors across model family, market, and language—without calling an LLM, crawling a website, or sending data outside Apify.

What this Actor does

Each successful run writes exactly one complete row to the default Dataset. It includes visibility, configured-entity share of voice, first-position rate, average position, a deterministic competitor ranking, and bounded breakdowns by model family, market, and language. Every percentage retains its numerator and denominator.

The result is designed for recurring client reports, dashboard ingestion, competitive benchmarking, and before/after comparisons where repeatability matters more than opaque scoring.

Who this is for

AI-search marketers, agencies, analysts, and measurement teams that already own normalized observations and need a repeatable competitive summary.

The business question it answers

For the exact supplied sample: how often was the target mentioned, how did configured competitors compare, which competitor led, and how did the result vary by model family, market, and language?

Input: inline observations

Run the public Task compare-ai-visibility-share-of-voice (Task ID fEJHMBaHfH2exSoeW). Its fictional Acme prefill contains six normalized observations and produces one complete example report with no provider API key or private Dataset reference.

For your own analysis, supply 2–500 observations directly in observations. The smallest valid shape contains two rows:

{
  "schemaVersion": "1.0",
  "analysisId": "acme-q4-benchmark",
  "targetBrand": "Acme",
  "competitors": ["Beta", "Gamma"],
  "observations": [
    {
      "schemaVersion": "1.0",
      "observationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "brand": "Acme",
      "competitors": ["Beta"],
      "modelFamily": "ChatGPT",
      "market": "US",
      "language": "en",
      "mentioned": true,
      "position": 1
    },
    {
      "schemaVersion": "1.0",
      "observationId": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "brand": "Acme",
      "competitors": ["Gamma"],
      "modelFamily": "Gemini",
      "market": "US",
      "language": "en",
      "mentioned": false,
      "position": null
    }
  ],
  "maximumSegmentsPerDimension": 10
}

The repeated-character IDs above illustrate the required 64-character lowercase SHA-256 shape; use immutable content hashes in production.

Exact observation contract

Field	Required	Meaning
schemaVersion	Yes	Input contract version; currently 1.0.
analysisId	Yes	Your stable identifier for this analysis.
targetBrand	Yes	Canonical target label shared by every observation.
competitors	Yes	One to ten unique canonical competitor labels.
observations	Yes	Two to 500 normalized observations supplied inline.
maximumSegmentsPerDimension	Yes	Required API display cap from 1 to 20; the UI prefill is 10.

Each observation supplies its immutable ID, target label, ordered mentioned competitors, model family, market, language, target mention boolean, and target position or null. Compatible producer extras are ignored. Unknown, duplicate, partial, ambiguous, or internally inconsistent input fails before output. Source Dataset references are not accepted.

Metrics and formulas

• Visibility rate = entity mentions ÷ eligible observations.
• Share of voice = entity mentions ÷ all target-plus-configured-competitor mentions.
• First-position rate = first positions ÷ positioned mentions.
• Average position = position sum ÷ positioned mentions.

All displayed values use integer half-up rounding.

Overall and segment completeness

Overall metrics always include every accepted unique observation. Model-family, market, and language groups are ordered deterministically and bounded by maximumSegmentsPerDimension. SEGMENTS_TRUNCATED declares omitted display groups; it never hides source truncation.

Output schema

The default Dataset receives one closed report object:

{
  "schemaVersion": "ai-visibility-competitor-share-of-voice-report-1.0",
  "reportId": "823054fffa8e6d22b86efbe4b8f4540869a5658e1e831fa26bd1873737592c6b",
  "analysisId": "acme-ai-sov-2026-q4",
  "status": "COMPLETE",
  "targetBrand": "Acme",
  "competitors": ["Beta", "Gamma"],
  "source": {
    "mode": "INLINE",
    "suppliedObservationCount": 6,
    "acceptedUniqueObservationCount": 6
  },
  "overall": {
    "observationCount": 6,
    "totalEntityMentions": 11
  }
}

The complete row also contains entity-level fractions, formatted percentages, ranking, segment items, limitations, and exact billing facts. No KVS OUTPUT, HTML, CSV, webhook, secondary Dataset, or synthetic diagnostic row is written.

Pricing and paid unit

Pay Per Event charges the platform Actor Start event and one result-found event only after the complete report is durably delivered.

Tier	Actor start	Complete report	Maximum total
Free	$0.006000	$0.019000	$0.025000
Bronze	$0.005700	$0.018050	$0.023750
Silver	$0.005400	$0.017100	$0.022500
Gold	$0.005100	$0.016150	$0.021250
Platinum	$0.004920	$0.015580	$0.020500
Diamond	$0.004800	$0.015200	$0.020000

Invalid or incomplete work emits no result-found event. The public Task caps total charge at $0.025, enough for exactly one report at every tier.

Use with Make, n8n and the API

Start the public Task through the Apify API:

curl -X POST \
  "https://api.apify.com/v2/actor-tasks/fEJHMBaHfH2exSoeW/runs?token=YOUR_APIFY_TOKEN&waitForFinish=120"

Read defaultDatasetId from the returned Run and fetch that Dataset's single item. In Make or n8n, use the same endpoint, wait for a terminal status, and pass the row to your reporting or warehouse step. Check the original Run before retrying a timed-out request so a completed paid run is not duplicated.

Privacy, rights and retention

• The Actor runs with limited permissions and accepts inline observations only.
• It requests no provider tokens, cookies, proxies, Dataset access, or arbitrary Run IDs.
• It makes no external network, model, search, or child-Actor calls.
• You must own or be authorized to process the supplied observations and labels.
• Extra prose, citations, and PII-like fields are not promoted into the output contract.

Limitations

This report covers only the supplied sample and configured entities. It does not measure sentiment, citations, recommendation quality, universal model coverage, traffic, market share, conversion, revenue, or causation. Competitor positions are reconstructed only from the supplied ordered mentions and target position.

Troubleshooting

• Input fails immediately: verify every observation ID is unique, labels match the top-level configuration, and the Input contains 2–500 rows.
• Position is rejected: ensure position agrees with the target and ordered competitor mentions; use null when the target is not mentioned.
• No report is written: inspect the Run error, correct the Input, and confirm the charge limit covers the current tier before starting a new run.
• Some segment groups are absent: raise maximumSegmentsPerDimension; overall metrics are never truncated.

FAQ

Does it collect live AI answers? No. It analyzes normalized observations you supply.

Can overall metrics be truncated? No. Only bounded segment presentation can be truncated.

Why retain numerators and denominators? They make percentages auditable and allow downstream aggregation without reverse-engineering rounded values.

Can one run produce several reports? No. One successful run produces exactly one complete report and at most one result-found event.