# Prism Share Of Voice API (https://www.socialcrawl.dev/platforms/prism/share-of-voice)

> Per brand, fans out to content_analysis summary/phrase-trends/sentiment plus /search/everywhere (consuming the real per-platform items_by_source counts, not the capped fused list), then computes a published-formula SOV (web + social, equal-weighted by default), optional true-share-of-category (numeric `category_code`), and ESOV (`market_shares`, Binet/Field: a planning signal, not a growth guarantee). The web share is divided from the windowed phrase-trends sum over `date_from`..`date_to`, never from the upstream's all-time `total_count`, which is censored at 4,000,000 and would tie any two brands above that cap at exactly 50/50; the all-time figure still rides along per brand as `web_mentions_all_time` with a `web_mentions_all_time_censored` flag. One axis is chosen for the whole table and named in `methodology.web_axis`, so a brand whose timeline is unavailable can never be compared against a rival's on a different footing; if no brand's timeline is available the table falls back to the all-time totals and `_warnings` states that your window was not applied, and if those totals are censored it returns no web share at all instead of a fabricated tie. Every measured brand is scored on the SAME evidence basis: if one brand's social leg returns nothing, the whole table drops to the axes every brand has, `methodology.basis` names it, and `_warnings` says which brand caused it, so the column is always a real share rather than a mix of formulas. `methodology` ships the weights, the formula, the axis and the denominators, so you can recompute any share by hand from the same payload. With the social leg on, each brand's highest-engagement social rows (up to `methodology.about_brand.max_rows_per_brand`) are also judged for whether they are about that brand at all, and a second set of numbers is published next to the first, never in place of it: `engagement_sum_about_brand`, `social_sov_pct_about_brand` and `sov_pct_about_brand` leave out the rows under `methodology.about_brand.about_brand_at_or_above`, and `per_brand[].about_brand` lists the excluded row ids, their engagement, and the negative mentions by aspect. The web axis is an index count and is not cleaned. If any brand's rows could not be judged the cleaned numbers are null for the whole table and `_warnings` says `about_brand_unavailable`. The price is the same either way. Metered at 40cr/brand (20 web-only); a brand whose social search half-failed is automatically cheaper, with the reason legible in `legs[]` + per-brand `coverage`.

TL;DR: `GET /v1/prism/share-of-voice` costs 40 credits per brand with the social leg, which is the default, or 20 per brand for the web-only read. Up to 5 brands per call, so the 200-credit ceiling is 5 brands with social and dropping `social` from `include` halves it. Price the call as `brands x per-brand` before you send it - this is the most expensive composite on the API and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `brands` | yes | 2-5 competitor brand names (CSV). |
| `category_code` | no | Numeric category-taxonomy code for true-share-of-category (look one up with `GET /v1/content_analysis/categories`). |
| `market_shares` | no | JSON map of real market share per brand (fraction or %), e.g. {"notion":0.4,"coda":0.25,"airtable":0.35}, to compute ESOV. |
| `include` | no | CSV toggles (default `emotions,social`). Drop `social` for the cheaper web-only variant; drop `emotions` to skip the sentiment leg. The emotion overlay is third-party NLP passed through unmodified and is not scoped to your date window; `methodology.sentiment_provenance` states that on every response that carries it. |
| `page_type` | no | Optional surface filter forwarded to the content_analysis legs. (ecommerce \| news \| blogs \| message-boards \| organization) |
| `date_from` | no | Window start (YYYY-MM-DD). Defaults to 90 days ago. |
| `date_to` | no | Window end (YYYY-MM-DD). Defaults to today. |
| `brand_descriptions` | no | Optional JSON map of a one-line description per brand, e.g. {"notion":"the workspace app"}, used to tell a brand apart from its namesakes. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/prism/share-of-voice" \
  --data-urlencode "brands=notion,coda,airtable" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### What is the SocialCrawl Share of Voice API?

GET /v1/prism/share-of-voice takes 2-5 brands and returns one ranked share-of-voice table where each brand's share is computed from real per-platform counts (web mention volume plus social engagement) and engagement-weighted with a published formula. No single endpoint computes a competitive share across brands.

### How is share of voice calculated?

Each brand gets a web_sov_pct (its mention volume over the total) and a social_sov_pct (its engagement over the total), blended 50/50 by default into sov_pct, which sums to roughly 1.0 across the set. The weights and dead-band are pinned in methodology_version so results are reproducible.

### What is ESOV and how do I get it?

ESOV (Excess Share of Voice) is share of voice minus real market share, times 100, the Binet/Field planning signal. Pass market_shares as a JSON map of brand to share and the endpoint computes esov per brand. It is a planning signal, not a growth guarantee.

### How much does a share-of-voice call cost?

Pricing is metered at 40 credits per brand for the full web-plus-social report, or 20 credits per brand for the web-only variant when you drop social from include. A brand whose social search half-failed is automatically cheaper, with the reason shown in its per-brand coverage and legs.

### Does share-of-voice use the real per-platform counts?

Yes. Social share is computed from items_by_source: the real per-platform counts and engagement from the universal search leg, not from a capped fused list, so the numbers reflect actual platform spread. Emotions come from NLP content analysis, and there is no LLM in the SOV math.

See the full Prism API: https://www.socialcrawl.dev/platforms/prism

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- What API computes share of voice across multiple brands?
- How do I measure ESOV and share of voice for competitors via API?
- engagement-weighted share of voice API with web and social split