## panorama/share-of-voice

`GET /v1/panorama/share-of-voice`

Compare 2–5 brands over bounded native social search samples. Mention shares use sources that answered for every brand; engagement shares also require observed counters on common sources. Fractions, evidence, source coverage and null denominators are explicit. Select supported sources with platforms; this is not total market share.

*Share of voice*

| Parameter | Required | Description |
| --- | --- | --- |
| `brands` | yes | 2–5 comma-separated brand or product names to compare — e.g. `deno,bun` |
| `platforms` | no | CSV of supported sources: reddit,hackernews,bluesky,github,x,tiktok,instagram,youtube,linkedin,threads,pinterest. Default the six example sources. Each remains subject to eligibility, funding, deadlines and limits. — e.g. `reddit,hackernews,x,tiktok,instagram,youtube` |
| `date_mode` | no | ranked (default) retains date-labelled matches; strict excludes unknown and out-of-window dates. — e.g. `strict` |
| `per_source_limit` | no | Integer 1–50, default25. Bounded sample per source; no full-platform count. — e.g. `25` |
| `lookback_days` | no | Integer1–366, default30. — e.g. `30` |
| `context` | no | Optional subject context, at most1000 characters. Adds a bounded hint from the caller’s positive context to native search and prioritises returned candidates; inspect query_plan and source queries. Also guides optional Jev classification where supported. No inferred aliases or identity guarantee. — e.g. `Mercury, the business banking service; not the planet.` |
| `relevance` | no | none (default) or jev. Optional funded classification on at most20 candidates per brand, balanced across sources within relevance tiers. All original evidence and sampled arithmetic remain available. Inspect selection and classified counts; capacity and funding can leave records unclassified. — e.g. `none` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. — e.g. `1` |

