---
title: "Engagement-weighted Share of Voice across 2-5 brands, with web+social split, emotion overlay, and ESOV."
method: GET
path: "/prism/share-of-voice"
tags: ["prism"]
---

# Engagement-weighted Share of Voice across 2-5 brands, with web+social split, emotion overlay, and ESOV.

`GET /prism/share-of-voice`

## Request

- Base URL: `https://www.socialcrawl.dev/v1`
- URL: `https://www.socialcrawl.dev/v1/prism/share-of-voice`
- Auth: API key in header `x-api-key`

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`.

## Query parameters

- `brands` string, required
- `category_code` string
- `market_shares` string
- `include` string
- `page_type` 'ecommerce' | 'news' | 'blogs' | 'message-boards' | 'organization'
- `date_from` string
- `date_to` string
- `brand_descriptions` string

## Headers

- `Cache-Control` string
- `Idempotency-Key` string

## Response `200`

Successful response

- object
  - `success` boolean, required: Whether the request succeeded
  - `platform` string, required: Platform name
  - `endpoint` string, required: API endpoint path
  - `data` object, required: Platform-specific response data
    - `metrics` object: Key performance metrics
      - `total_views` integer: Total view count
      - `total_likes` integer: Total like count
      - `total_comments` integer: Total comment count
      - `engagement_rate` number: Computed engagement rate (0-1)
    - `period` string, nullable: Time period for the analytics data
    - `breakdown` object[], nullable: Per-item or per-period breakdown
    - `_warnings` string[]: Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.
  - `credits_used` integer, required: Number of credits consumed
  - `credits_remaining` integer, nullable, required: Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.
  - `request_id` string, required: Unique request identifier for support
  - `cached` boolean, required: Whether the response was served from cache
  - `idempotent_replay` boolean: True only when this response is an idempotency replay
  - `meta` object: Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.
    - `hint` object: One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.
      - `code` string: creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat
      - `message` string: One sentence for a person or an agent to read.
      - `method` string: GET or POST.
      - `path` string: The call the hint points to.

## Other responses

- `400`: Invalid request - missing or malformed parameters
- `401`: Unauthorized - missing or invalid API key
- `402`: Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit
- `404`: Not found - the endpoint does not exist, or the requested resource was not found upstream
- `405`: Method not allowed - wrong HTTP verb for this endpoint
- `409`: Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation
- `410`: Gone - the discover run's retention passed and its rows were deleted; start a new run
- `413`: Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling
- `422`: Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)
- `429`: Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.
- `500`: Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit
- `502`: Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge
- `503`: Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge
- `504`: Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After

---

[API](https://skmtc.dev/socialcrawl/apis/socialcrawl-api.md) · [All operations](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/revisions/a0ad2511004a?raw)