Panorama share-of-voice API

Endpoint

GET/v1/panorama/share-of-voicelive · provenUp to 5 credits

Parameters

Query parameters

Name	Required	Description	Example
`brands`	yes	2–5 comma-separated brand or product names to compare	`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.	`reddit,hackernews,x,tiktok,instagram,youtube`
`date_mode`	no	ranked (default) retains date-labelled matches; strict excludes unknown and out-of-window dates.	`strict`
`per_source_limit`	no	Integer 1–50, default25. Bounded sample per source; no full-platform count.	`25`
`lookback_days`	no	Integer1–366, default30.	`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.	`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.	`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.	`1`

Examples

Make the request

curl

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

TypeScript

typescript

const key = process.env.MONOCRAWL_API_KEY;
if (!key) throw new Error('Set MONOCRAWL_API_KEY on your server.');
const res = await fetch(
  "https://www.monocrawl.com/v1/panorama/share-of-voice?brands=deno%2Cbun",
  { headers: { "x-api-key": key } },
);
const body = await res.json();

if (!body.success) {
  // one error shape for every endpoint — see /docs/errors
  throw new Error(`${body.error.type}: ${body.error.message}`);
}

console.log(body.data, "credits left:", body.credits_remaining);

Python

python

import os
import requests

res = requests.get(
    "https://www.monocrawl.com/v1/panorama/share-of-voice?brands=deno%2Cbun",
    headers={"x-api-key": os.environ["MONOCRAWL_API_KEY"]},
    timeout=60,
)
body = res.json()

if not body["success"]:
    # one error shape for every endpoint — see /docs/errors
    raise RuntimeError(f"{body['error']['type']}: {body['error']['message']}")

print(body["data"], "credits left:", body["credits_remaining"])

Response

Response fields and example

This example is illustrative, not a captured live response. Variable-cost operations may settle a charge different from the list price below. A successful response puts the platform payload in data and reports the exact credits used, remaining balance, request id and cache status beside it.

200 · application/json

{
  "success": true,
  "platform": "panorama",
  "endpoint": "/v1/panorama/share-of-voice",
  "data": {
    "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."
        }
      }
    ]
  },
  "credits_used": 5,
  "credits_remaining": 99,
  "request_id": "req_…",
  "cached": false
}

The example uses fictional values and shows a documented subset of data. The fields below are optional across supported sources; nullable fields can also be absent. Preserve unknown values and accept additional fields.

Download the data JSON Schema. Validate response.data, not the whole envelope. A valid shape does not establish that every field or source record was returned.

