# Panorama: Search and API guide

Explore public data in the Search workspace, or bring related data together programmatically with the API. Choose the interface that fits your task.

## Panorama Search or Panorama API?

| Interface | Use it for | Start here |
| --- | --- | --- |
| Panorama Search | Interactive research around a company, brand, product or topic: inspect mentions, filter evidence, reopen saved searches and export results. | [Search guide](https://www.monocrawl.com/docs/panorama-search) · [Open Search](https://www.monocrawl.com/dashboard/conversations) |
| Panorama API | Ready-made workflows that collect related records and return endpoint-specific structured data. Use HTTP, the playground or MCP. | [Open API playground](https://www.monocrawl.com/dashboard/api/explorer?platform=panorama&endpoint=devtool-brief) · [Endpoint catalogue](https://www.monocrawl.com/docs/platforms/panorama) |

They share the Panorama name, but have different workflows and coverage. Search’s saved results, relevance decisions and optional complaint labels are dashboard features. Calling a Panorama API endpoint does not reproduce the Search interface or expose its saved analysis. See [Search’s API and MCP scope](https://www.monocrawl.com/docs/panorama-search#api).

## Make your first Panorama API request

A composite operation combines related lookups behind one request. Some span multiple platforms; others combine several reads on the same platform. Universal URL lookup is a dispatcher to a supported detail endpoint rather than a multi-source analysis.

This example requests a developer brief for Deno: a GitHub repository dossier, activity over the last seven days and matching Hacker News discussions. Store your key in the server environment as `MONOCRAWL_API_KEY`. Check the [current endpoint price and availability](https://www.monocrawl.com/docs/endpoints/panorama/devtool-brief) before running it.

**cURL · a billable retrieval**

```
curl --get 'https://www.monocrawl.com/v1/panorama/devtool-brief' \
  --header "x-api-key: $MONOCRAWL_API_KEY" \
  --data-urlencode 'query=deno' \
  --data-urlencode 'threads=5'
```

A name query searches for a repository and selects a candidate. Inspect `data.repo_resolution` to confirm the intended project. You can supply a GitHub repository URL for explicit resolution; the same query is also used for the Hacker News search. A matching repository does not prove that every discussion concerns that project.

`threads=5` limits the displayed ranked threads. The brief’s Hacker News totals are computed over the returned search sample, which can include more stories than the displayed five.

## Choose an operation by its result

| Operation | What it combines | Coverage |
| --- | --- | --- |
| [`devtool-brief`](https://www.monocrawl.com/docs/endpoints/panorama/devtool-brief) | Combine a GitHub repository dossier, recent commit activity and Hacker News discussions. Repository, ranked threads and activity counts. | GitHub · Hacker News |
| [`creator-vetting`](https://www.monocrawl.com/docs/endpoints/panorama/creator-vetting) | Bring together a profile, recent posts, engagement and available comments for one creator. One platform per call; comment and commerce coverage varies. | Choose TikTok, Instagram, YouTube, X or Threads |
| [`video-intel`](https://www.monocrawl.com/docs/endpoints/panorama/video-intel) | Start with a video URL to collect its details, engagement, author and supported transcript or comment data. A video brief with unavailable components identified. | Coverage depends on the video platform |
| [`share-of-voice`](https://www.monocrawl.com/docs/endpoints/panorama/share-of-voice) | Compare two to five brands by mentions and engagement, with evidence links and source breakdowns. Shares calculated over common sources; engagement also requires observed counters. | Default: Reddit · Hacker News · X · TikTok · Instagram · YouTube, plus configured Bluesky. Sources can be selected explicitly. |
| [`reputation`](https://www.monocrawl.com/docs/endpoints/panorama/reputation) | Combine supported review sources and news into a brand reputation response with source ratings and review samples. Sources depend on supplied identifiers; optional review themes. | Trustpilot · App stores · Places · News |
| [`ai-visibility`](https://www.monocrawl.com/docs/endpoints/panorama/ai-visibility) | Currently unavailable. The contract documents prompt-level brand appearances, competitors and cited domains. Free planning and response-contract discovery remain available. | No eligible answer engines currently offered |

The [complete reference](https://www.monocrawl.com/docs/platforms/panorama) includes batch profiles, comments, URL lookup, review integrity and other workflows. Platform support is specific to each operation. Batch profiles accepts explicit platform/handle pairs, including supported major social profiles. A YouTube pair can use a handle or an exact 24-character channel ID beginning with `UC`; preserve its case. Inspect each item’s outcome because sources differ in eligibility, identifiers and available fields.

## Read the result and its coverage

The API uses Monocrawl’s normal response envelope, including `success`, `data`, `request_id` and billing fields. Each Panorama endpoint defines its own data object. Do not assume that all operations return the same fields.

| Developer brief field | Meaning |
| --- | --- |
| `data.repo_resolution` | Resolution method, selected owner/repository and available search candidates. |
| `data.repo` | The repository dossier, or null if it was not retrieved. |
| `data.hacker_news` | Ranked threads, analysed story count and summed points/comments for the search sample; null when unavailable. |
| `data.computed` | Stars, weekly commit count, its time window and the source-reported Hacker News hit count. Weekly commits use one page capped at 100; warnings identify a reached cap. |
| `data.sources` | Component outcomes. Inspect ok, skipped and error information before treating a source as covered. |
| `data._warnings` | Collection bounds, missing coverage and interpretation limits. |
| `data._meta.billing` | This workflow’s component billing calculation. Read the outer response receipt for customer settlement status. |

Other workflows may use `legs`, per-item failures or engine outcomes instead of `sources`. A successful envelope can contain partial data. Keep null values and warnings; do not replace missing results with zero or describe a returned sample as complete platform coverage.

For AI answers, shared citations indicate source overlap, not verified factual agreement. For optional themes or topics, distinguish model interpretations from original source records and calculated metrics.

## Measure social mentions and share of voice

`brand-mentions` and `share-of-voice` accept an explicit `platforms` list. The default pool includes Reddit, Hacker News, X, TikTok, Instagram and YouTube, plus configured Bluesky. Sources use their supported keyword or hashtag search operations; source eligibility, spending limits and deadlines determine which can answer.

Set `date_mode=strict` for metrics limited to known publication dates inside the lookback window. The default `ranked` mode retains undated and older matches with date labels. `per_source_limit` is a bounded page sample, not a platform-wide mention count. Preserve each record’s native ID, URL, metrics, timestamp and provenance.

Share of voice compares only sources that answered for every brand. `share_of_mentions` and `share_of_engagement` are fractions from 0 to 1; null means no usable denominator. Views remain separate from interactions. Each brand’s evidence and coverage explain its contribution to the calculation.

For an ambiguous name, supply `context` describing the intended subject, such as `Mercury, the business banking service; not the planet`. Brand mentions and share of voice use a short descriptive hint to improve retrieval. With three or more selected sources, a fixed subset searches the original name to retain broader evidence; the other sources use the contextual query. One or two sources use the contextual query. Each source still receives one bounded search request. Read `query_plan.lanes` and each source’s coverage for the exact queries. Extra terms can narrow what a source returns; neither query mode guarantees complete recall or verified identity.

Results prioritise supported useful subject matches when classified, then other subject matches, contextual candidates, keyword candidates, uncertain matches and unrelated results. Within candidate groups, authored questions and experience text are prioritised and repeated long text is deferred. Platforms take turns within each priority group; `source_rank` preserves each record’s original page position. A large like count on one network does not outrank every result from another. Inspect `ranking` for the ordering policy and source counts. Missing engagement remains unknown.

Optional `relevance=jev` classifies at most 20 candidates per brand when funding and capacity permit. The workflow protects part of its existing spending limit for classification and requested reading context before collecting sources. Classification runs before comment selection. This can reduce source coverage within the same price; inspect completed source and analysis counts. `relevance_analysis.status` distinguishes complete, partial, unavailable and no-candidate outcomes. `remaining_unclassified` includes both unselected records and failed classifications.

`matched_items` contains completed Jev subject matches; `candidate_items` contains lexical candidates still needing review. `match_summary` reports both pools, unresolved records and unrelated records. A `no_supported_match` status means this returned sample established no supported match, not that the subject has no mentions anywhere. Every original record remains in `items` (or each share-of-voice brand’s `evidence`). Sample counts and share denominators are not silently replaced with model-filtered totals. Read identity, discussion and usefulness labels independently; model support is not a calibrated probability.

For brand mentions, `enrich=comments` or `transcripts` adds reading context to up to three supported posts chosen across sources, with a cap of 10 comments or 8,000 transcript characters each. These records do not increase the mention count. Optional classification examines the returned parent title and text; attached comments and transcripts remain separate reading evidence. An empty comment sample, disabled comments and a failed source request are different outcomes; inspect the source receipt.

## Find purchase intent and audience questions in comments

[Leads](https://www.monocrawl.com/docs/endpoints/panorama/leads) keeps its existing alternative/comparison search with `mode=threads` (the default). Choose `mode=comments` to search supported social posts, sample their comments and identify authored purchase intent that fits your `product_category`. Supply a subject with `competitor` or `query`. The category is required in this mode: wanting an unrelated product, an advert or a generic “I want it” does not qualify as demand for your offer.

**MCP · inspect the current quote before retrieval**

```
{
  "name": "get_endpoint",
  "arguments": {
    "id": "panorama/leads",
    "params": {
      "mode": "comments",
      "competitor": "Figma",
      "product_category": "collaborative design software",
      "platforms": "youtube,tiktok,instagram",
      "limit": "10"
    }
  }
}
```

[Questions](https://www.monocrawl.com/docs/endpoints/panorama/questions) defaults to `mode=threads`, a multilingual title-shape heuristic over Hacker News and Reddit. For multilingual research, use `mode=semantic`: it classifies genuine information-seeking questions and indirect requests in returned posts and sampled comments. Use `mode=comments` to examine only comments. Semantic classification does not require English words or a question mark; quoted questions, rhetorical wording and tutorial adverts do not automatically count.

**MCP · plan multilingual question research**

```
{
  "name": "get_endpoint",
  "arguments": {
    "id": "panorama/questions",
    "params": {
      "mode": "semantic",
      "topic": "Figma",
      "context": "collaborative interface design software",
      "platforms": "reddit,hackernews,youtube",
      "limit": "20"
    }
  }
}
```

Comments mode supports Reddit, X, TikTok, Instagram and YouTube; its default pool is TikTok, Instagram and YouTube. Semantic questions adds Hacker News posts and defaults to Reddit, Hacker News and those three video sources. Select a subset with `platforms`. Each source receives at most one search request, retaining up to 20 posts. Up to three parent posts receive comment lookups, retaining at most 10 comments each. Analysis selects at most 24 candidates across source posts and comment parents. Availability, deadlines and funding can reduce these counts.

In these modes, `items` contains qualified results grouped by matching wording; `count` is the number displayed after `limit`. `candidate_items` retains all native candidates. `needs_review` contains uncertain, unavailable and unselected analysis, while `rejected_items` keeps supported exclusions inspectable. Read `match_summary` for candidate, analyzed, qualified and retained-useful counts together. An empty qualified list does not mean there are no questions or potential buyers.

Each `intelligence.judgments` entry carries its status, model support and an exact supporting sentence with field and UTF-16 offsets. Parent posts are separately labelled context; they cannot supply the commenter’s purchase intent. These are advisory content judgments, not verified buyer identities or permission for outreach. No author profiles or contact details are fetched. Repeated wording is grouped for reading, not counted as independent people.

The existing endpoint price applies with no analysis surcharge. Retrieval and model requests share the workflow’s current funding envelope and deadline. `analysis_legs` separates model receipts from source `legs`; unknown supplier cost is not a measured zero. `source_coverage` describes search outcomes and `comment_coverage` describes which comment samples answered. `lookback_days` accepts 1–365 (default 90), but source and comment dates remain explicit: older and undated evidence is retained with `date_status`.

## Add historical web evidence

Use `brand-mentions?include_history=true` to request indexed web summary, trends and example citations alongside the social sample. The `history` field reports its own completeness. `mention-surge?history_mode=indexed` compares non-overlapping completed historical windows; it excludes today and does not silently replace missing days with zero.

The standalone [indexed summary](https://www.monocrawl.com/docs/endpoints/content_analysis/indexed-summary), [indexed search](https://www.monocrawl.com/docs/endpoints/content_analysis/indexed-search) and [indexed phrase trends](https://www.monocrawl.com/docs/endpoints/content_analysis/indexed-phrase-trends) expose this measurement separately. Index history starts on 31 October 2022 where source records exist. Search examples use publication dates, while trend buckets use index reporting dates. An observed/fetched timestamp does not establish when an article was published.

Indexed citations and native social posts have different coverage and denominators. `negative_share` divides negative reported assignments by positive + negative + neutral assignments. These source categories can overlap, so this is not a verified fraction of unique citations. A negative-share trend uses those fractions, not negative counts. Returned provenance describes the source classification and its unknown confidence.

Summary and trend filters describe the requested query; precise source enforcement and a consistent historical source roster remain unverified. Inspect `window.verified` and `filters.verified`. Search records can be filtered locally to known publication dates and requested fields, but source totals are reported before that local filtering.

## Interpret creator and review samples

Creator vetting accepts `posts_limit`, `comment_posts` and `comments_per_post`. Read `post_evidence` and `sample` to see the original counters and requested versus completed collection. Zero interactions remain zero; missing counters remain unknown. Summed followers across profiles are not unique audience reach, and a small commenter sample is not proof of a fake audience.

YouTube creator research can fetch counters for up to 10 returned video IDs in one bounded detail request when the initial post page omits them. `metrics_hydration` reports requested and returned IDs and any remaining gaps. Each post’s `count_sources` identifies the fields and lookup behind its numbers. `video-intel` reads both published top-level and nested counters; interactions exclude views, and an engagement rate requires observed interactions and a positive view count. Handle audits use reported followers or subscribers and disclose `follower_source_field`.

Optional `content_review=1` adds advisory text review to creator vetting without another source lookup or credit surcharge. It examines at most eight evenly spaced posts from the already-returned sample, looking for explicit authored threats, targeted abuse, sexual text, regulated-product promotion, sponsorship disclosures and engagement bait. Every flag points to the original `content_review.source_posts` field and sentence. `assessments` and `remaining_unclassified` preserve incomplete and uncertain analysis. The same spending and time limits apply, so reserving room for this review can reduce retrieval coverage.

Content review requires human interpretation. It does not inspect images or video, determine authenticity, infer personal traits or produce an overall creator score. Missing flags are not evidence of safety. Profile metrics remain arithmetic over observed counters and are unaffected by the labels.

For `product-reviews`, query-based Amazon, Google Shopping and Trustpilot discovery now exposes `identity_resolution`. It checks returned names, models and supplied variants; multiple compatible identities remain ambiguous. Supply an explicit ASIN or company domain when needed. Query-based app discovery in `reputation` and `demand-signals` follows the same rule; explicit app IDs take precedence. Text matches do not verify ownership, and source reviews may pool variants. Trustpilot reviews describe the company and remain separate from product-rating arithmetic. Shopping offers with differing ratings, variants or currencies do not receive an invented shared aggregate.

Each decision exposes its status, selected ID, number of compatible candidates and up to ten candidate summaries with matching reasons. An ambiguous or unavailable source has no selected ID; if no source can be matched and read, inspect the error’s `identity_resolution` details. Google Business discovery in `reputation` uses the same name-matching rule. This does not extend identity verification to keyword news, Reddit or Amazon demand samples. The [product-review schema](https://www.monocrawl.com/schemas/panorama/product-reviews.json) and the [reputation](https://www.monocrawl.com/docs/endpoints/panorama/reputation) and [demand-signals references](https://www.monocrawl.com/docs/endpoints/panorama/demand-signals) describe the exact scopes.

Review comparisons accept explicit `review_sources` mappings across supported app, product or company sources. Only comparable entity types, marketplaces and variants are tested. Caller mappings remain labelled as caller supplied. Statistical comparisons need at least 20 rated reviews per source and abstain when identities or samples are inadequate. A rating difference or unusual distribution does not establish fraudulent reviews.

Source `ratings_count` and written `reviews_count` are separate population measures. Review windows and daily statistics use `review_date`; `date_basis` distinguishes publication from a last update. An update date is never presented as a publication timestamp.

A review without a variant label remains usable evidence from the requested listing, marked `variant_status=unknown`. It is not counted as a verified match for the requested variant, and variant comparisons abstain when those labels are missing. Explicitly different variants and records excluded by a strict date window are retained separately in `excluded_reviews` with reasons. Without a strict window, undated reviews remain in the sample; they never receive invented dates or enter daily statistics.

## Audit every AI visibility probe

**Currently unavailable:** no eligible answer engine is offered for AI answers or AI visibility. Free plans and response contracts remain available; execution refuses these requests without running probes.

`ai-visibility` accepts your prompts, brand, competitors and engine subset. Explicit `runs` overrides preset repetitions; the preset still caps prompt count. Read `effective_settings` for omitted prompts and planned calls before interpreting results. A default quick batch permits up to three prompts with two repetitions each per engine.

Every `probes` entry includes the answer, citations, model, prompt/run IDs, timestamps, SHA-256 and recognized brand passages. Normal answers are retained in full; safety bounds cap each at 64,000 characters and 100 citations with explicit truncation flags. Appearance rates use **0–100 percentages** over completed nonempty answers. Failed and skipped probes are excluded and reported separately; a completely failed batch returns an error. Literal brand matches do not imply a recommendation or verified identity.

**Free MCP plan before a paid AI visibility request**

```
{
  "name": "get_endpoint",
  "arguments": {
    "id": "panorama/ai-visibility",
    "params": {
      "brand": "My Brand",
      "prompts": "[\"Which project tools are useful?\"]",
      "runs": "1",
      "engines": "perplexity,grok"
    }
  }
}
```

This returns an execution plan and the current endpoint price without probing any engine or reserving credits. The plan is not an availability guarantee. Actual execution still checks eligible supply, configured cost ceilings, account funds and limits. Use `call_endpoint.max_credits` to enforce your spending ceiling.

## Prices, partial results and retries

Read each operation’s current price in the endpoint reference or with `get_endpoint`. The developer brief reports attempted and successful component counts and its billing formula; other operations have their own accounting. Do not apply one workflow’s partial-result adjustment to every Panorama endpoint.

If `credits_used` is null and `error.details.billing_status` is `pending_reconciliation`, the final charge is unresolved. Preserve the request ID and idempotency key and reconcile it before starting a replacement paid request. A source failure is not by itself proof of a refund. See [credits and reconciliation](https://www.monocrawl.com/docs/credits).

Bound retries, retain the exact arguments for each logical request, and inspect the error before retrying. Reuse its idempotency key where supported. A new subject, page or refreshed request is a new operation. Use the [production request wrapper](https://www.monocrawl.com/docs/production-checklist) for timeouts, backoff and receipt handling.

## Use Panorama API through MCP

After [connecting Monocrawl](https://www.monocrawl.com/docs/mcp), read the guide and endpoint contract, check the available balance, then retrieve with an explicit spending ceiling. These are separate tool calls in order; discovery is free, retrieval can spend credits.

**MCP tool calls**

```
[
  {
    "name": "get_docs",
    "arguments": {
      "topic": "panorama"
    }
  },
  {
    "name": "get_endpoint",
    "arguments": {
      "id": "panorama/devtool-brief"
    }
  },
  {
    "name": "call_endpoint",
    "arguments": {
      "platform": "panorama",
      "endpoint": "devtool-brief",
      "params": {
        "query": "deno",
        "threads": "5"
      },
      "max_credits": 5,
      "idempotency_key": "panorama-deno-brief-001"
    }
  }
]
```

The example allows at most 5 credits for this request. If the current quote exceeds that limit, stop and review it; do not automatically increase the budget. Use a unique idempotency key for a new logical request and retain it for retries of that same request.

When storage succeeds, large MCP results return a compact preview with `data.stored_result.id`. Call `get_result` with that ID, then follow its cursor to retrieve the complete original response for 24 hours. These reads require the same account and cost zero credits. Concatenate each `data.text` fragment in order and parse the JSON after the final cursor is null. Storage allows up to 8 MiB per result and 32 MiB of retained results per account. If storage is unavailable or a limit is reached, the full response is returned with a warning; save that original response yourself. Never repeat the paid workflow merely to read another evidence chunk.

Use `get_docs` with topic `panorama-search` for the interactive workspace guide. It reads documentation, not private saved searches. Both guides also have public Markdown versions: [Panorama](https://www.monocrawl.com/docs/panorama.md) and [Panorama Search](https://www.monocrawl.com/docs/panorama-search.md).