**Cost:** 5 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/panorama/share-of-voice?brands=deno%2Cbun" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "schema_version": "social-evidence-v2",
  "scope": "native_social_search_sample",
  "comparison": {
    "sources": [
      "hackernews"
    ]
  },
  "totals": {
    "comparable_mentions": 2,
    "comparable_engagement": 16
  },
  "brands": [
    {
      "brand": "My Brand",
      "mentions": 1,
      "comparable_mentions": 1,
      "share_of_mentions": 0.5,
      "share_of_engagement": 0.75,
      "evidence": [
        {
          "id": "101",
          "platform": "hackernews",
          "source": "hackernews",
          "title": "Using My Brand",
          "text": null,
          "url": "https://news.ycombinator.com/item?id=101",
          "canonical_url": "https://news.ycombinator.com/item?id=101",
          "author": {
            "id": null,
            "handle": "example_reader",
            "name": null,
            "url": null
          },
          "metrics": {
            "likes": null,
            "score": 10,
            "comments": 2,
            "reshares": null,
            "views": null,
            "interactions": 12,
            "complete_interactions": false
          },
          "engagement": 12,
          "created_at": "2026-09-18T12:00:00.000Z",
          "fetched_at": "2026-09-19T12:00:00.000Z",
          "date_status": "within_window",
          "relevance": {
            "method": "literal_subject_match",
            "classification": "keyword_match",
            "entity_verified": false
          },
          "provenance": [
            {
              "platform": "hackernews",
              "endpoint": "search",
              "query": "My Brand",
              "params": {
                "query": "My Brand"
              }
            }
          ]
        }
      ],
      "coverage": {
        "hackernews": {
          "status": "answered",
          "fetched": 1,
          "examined": 1,
          "returned": 1,
          "deduplicated": 0,
          "within_window": 1,
          "undated": 0,
          "outside_window": 0,
          "sample_cap": 25,
          "has_more": false,
          "date_mode": "strict"
        }
      },
      "query_plan": {
        "version": "panorama-context-query-v1",
        "subject": "My Brand",
        "query": "My Brand",
        "mode": "subject",
        "context_terms": [],
        "source_order": [
          "hackernews"
        ],
        "lanes": [
          {
            "platform": "hackernews",
            "query": "My Brand",
            "mode": "subject"
          }
        ],
        "literal_sources": [
          "hackernews"
        ],
        "context_sources": [],
        "max_requests_per_source": 1,
        "policy": "One bounded native search per source. Original subject remains the identity target; lexical matching is not proof of identity."
      },
      "matched_items": [],
      "candidate_items": [
        {
          "id": "101",
          "platform": "hackernews",
          "source": "hackernews",
          "title": "Using My Brand",
          "text": null,
          "url": "https://news.ycombinator.com/item?id=101",
          "canonical_url": "https://news.ycombinator.com/item?id=101",
          "author": {
            "id": null,
            "handle": "example_reader",
            "name": null,
            "url": null
          },
          "metrics": {
            "likes": null,
            "score": 10,
            "comments": 2,
            "reshares": null,
            "views": null,
            "interactions": 12,
            "complete_interactions": false
          },
          "engagement": 12,
          "created_at": "2026-09-18T12:00:00.000Z",
          "fetched_at": "2026-09-19T12:00:00.000Z",
          "date_status": "within_window",
          "relevance": {
            "method": "literal_subject_match",
            "classification": "keyword_match",
            "entity_verified": false
          },
          "provenance": [
            {
              "platform": "hackernews",
              "endpoint": "search",
              "query": "My Brand",
              "params": {
                "query": "My Brand"
              }
            }
          ]
        }
      ],
      "match_summary": {
        "status": "candidates_only",
        "collected_records": 1,
        "supported_matches": 0,
        "supported_useful_matches": 0,
        "lexical_candidates": 1,
        "unresolved_records": 0,
        "unrelated_records": 0,
        "scope": "returned_sample",
        "entity_verified": false,
        "policy": "No completed relevance classification in this illustration. The original records remain available; these are lexical candidates, not verified matches."
      }
    },
    {
      "brand": "Other Brand",
      "mentions": 1,
      "comparable_mentions": 1,
      "share_of_mentions": 0.5,
      "share_of_engagement": 0.25,
      "evidence": [
        {
          "id": "102",
          "platform": "hackernews",
          "source": "hackernews",
          "title": "Using Other Brand",
          "text": null,
          "url": "https://news.ycombinator.com/item?id=102",
          "canonical_url": "https://news.ycombinator.com/item?id=102",
          "author": {
            "id": null,
            "handle": "example_reader",
            "name": null,
            "url": null
          },
          "metrics": {
            "likes": null,
            "score": 2,
            "comments": 2,
            "reshares": null,
            "views": null,
            "interactions": 4,
            "complete_interactions": false
          },
          "engagement": 4,
          "created_at": "2026-09-18T12:00:00.000Z",
          "fetched_at": "2026-09-19T12:00:00.000Z",
          "date_status": "within_window",
          "relevance": {
            "method": "literal_subject_match",
            "classification": "keyword_match",
            "entity_verified": false
          },
          "provenance": [
            {
              "platform": "hackernews",
              "endpoint": "search",
              "query": "Other Brand",
              "params": {
                "query": "Other Brand"
              }
            }
          ]
        }
      ],
      "coverage": {
        "hackernews": {
          "status": "answered",
          "fetched": 1,
          "examined": 1,
          "returned": 1,
          "deduplicated": 0,
          "within_window": 1,
          "undated": 0,
          "outside_window": 0,
          "sample_cap": 25,
          "has_more": false,
          "date_mode": "strict"
        }
      },
      "query_plan": {
        "version": "panorama-context-query-v1",
        "subject": "Other Brand",
        "query": "Other Brand",
        "mode": "subject",
        "context_terms": [],
        "source_order": [
          "hackernews"
        ],
        "lanes": [
          {
            "platform": "hackernews",
            "query": "Other Brand",
            "mode": "subject"
          }
        ],
        "literal_sources": [
          "hackernews"
        ],
        "context_sources": [],
        "max_requests_per_source": 1,
        "policy": "One bounded native search per source. Original subject remains the identity target; lexical matching is not proof of identity."
      },
      "matched_items": [],
      "candidate_items": [
        {
          "id": "102",
          "platform": "hackernews",
          "source": "hackernews",
          "title": "Using Other Brand",
          "text": null,
          "url": "https://news.ycombinator.com/item?id=102",
          "canonical_url": "https://news.ycombinator.com/item?id=102",
          "author": {
            "id": null,
            "handle": "example_reader",
            "name": null,
            "url": null
          },
          "metrics": {
            "likes": null,
            "score": 2,
            "comments": 2,
            "reshares": null,
            "views": null,
            "interactions": 4,
            "complete_interactions": false
          },
          "engagement": 4,
          "created_at": "2026-09-18T12:00:00.000Z",
          "fetched_at": "2026-09-19T12:00:00.000Z",
          "date_status": "within_window",
          "relevance": {
            "method": "literal_subject_match",
            "classification": "keyword_match",
            "entity_verified": false
          },
          "provenance": [
            {
              "platform": "hackernews",
              "endpoint": "search",
              "query": "Other Brand",
              "params": {
                "query": "Other Brand"
              }
            }
          ]
        }
      ],
      "match_summary": {
        "status": "candidates_only",
        "collected_records": 1,
        "supported_matches": 0,
        "supported_useful_matches": 0,
        "lexical_candidates": 1,
        "unresolved_records": 0,
        "unrelated_records": 0,
        "scope": "returned_sample",
        "entity_verified": false,
        "policy": "No completed relevance classification in this illustration. The original records remain available; these are lexical candidates, not verified matches."
      }
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/panorama/share-of-voice#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/panorama/share-of-voice.json)