Field inside data	Type	Meaning
`schema_version`	`string \| null`	social-evidence-v2.
`scope`	`string \| null`	native_social_search_sample, not a full platform mention count.
`window`	`object`	Nested response fields; optional unless explicitly documented.
`window.from`	`string \| null`	Window start.
`window.to`	`string \| null`	Window end.
`window.date_mode`	`string \| null`	ranked retains date-labelled results; strict excludes undated and out-of-window rows.
`coverage`	`object`	Nested response fields; optional unless explicitly documented.
`brands`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].brand`	`string \| null`	Compared name.
`brands[].mentions`	`number \| null`	Bounded observed sample count.
`brands[].comparable_mentions`	`number \| null`	Sample mentions on common sources.
`brands[].share_of_mentions`	`number \| null`	Brand common-source mentions / all compared brand common-source mentions; 0–1 fraction, null if unavailable.
`brands[].share_of_engagement`	`number \| null`	Observed interaction share, 0–1 fraction; missing inputs excluded and views separate.
`brands[].evidence`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].evidence[].id`	`string \| null`	Native record identifier; preserve exact case and value.
`brands[].evidence[].platform`	`string \| null`	Platform id.
`brands[].evidence[].source`	`string \| null`	Collection lane.
`brands[].evidence[].title`	`string \| null`	Original title.
`brands[].evidence[].text`	`string \| null`	Original text.
`brands[].evidence[].url`	`string \| null`	Original link.
`brands[].evidence[].canonical_url`	`string \| null`	Deduplication URL preserving source identity.
`brands[].evidence[].author`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].evidence[].author.id`	`string \| null`	Author id.
`brands[].evidence[].author.handle`	`string \| null`	Public username.
`brands[].evidence[].author.name`	`string \| null`	Display name.
`brands[].evidence[].author.url`	`string \| null`	Author link.
`brands[].evidence[].metrics`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].evidence[].metrics.likes`	`number \| null`	Native likes or null.
`brands[].evidence[].metrics.score`	`number \| null`	Native net score; can be negative.
`brands[].evidence[].metrics.comments`	`number \| null`	Native comments or replies.
`brands[].evidence[].metrics.reshares`	`number \| null`	Native reposts/reshares.
`brands[].evidence[].metrics.views`	`number \| null`	Native views; separate from interactions.
`brands[].evidence[].metrics.interactions`	`number \| null`	Documented interaction total when available.
`brands[].evidence[].metrics.complete_interactions`	`boolean \| null`	All inputs for the interaction total are known.
`brands[].evidence[].engagement`	`number \| null`	Observed interaction sum; inspect metrics for original counters. This value is not a cross-platform ranking score.
`brands[].evidence[].created_at`	`string \| null`	Publication timestamp or null.
`brands[].evidence[].fetched_at`	`string \| null`	Collection timestamp.
`brands[].evidence[].date_status`	`string \| null`	within_window, outside_window or undated.
`brands[].evidence[].relevance`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].evidence[].relevance.method`	`string \| null`	literal_subject_match or jev.
`brands[].evidence[].relevance.classification`	`string \| null`	keyword_match, subject_match, unrelated or needs_review. Lexical matching is not identity verification.
`brands[].evidence[].relevance.entity_verified`	`boolean \| null`	False for keyword-only matching.
`brands[].evidence[].relevance.model`	`string \| null`	Model identifier when classified.
`brands[].evidence[].relevance.version`	`string \| null`	Classifier version.
`brands[].evidence[].relevance.status`	`string \| null`	classified or unavailable for optional Jev analysis.
`brands[].evidence[].relevance.reason`	`string \| null`	Reason analysis was unavailable.
`brands[].evidence[].relevance.identity`	`string \| null`	yes, no or uncertain.
`brands[].evidence[].relevance.identity_support`	`number \| null`	Model support0–1, not a calibrated correctness probability.
`brands[].evidence[].relevance.discussion`	`string \| null`	substantive, incidental, adjacent, unrelated or uncertain.
`brands[].evidence[].relevance.discussion_support`	`number \| null`	Model support0–1.
`brands[].evidence[].relevance.usefulness`	`string \| null`	evidence, question, capability, passing or unclear.
`brands[].evidence[].relevance.usefulness_support`	`number \| null`	Model support0–1.
`brands[].evidence[].relevance.evidence_scope`	`string \| null`	returned_title_and_text; attached context is separate reading evidence.
`brands[].evidence[].provenance`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].evidence[].provenance[].platform`	`string \| null`	Original platform.
`brands[].evidence[].provenance[].endpoint`	`string \| null`	Original endpoint.
`brands[].evidence[].provenance[].query`	`string \| null`	Query used.
`brands[].evidence[].provenance[].params`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].evidence[].context_evidence`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].evidence[].context_evidence.kind`	`string \| null`	comments or transcripts.
`brands[].evidence[].context_evidence.status`	`string \| null`	answered, unavailable or invalid_response.
`brands[].evidence[].context_evidence.items`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].evidence[].context_evidence.items[].id`	`string \| null`	Original comment identifier.
`brands[].evidence[].context_evidence.items[].text`	`string \| null`	Readable comment text; YouTube HTML formatting is converted to plain text.
`brands[].evidence[].context_evidence.items[].url`	`string \| null`	Original comment URL.
`brands[].evidence[].context_evidence.items[].created_at`	`string \| null`	Original publication timestamp or null.
`brands[].evidence[].context_evidence.items[].date_status`	`string \| null`	within_window or outside_window against the disclosed context window; undated without a publication timestamp; not_evaluated if no valid window was supplied.
`brands[].evidence[].context_evidence.window`	`object \| null`	Nested response fields; optional unless explicitly documented.
`brands[].evidence[].context_evidence.window.from`	`string \| null`	Explicit parent query-window start.
`brands[].evidence[].context_evidence.window.to`	`string \| null`	Explicit parent query-window end.
`brands[].evidence[].context_evidence.excluded_parent_records`	`number \| null`	X records excluded because native ID or canonical URL matched the parent post, not actual replies.
`brands[].evidence[].context_evidence.counted_as_mentions`	`boolean \| null`	False: contextual comments do not add mentions to the search sample.
`brands[].evidence[].context_evidence.sample_cap`	`number \| null`	At most 10 returned comments per selected parent.
`brands[].evidence[].source_rank`	`number \| null`	One-based original source page position before non-content filtering and deduplication; null for legacy evidence or separately attached context.
`brands[].coverage`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].comparable_engagement`	`number \| null`	Observed interactions on the common engagement sources, or null when unavailable.
`brands[].ranking`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].ranking.version`	`string \| null`	panorama-source-diverse-v2.
`brands[].ranking.order`	`string \| null`	Relevance tier, authored-content priority, balanced source lanes, context overlap, then native source rank.
`brands[].ranking.relevance_tiers`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].ranking.source_order`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].ranking.records`	`number \| null`	Number of records ordered, before any top-evidence preview limit.
`brands[].ranking.per_source`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].ranking.per_tier`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].ranking.source_rank_basis`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].ranking.source_rank_basis.record_source_rank`	`number \| null`	Records with original one-based page rank.
`brands[].ranking.source_rank_basis.input_source_order`	`number \| null`	Legacy records using encounter order within their source.
`brands[].ranking.accounting_policy`	`string \| null`	Ordering leaves collected evidence, sample counts and billing unchanged.
`brands[].ranking.relevance_policy`	`string \| null`	Lexical cues are candidates, not entity verification.
`brands[].ranking.repeated_text_records`	`number \| null`	Repeated long authored text deferred within a relevance tier, not deleted or counted as an independent opinion.
`brands[].relevance_analysis`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].relevance_analysis.method`	`string \| null`	jev.
`brands[].relevance_analysis.model`	`string \| null`	Configured model identifier.
`brands[].relevance_analysis.version`	`string \| null`	Classification prompt version.
`brands[].relevance_analysis.examined`	`number \| null`	Selected records, including those whose analysis was unavailable.
`brands[].relevance_analysis.classified`	`number \| null`	Records with complete valid classification answers.
`brands[].relevance_analysis.batches`	`number \| null`	Attempted bounded classification batches.
`brands[].relevance_analysis.status`	`string \| null`	complete, partial, unavailable or no_candidates; complete means all selected candidates were classified, not the full pool.
`brands[].relevance_analysis.unavailable`	`number \| null`	Selected records whose classification did not complete.
`brands[].relevance_analysis.remaining_unclassified`	`number \| null`	All collected records without completed classification, including failed selected candidates.
`brands[].relevance_analysis.selection`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].relevance_analysis.selection.version`	`string \| null`	Ranking version.
`brands[].relevance_analysis.selection.limit`	`number \| null`	Maximum candidates; Jev at most20 per brand, enrichment at most3.
`brands[].relevance_analysis.selection.collected`	`number \| null`	Collected records supplied to selection.
`brands[].relevance_analysis.selection.eligible`	`number \| null`	Records not explicitly classified unrelated.
`brands[].relevance_analysis.selection.selected`	`number \| null`	Records selected for attempted interpretation.
`brands[].relevance_analysis.selection.remaining_eligible`	`number \| null`	Eligible records outside the selection allowance.
`brands[].relevance_analysis.selection.explicitly_unrelated_not_selected`	`number \| null`	Unrelated records retained in the response without using interpretation slots.
`brands[].relevance_analysis.selection.per_source`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].relevance_analysis.selection.per_tier`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].relevance_analysis.selection.order`	`string \| null`	Selection ordering policy.
`brands[].relevance_analysis.selection.evidence_preserved`	`boolean \| null`	True; candidate selection does not filter the evidence response.
`brands[].relevance_analysis.metrics_policy`	`string \| null`	Labels are additive; sample arithmetic is unchanged.
`brands[].top_evidence`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].top_evidence[].id`	`string \| null`	Native record identifier; preserve exact case and value.
`brands[].top_evidence[].platform`	`string \| null`	Platform id.
`brands[].top_evidence[].source`	`string \| null`	Collection lane.
`brands[].top_evidence[].title`	`string \| null`	Original title.
`brands[].top_evidence[].text`	`string \| null`	Original text.
`brands[].top_evidence[].url`	`string \| null`	Original link.
`brands[].top_evidence[].canonical_url`	`string \| null`	Deduplication URL preserving source identity.
`brands[].top_evidence[].author`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].top_evidence[].author.id`	`string \| null`	Author id.
`brands[].top_evidence[].author.handle`	`string \| null`	Public username.
`brands[].top_evidence[].author.name`	`string \| null`	Display name.
`brands[].top_evidence[].author.url`	`string \| null`	Author link.
`brands[].top_evidence[].metrics`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].top_evidence[].metrics.likes`	`number \| null`	Native likes or null.
`brands[].top_evidence[].metrics.score`	`number \| null`	Native net score; can be negative.
`brands[].top_evidence[].metrics.comments`	`number \| null`	Native comments or replies.
`brands[].top_evidence[].metrics.reshares`	`number \| null`	Native reposts/reshares.
`brands[].top_evidence[].metrics.views`	`number \| null`	Native views; separate from interactions.
`brands[].top_evidence[].metrics.interactions`	`number \| null`	Documented interaction total when available.
`brands[].top_evidence[].metrics.complete_interactions`	`boolean \| null`	All inputs for the interaction total are known.
`brands[].top_evidence[].engagement`	`number \| null`	Observed interaction sum; inspect metrics for original counters. This value is not a cross-platform ranking score.
`brands[].top_evidence[].created_at`	`string \| null`	Publication timestamp or null.
`brands[].top_evidence[].fetched_at`	`string \| null`	Collection timestamp.
`brands[].top_evidence[].date_status`	`string \| null`	within_window, outside_window or undated.
`brands[].top_evidence[].relevance`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].top_evidence[].relevance.method`	`string \| null`	literal_subject_match or jev.
`brands[].top_evidence[].relevance.classification`	`string \| null`	keyword_match, subject_match, unrelated or needs_review. Lexical matching is not identity verification.
`brands[].top_evidence[].relevance.entity_verified`	`boolean \| null`	False for keyword-only matching.
`brands[].top_evidence[].relevance.model`	`string \| null`	Model identifier when classified.
`brands[].top_evidence[].relevance.version`	`string \| null`	Classifier version.
`brands[].top_evidence[].relevance.status`	`string \| null`	classified or unavailable for optional Jev analysis.
`brands[].top_evidence[].relevance.reason`	`string \| null`	Reason analysis was unavailable.
`brands[].top_evidence[].relevance.identity`	`string \| null`	yes, no or uncertain.
`brands[].top_evidence[].relevance.identity_support`	`number \| null`	Model support0–1, not a calibrated correctness probability.
`brands[].top_evidence[].relevance.discussion`	`string \| null`	substantive, incidental, adjacent, unrelated or uncertain.
`brands[].top_evidence[].relevance.discussion_support`	`number \| null`	Model support0–1.
`brands[].top_evidence[].relevance.usefulness`	`string \| null`	evidence, question, capability, passing or unclear.
`brands[].top_evidence[].relevance.usefulness_support`	`number \| null`	Model support0–1.
`brands[].top_evidence[].relevance.evidence_scope`	`string \| null`	returned_title_and_text; attached context is separate reading evidence.
`brands[].top_evidence[].provenance`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].top_evidence[].provenance[].platform`	`string \| null`	Original platform.
`brands[].top_evidence[].provenance[].endpoint`	`string \| null`	Original endpoint.
`brands[].top_evidence[].provenance[].query`	`string \| null`	Query used.
`brands[].top_evidence[].provenance[].params`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].top_evidence[].context_evidence`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].top_evidence[].context_evidence.kind`	`string \| null`	comments or transcripts.
`brands[].top_evidence[].context_evidence.status`	`string \| null`	answered, unavailable or invalid_response.
`brands[].top_evidence[].context_evidence.items`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].top_evidence[].context_evidence.items[].id`	`string \| null`	Original comment identifier.
`brands[].top_evidence[].context_evidence.items[].text`	`string \| null`	Readable comment text; YouTube HTML formatting is converted to plain text.
`brands[].top_evidence[].context_evidence.items[].url`	`string \| null`	Original comment URL.
`brands[].top_evidence[].context_evidence.items[].created_at`	`string \| null`	Original publication timestamp or null.
`brands[].top_evidence[].context_evidence.items[].date_status`	`string \| null`	within_window or outside_window against the disclosed context window; undated without a publication timestamp; not_evaluated if no valid window was supplied.
`brands[].top_evidence[].context_evidence.window`	`object \| null`	Nested response fields; optional unless explicitly documented.
`brands[].top_evidence[].context_evidence.window.from`	`string \| null`	Explicit parent query-window start.
`brands[].top_evidence[].context_evidence.window.to`	`string \| null`	Explicit parent query-window end.
`brands[].top_evidence[].context_evidence.excluded_parent_records`	`number \| null`	X records excluded because native ID or canonical URL matched the parent post, not actual replies.
`brands[].top_evidence[].context_evidence.counted_as_mentions`	`boolean \| null`	False: contextual comments do not add mentions to the search sample.
`brands[].top_evidence[].context_evidence.sample_cap`	`number \| null`	At most 10 returned comments per selected parent.
`brands[].top_evidence[].source_rank`	`number \| null`	One-based original source page position before non-content filtering and deduplication; null for legacy evidence or separately attached context.
`brands[].query_plan`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].query_plan.version`	`string \| null`	panorama-context-query-v1.
`brands[].query_plan.subject`	`string \| null`	Original identity target.
`brands[].query_plan.query`	`string \| null`	Bounded expanded query template; actual source queries are listed in lanes.
`brands[].query_plan.mode`	`string \| null`	subject, subject_with_context or mixed_subject_and_context.
`brands[].query_plan.context_terms`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].query_plan.source_order`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].query_plan.lanes`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].query_plan.lanes[].platform`	`string \| null`	Source platform.
`brands[].query_plan.lanes[].query`	`string \| null`	Exact native retrieval query for this lane.
`brands[].query_plan.lanes[].mode`	`string \| null`	subject or subject_with_context.
`brands[].query_plan.literal_sources`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].query_plan.context_sources`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].query_plan.max_requests_per_source`	`number \| null`	One bounded search per selected source.
`brands[].query_plan.policy`	`string \| null`	Caller context and retrieval limitations.
`brands[].match_summary`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].match_summary.status`	`string \| null`	matched, candidates_only, no_supported_match or empty_sample.
`brands[].match_summary.collected_records`	`number \| null`	All retained records, including uncertain and unrelated evidence.
`brands[].match_summary.supported_matches`	`number \| null`	Completed Jev subject matches.
`brands[].match_summary.supported_useful_matches`	`number \| null`	Supported subject matches with substantive useful evidence.
`brands[].match_summary.lexical_candidates`	`number \| null`	Authored keyword/context candidates; may be namesakes.
`brands[].match_summary.unresolved_records`	`number \| null`	Evidence without supported identity or literal candidacy.
`brands[].match_summary.unrelated_records`	`number \| null`	Explicit unrelated classifications.
`brands[].match_summary.scope`	`string \| null`	returned_sample.
`brands[].match_summary.entity_verified`	`boolean \| null`	False: model support is not independent identity verification.
`brands[].match_summary.policy`	`string \| null`	Original evidence remains available; no supported match does not establish absence from the web.
`brands[].matched_items`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].matched_items[].id`	`string \| null`	Native record identifier; preserve exact case and value.
`brands[].matched_items[].platform`	`string \| null`	Platform id.
`brands[].matched_items[].source`	`string \| null`	Collection lane.
`brands[].matched_items[].title`	`string \| null`	Original title.
`brands[].matched_items[].text`	`string \| null`	Original text.
`brands[].matched_items[].url`	`string \| null`	Original link.
`brands[].matched_items[].canonical_url`	`string \| null`	Deduplication URL preserving source identity.
`brands[].matched_items[].author`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].matched_items[].author.id`	`string \| null`	Author id.
`brands[].matched_items[].author.handle`	`string \| null`	Public username.
`brands[].matched_items[].author.name`	`string \| null`	Display name.
`brands[].matched_items[].author.url`	`string \| null`	Author link.
`brands[].matched_items[].metrics`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].matched_items[].metrics.likes`	`number \| null`	Native likes or null.
`brands[].matched_items[].metrics.score`	`number \| null`	Native net score; can be negative.
`brands[].matched_items[].metrics.comments`	`number \| null`	Native comments or replies.
`brands[].matched_items[].metrics.reshares`	`number \| null`	Native reposts/reshares.
`brands[].matched_items[].metrics.views`	`number \| null`	Native views; separate from interactions.
`brands[].matched_items[].metrics.interactions`	`number \| null`	Documented interaction total when available.
`brands[].matched_items[].metrics.complete_interactions`	`boolean \| null`	All inputs for the interaction total are known.
`brands[].matched_items[].engagement`	`number \| null`	Observed interaction sum; inspect metrics for original counters. This value is not a cross-platform ranking score.
`brands[].matched_items[].created_at`	`string \| null`	Publication timestamp or null.
`brands[].matched_items[].fetched_at`	`string \| null`	Collection timestamp.
`brands[].matched_items[].date_status`	`string \| null`	within_window, outside_window or undated.
`brands[].matched_items[].relevance`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].matched_items[].relevance.method`	`string \| null`	literal_subject_match or jev.
`brands[].matched_items[].relevance.classification`	`string \| null`	keyword_match, subject_match, unrelated or needs_review. Lexical matching is not identity verification.
`brands[].matched_items[].relevance.entity_verified`	`boolean \| null`	False for keyword-only matching.
`brands[].matched_items[].relevance.model`	`string \| null`	Model identifier when classified.
`brands[].matched_items[].relevance.version`	`string \| null`	Classifier version.
`brands[].matched_items[].relevance.status`	`string \| null`	classified or unavailable for optional Jev analysis.
`brands[].matched_items[].relevance.reason`	`string \| null`	Reason analysis was unavailable.
`brands[].matched_items[].relevance.identity`	`string \| null`	yes, no or uncertain.
`brands[].matched_items[].relevance.identity_support`	`number \| null`	Model support0–1, not a calibrated correctness probability.
`brands[].matched_items[].relevance.discussion`	`string \| null`	substantive, incidental, adjacent, unrelated or uncertain.
`brands[].matched_items[].relevance.discussion_support`	`number \| null`	Model support0–1.
`brands[].matched_items[].relevance.usefulness`	`string \| null`	evidence, question, capability, passing or unclear.
`brands[].matched_items[].relevance.usefulness_support`	`number \| null`	Model support0–1.
`brands[].matched_items[].relevance.evidence_scope`	`string \| null`	returned_title_and_text; attached context is separate reading evidence.
`brands[].matched_items[].provenance`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].matched_items[].provenance[].platform`	`string \| null`	Original platform.
`brands[].matched_items[].provenance[].endpoint`	`string \| null`	Original endpoint.
`brands[].matched_items[].provenance[].query`	`string \| null`	Query used.
`brands[].matched_items[].provenance[].params`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].matched_items[].context_evidence`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].matched_items[].context_evidence.kind`	`string \| null`	comments or transcripts.
`brands[].matched_items[].context_evidence.status`	`string \| null`	answered, unavailable or invalid_response.
`brands[].matched_items[].context_evidence.items`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].matched_items[].context_evidence.items[].id`	`string \| null`	Original comment identifier.
`brands[].matched_items[].context_evidence.items[].text`	`string \| null`	Readable comment text; YouTube HTML formatting is converted to plain text.
`brands[].matched_items[].context_evidence.items[].url`	`string \| null`	Original comment URL.
`brands[].matched_items[].context_evidence.items[].created_at`	`string \| null`	Original publication timestamp or null.
`brands[].matched_items[].context_evidence.items[].date_status`	`string \| null`	within_window or outside_window against the disclosed context window; undated without a publication timestamp; not_evaluated if no valid window was supplied.
`brands[].matched_items[].context_evidence.window`	`object \| null`	Nested response fields; optional unless explicitly documented.
`brands[].matched_items[].context_evidence.window.from`	`string \| null`	Explicit parent query-window start.
`brands[].matched_items[].context_evidence.window.to`	`string \| null`	Explicit parent query-window end.
`brands[].matched_items[].context_evidence.excluded_parent_records`	`number \| null`	X records excluded because native ID or canonical URL matched the parent post, not actual replies.
`brands[].matched_items[].context_evidence.counted_as_mentions`	`boolean \| null`	False: contextual comments do not add mentions to the search sample.
`brands[].matched_items[].context_evidence.sample_cap`	`number \| null`	At most 10 returned comments per selected parent.
`brands[].matched_items[].source_rank`	`number \| null`	One-based original source page position before non-content filtering and deduplication; null for legacy evidence or separately attached context.
`brands[].candidate_items`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].candidate_items[].id`	`string \| null`	Native record identifier; preserve exact case and value.
`brands[].candidate_items[].platform`	`string \| null`	Platform id.
`brands[].candidate_items[].source`	`string \| null`	Collection lane.
`brands[].candidate_items[].title`	`string \| null`	Original title.
`brands[].candidate_items[].text`	`string \| null`	Original text.
`brands[].candidate_items[].url`	`string \| null`	Original link.
`brands[].candidate_items[].canonical_url`	`string \| null`	Deduplication URL preserving source identity.
`brands[].candidate_items[].author`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].candidate_items[].author.id`	`string \| null`	Author id.
`brands[].candidate_items[].author.handle`	`string \| null`	Public username.
`brands[].candidate_items[].author.name`	`string \| null`	Display name.
`brands[].candidate_items[].author.url`	`string \| null`	Author link.
`brands[].candidate_items[].metrics`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].candidate_items[].metrics.likes`	`number \| null`	Native likes or null.
`brands[].candidate_items[].metrics.score`	`number \| null`	Native net score; can be negative.
`brands[].candidate_items[].metrics.comments`	`number \| null`	Native comments or replies.
`brands[].candidate_items[].metrics.reshares`	`number \| null`	Native reposts/reshares.
`brands[].candidate_items[].metrics.views`	`number \| null`	Native views; separate from interactions.
`brands[].candidate_items[].metrics.interactions`	`number \| null`	Documented interaction total when available.
`brands[].candidate_items[].metrics.complete_interactions`	`boolean \| null`	All inputs for the interaction total are known.
`brands[].candidate_items[].engagement`	`number \| null`	Observed interaction sum; inspect metrics for original counters. This value is not a cross-platform ranking score.
`brands[].candidate_items[].created_at`	`string \| null`	Publication timestamp or null.
`brands[].candidate_items[].fetched_at`	`string \| null`	Collection timestamp.
`brands[].candidate_items[].date_status`	`string \| null`	within_window, outside_window or undated.
`brands[].candidate_items[].relevance`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].candidate_items[].relevance.method`	`string \| null`	literal_subject_match or jev.
`brands[].candidate_items[].relevance.classification`	`string \| null`	keyword_match, subject_match, unrelated or needs_review. Lexical matching is not identity verification.
`brands[].candidate_items[].relevance.entity_verified`	`boolean \| null`	False for keyword-only matching.
`brands[].candidate_items[].relevance.model`	`string \| null`	Model identifier when classified.
`brands[].candidate_items[].relevance.version`	`string \| null`	Classifier version.
`brands[].candidate_items[].relevance.status`	`string \| null`	classified or unavailable for optional Jev analysis.
`brands[].candidate_items[].relevance.reason`	`string \| null`	Reason analysis was unavailable.
`brands[].candidate_items[].relevance.identity`	`string \| null`	yes, no or uncertain.
`brands[].candidate_items[].relevance.identity_support`	`number \| null`	Model support0–1, not a calibrated correctness probability.
`brands[].candidate_items[].relevance.discussion`	`string \| null`	substantive, incidental, adjacent, unrelated or uncertain.
`brands[].candidate_items[].relevance.discussion_support`	`number \| null`	Model support0–1.
`brands[].candidate_items[].relevance.usefulness`	`string \| null`	evidence, question, capability, passing or unclear.
`brands[].candidate_items[].relevance.usefulness_support`	`number \| null`	Model support0–1.
`brands[].candidate_items[].relevance.evidence_scope`	`string \| null`	returned_title_and_text; attached context is separate reading evidence.
`brands[].candidate_items[].provenance`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].candidate_items[].provenance[].platform`	`string \| null`	Original platform.
`brands[].candidate_items[].provenance[].endpoint`	`string \| null`	Original endpoint.
`brands[].candidate_items[].provenance[].query`	`string \| null`	Query used.
`brands[].candidate_items[].provenance[].params`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].candidate_items[].context_evidence`	`object`	Nested response fields; optional unless explicitly documented.
`brands[].candidate_items[].context_evidence.kind`	`string \| null`	comments or transcripts.
`brands[].candidate_items[].context_evidence.status`	`string \| null`	answered, unavailable or invalid_response.
`brands[].candidate_items[].context_evidence.items`	`array`	Nested response fields; optional unless explicitly documented.
`brands[].candidate_items[].context_evidence.items[].id`	`string \| null`	Original comment identifier.
`brands[].candidate_items[].context_evidence.items[].text`	`string \| null`	Readable comment text; YouTube HTML formatting is converted to plain text.
`brands[].candidate_items[].context_evidence.items[].url`	`string \| null`	Original comment URL.
`brands[].candidate_items[].context_evidence.items[].created_at`	`string \| null`	Original publication timestamp or null.
`brands[].candidate_items[].context_evidence.items[].date_status`	`string \| null`	within_window or outside_window against the disclosed context window; undated without a publication timestamp; not_evaluated if no valid window was supplied.
`brands[].candidate_items[].context_evidence.window`	`object \| null`	Nested response fields; optional unless explicitly documented.
`brands[].candidate_items[].context_evidence.window.from`	`string \| null`	Explicit parent query-window start.
`brands[].candidate_items[].context_evidence.window.to`	`string \| null`	Explicit parent query-window end.
`brands[].candidate_items[].context_evidence.excluded_parent_records`	`number \| null`	X records excluded because native ID or canonical URL matched the parent post, not actual replies.
`brands[].candidate_items[].context_evidence.counted_as_mentions`	`boolean \| null`	False: contextual comments do not add mentions to the search sample.
`brands[].candidate_items[].context_evidence.sample_cap`	`number \| null`	At most 10 returned comments per selected parent.
`brands[].candidate_items[].source_rank`	`number \| null`	One-based original source page position before non-content filtering and deduplication; null for legacy evidence or separately attached context.
`comparison`	`object`	Nested response fields; optional unless explicitly documented.
`comparison.sources`	`array`	Nested response fields; optional unless explicitly documented.
`comparison.engagement_sources`	`array`	Nested response fields; optional unless explicitly documented.
`comparison.engagement_comparable`	`boolean \| null`	Every compared brand has observed interactions on the disclosed engagement sources.
`totals`	`object`	Nested response fields; optional unless explicitly documented.
`totals.comparable_mentions`	`number \| null`	Common-source denominator.
`totals.comparable_engagement`	`number \| null`	Observed interaction denominator.

Compare only common successful sources and inspect each brand’s retained evidence. Zero or unavailable denominators yield null, not a zero share.

share_of_mentions and share_of_engagement use fractions0–1, unlike AI visibility percentages0–100. Indexed web citation counts are a different measurement.

Evidence is ordered by relevance tier and balanced across sources within each tier, preserving source page rank. Context supplies a bounded search hint from the caller’s words and lexical priority cues. Inspect query_plan and per-source queries; added terms can narrow retrieval and do not verify identity. Ordering and optional labels do not change sample counts or share denominators.

Use match_summary to distinguish supported matches, lexical candidates and no supported match. matched_items and candidate_items are views into the retained pool, not additional mentions. A complete relevance_analysis covers selected candidates only; remaining_unclassified includes both unselected and failed records.

Failures use the typed error envelope. A confirmed uncharged or refunded failure reports zero; a pending reconciliation can report an unknown charge. Read credits_used and error.details.billing_status, and keep request_id for recovery. Response contract · Error reference

Share of voice

Query parameters

Make the request

Response fields and example

First call in under a minute

Share of voice

Query parameters

Make the request

Response fields and example

More Panorama reference

First call in under a minute