# Prism (/docs/prism)
Prism [#prism]
Prism endpoints are **composites**. One call fans out to several platforms in parallel, merges the results, and returns a single computed answer, so you don't orchestrate the fan-out, the retries, or the merge yourself.
Base URL: `/v1/prism/...`
Every number a Prism composite returns is
**computed in code, not generated by a model**
. Where a composite does use an LLM (topic clustering, tone labels), it narrates data that was already computed deterministically.
How do I get started with Prism? [#how-do-i-get-started-with-prism]
1\. Pick a composite by the question you're answering [#1-pick-a-composite-by-the-question-youre-answering]
Each composite answers one question end to end. `handle-audit` answers "is this handle worth pulling"; `comments` answers "what did everyone say on this post"; `reputation` answers "how is this brand seen across review sites". The catalogue below groups all of them by the question they answer.
2\. Make the call [#2-make-the-call]
```bash
curl "https://www.socialcrawl.dev/v1/prism/handle-audit?handle=mrbeast" \
-H "x-api-key: sc_your_api_key_here"
```
3\. Read the coverage block [#3-read-the-coverage-block]
A composite is a fan-out, so a leg can fail without failing your call. Responses carry a coverage signal (`legs[]`, `sources_succeeded`, `coverage`, or a `confidence` block depending on the composite) telling you which sources answered. Billing differs by composite. For `handle-audit`, every successful HTTP 200 receives the full request-shaped charge, even with partial evidence; there is no partial refund.
4\. Read computed fields [#4-read-computed-fields]
Each composite returns fields tailored to its question. `handle-audit` returns score-v2 evidence, nullable scores, component coverage, surface estimates, and leg diagnostics. Direct post and author endpoints may include shared computed fields such as `engagement_rate`, `language`, and `content_category`; see [Computed fields](/docs/computed-fields.md) for formulas and null semantics.
Pick a composite by the question [#pick-a-composite-by-the-question]
Prices below are read from the registry. A single number is a flat charge; a range is either param-derived (you can work out the exact price from your request before you send it) or metered (a ceiling is held and the unused portion refunded).
Brand health — "how is this brand doing right now?" [#brand-health--how-is-this-brand-doing-right-now]
* **`GET /v1/prism/reputation`** — *how is this company seen across review sites?* Blends Trustpilot, both app stores, Google Business, and web sentiment into one weighted score with themed pros, cons, and quotes. Takes `brand`. **30cr.**
* **`GET /v1/prism/share-of-voice`** — *who owns the conversation in this category?* Engagement-weighted share of voice across 2-5 brands, split web vs social, with an emotion overlay and ESOV against `market_shares`. Takes `brands` (CSV). **20cr per brand web-only, 40cr per brand with social (the default), so 20-200cr** — the price is fixed by how many brands you pass and whether `include` contains `social`.
* **`GET /v1/prism/brand-mentions`** — *is talk about this keyword rising or falling, and is it positive?* Mention volume time-series, sentiment split, top sources, and a sample of recent mentions. Takes `keyword` and `date_from`. **50cr.**
* **`GET /v1/prism/crisis-radar`** — *has something just broken?* A z-score on today's mention volume and negative share against the brand's own recent baseline, graded calm / watch / alert / crisis. Cheap enough to schedule. **15cr baseline; `confirm=true` escalates to a deeper confirmation pass at 45cr.**
* **`GET /v1/prism/crisis-postmortem`** — *who said what first?* Reconstructs an incident as a timeline across web, Reddit, Hacker News, and social, with an origin, a peak, a propagation sequence, and a grounded narrative. Takes `brand`. **35cr.**
* **`GET /v1/prism/earned-media`** — *who wrote about us?* Deduped, ranked news + tech-press + fresh-web clips with an outlet-coverage rollup. Pass `competitor` to see which outlets covered them and not you. Takes `brand`. **25cr.**
* **`GET /v1/prism/campaign`** — *did the campaign actually lift anything?* Pre / during / post volume against your window, cross-platform engagement, and ranked top amplifiers. Takes `hashtag` **or** `phrase`. **35cr.**
* **`GET /v1/prism/demand-signals`** — *is consumer interest in this product rising?* Fuses web mention slope, Reddit posting velocity, commerce review levels, and (when you pass a store id) app-review velocity into one published demand index with the arithmetic shown. Takes `keyword`. **30cr.**
```bash
# Is the conversation moving against us, and by how much?
curl "https://www.socialcrawl.dev/v1/prism/crisis-radar?brand=Figma" \
-H "x-api-key: sc_your_api_key_here"
```
Creators — "should we work with this person?" [#creators--should-we-work-with-this-person]
* **`GET /v1/prism/handle-audit`** — *is this handle worth pulling at all?* Scores a handle across platforms, ranks the best ones, and projects the data volume and credits a full pull would cost. Run it before you spend on the pull. Takes `handle`. **5cr for up to 4 platforms, +1cr per extra platform, so 5-8cr.**
* **`GET /v1/prism/creator-card`** — *who is this handle, everywhere?* One unified author card per platform — followers, verified status, bio, ids — with `null` on platforms where the handle does not exist. No scoring, just the profiles. **5cr for up to 4 platforms, +1cr per extra, so 5-8cr.**
* **`GET /v1/prism/creator-vet`** — *is it safe to pay this creator?* Engagement quality, commenter authenticity, posting cadence, and controversy signals from news and forums, in one verdict. Takes `handle`. **50cr; `include=cross_platform` widens it to other networks at 75cr.**
* **`GET /v1/prism/audience-overlap`** — *are we booking the same audience twice?* Jaccard overlap between two TikTok creators' commenting audiences, with shared-fan count, per-creator unique counts, and a confidence label. Takes `handle_a` and `handle_b`. **20cr.**
* **`GET /v1/prism/voice`** — *what has this person been saying?* One time-merged feed of a handle's public posts across X, Threads, Bluesky, and Truth Social, plus which of those they are actually on. Takes `handle`. **5cr.**
```bash
# 1. Vet the handle and get a cost projection before committing
curl "https://www.socialcrawl.dev/v1/prism/handle-audit?handle=mkbhd" \
-H "x-api-key: sc_your_api_key_here"
# 2. If it scores well, run the full partnership check
curl "https://www.socialcrawl.dev/v1/prism/creator-vet?handle=mkbhd&platform=youtube" \
-H "x-api-key: sc_your_api_key_here"
```
Commerce and apps — "what do buyers actually say?" [#commerce-and-apps--what-do-buyers-actually-say]
* **`GET /v1/prism/product-reviews`** — *what do buyers say about this product across shops?* Amazon + Google Shopping + Trustpilot reviews folded into a per-source rating, a retailer comparison, and the themes moving the rating. Takes `query`, `asin`, **or** `gid`. **30cr.**
* **`GET /v1/prism/review-integrity`** — *should I believe those ratings?* A deterministic, statistical verdict on whether a product's reviews look genuine, comparing its ratings across Amazon, Google Shopping, Trustpilot, and the open web. Same identifiers as `product-reviews`. **30cr.**
* **`GET /v1/prism/app-reviews`** — *what are users writing in the stores?* Google Play and App Store reviews together: rating summaries, topic clusters, sentiment over time, feature requests, and developer reply rate. **10cr for one store, 15cr for both** — the price follows how many store ids or `stores` members you pass.
* **`GET /v1/prism/apps-lookup`** — *how does the listing itself compare?* One app's two store listings side by side — rating, installs, price, the gap between stores — with a title-match confidence guard so two apps sharing a name are not merged. Takes `title`, `google_play_id`, **or** `app_store_id`. **30cr.**
`product-reviews` tells you what buyers said; `review-integrity` tells you whether to trust the stars. `app-reviews` covers review text; `apps-lookup` compares the listings.
```bash
# Reviews for one product across marketplaces
curl "https://www.socialcrawl.dev/v1/prism/product-reviews?asin=B0DGHMNQ5Z" \
-H "x-api-key: sc_your_api_key_here"
```
Developer ecosystem — "how is this tool landing with engineers?" [#developer-ecosystem--how-is-this-tool-landing-with-engineers]
* **`GET /v1/prism/devtool-pulse`** — *ongoing health of a dev tool.* Repo dossier + Hacker News reaction + Reddit chatter + dev-blog echo, with a summary label. Takes `query`. **20cr.**
* **`GET /v1/prism/launch-echo`** — *how did one launch land?* The top Hacker News threads and their comments, the blog echo, and optionally the repo behind it. This is the single-moment view; `devtool-pulse` is the standing one. Takes `query`. **20cr.**
* **`GET /v1/prism/org-radar`** — *size up a whole GitHub org.* Its top repos, each expanded into a full dossier (releases, open-issue load, top feature request, top complaint), rolled up. Takes `org`. **1cr base + 5cr per repo expanded, up to 10 repos, so 6-51cr** — set `repos` to control it.
```bash
curl "https://www.socialcrawl.dev/v1/prism/org-radar?org=vercel&repos=3" \
-H "x-api-key: sc_your_api_key_here"
```
AI visibility and research [#ai-visibility-and-research]
* **`GET /v1/prism/ai-visibility`** — *do AI assistants mention us?* Runs a prompt set against several AI engines, repeated, and reports per-brand appearance percentage per engine plus a ranking of the domains those answers cite. No per-platform endpoint covers this. **2cr per probe, where a probe is one prompt × one run × one engine**, so a 5-prompt × 3-run × 2-engine sweep is 60cr. The ceiling across the widest possible sweep is 1605cr, so set `prompts`, `runs`, and `engines` deliberately, or use `preset=quick|standard|deep`, which sets `runs` and caps `prompts` for a flat probe budget. The engines are Perplexity Sonar and Grok, and appearance is detected deterministically via recognition tokens rather than by a model's judgement. Add `include=web_baseline` to see which AI-cited domains you do not yet rank on.
* **`GET /v1/prism/answers`** — *what do the AI search engines say, and do they agree?* One question sent to Perplexity, Grok, and Tavily, each answer kept verbatim, citations merged, plus an agreement matrix. Takes `query`. **15cr.**
* **`GET /v1/prism/audience-questions`** — *what does this audience actually ask?* Real questions harvested from Reddit and YouTube threads, clustered by intent (who / what / why / how / vs) in the audience's own wording. Takes `topic`. **30cr.**
```bash
# Start narrow: 1 engine, 1 run, a short prompt list
curl "https://www.socialcrawl.dev/v1/prism/ai-visibility?brand=SocialCrawl&topic=social%20media%20api&engines=perplexity&runs=1" \
-H "x-api-key: sc_your_api_key_here"
```
Go-to-market and hiring [#go-to-market-and-hiring]
* **`GET /v1/prism/leads`** — *who is shopping for a competitor's replacement right now?* A ranked feed of public posts and comments where people ask for alternatives to a named competitor or say they are switching away. Takes `competitor`. **50cr.**
* **`GET /v1/prism/employer-brand`** — *what is it like to work there, according to everyone but them?* Reddit, web, YouTube, and Naver chatter about working at a company, contrasted with the tone of its own LinkedIn voice when you pass `linkedin_url`. Takes `company`. **30cr.**
* **`GET /v1/prism/truthsocial-pulse`** — *monitor one Truth Social account.* Profile, recent posts, detail drill on the top ones, and the news echo, with an activity and sentiment read. Truth Social has no search, so this is the way to watch an account without chaining calls. Takes `handle`. **20cr.**
Korea [#korea]
* **`GET /v1/prism/korea-gap`** — *is Korea talking about this the way the rest of the world is?* The global versus Korean (Naver) conversation gap for a brand or topic: which Naver surfaces carry it, a channel-by-channel map, and translated example quotes. Takes `query`. **15cr for the web-only read; 40cr with the social leg, which is the default** — drop `social` from `include` if you only need the web comparison.
Per-object workhorses [#per-object-workhorses]
These are the cheap ones you call constantly rather than once a week.
* **`GET /v1/prism/lookup`** — paste any social or commerce URL and get the right endpoint's unified response back. It sniffs the platform and resource, dispatches, and adds **no surcharge**: you pay the resolved endpoint's own cost (a social post routes to 1cr, an Amazon product to 5cr). The `resolved` block names the platform, endpoint, and archetype so an agent knows the shape that follows.
* **`GET /v1/prism/comments`** — every comment on a TikTok, YouTube, Facebook, Reddit, Hacker News, or Instagram post, paged to the end, replies nested where the platform allows. **2-200cr, metered by comment pages consumed; Instagram URLs are a flat 5cr.** See the pagination note below before you loop this on a large thread.
* **`GET /v1/prism/video-intel`** — one video URL to detail + stats + top comments + a commenter sample, across YouTube, TikTok, Rumble, and Instagram. **5cr; adding `include=transcript` makes it 15cr.**
* **`POST /v1/prism/post-stats`** — up to 100 mixed-platform post URLs, one row of current engagement per URL, in the order you sent them. **Metered per successful URL at that URL's own platform rate: 1cr on most platforms, 5cr for Instagram and LinkedIn.** Dead, errored, and unsupported URLs are refunded and never fail the batch.
* **`POST /v1/prism/profiles`** — up to 50 `(platform, handle)` pairs to one canonical Author per row, byte-identical to the single `GET` profile endpoint. **Metered per item at each platform's own tier: 1cr on most, 5cr on LinkedIn.** Only successful rows are charged. Supported on instagram, tiktok, youtube, twitter, threads, twitch, snapchat, truthsocial, bluesky, kwai, linkedin, and facebook. That roster is this endpoint's own, and is unrelated to the `/v1/search/everywhere` fan-out.
* **`POST /v1/prism/comment-lookup`** — re-check up to 25 comments you already know about, each item either `{ comment_url }` or `{ platform, post_url, comment_id }`, each result marked found / not found / errored / deferred. This is the batch sibling of the single-comment resolvers on TikTok and Instagram. **Metered per item — TikTok 2cr, Instagram 5cr, more with `deep_scan` — and only `found` items are charged.** The whole batch holds at most 100 credits. Store each row's `lookup.position_hint` and pass it back next run to keep a daily refresh near the floor.
```bash
# One URL, whatever platform it is
curl "https://www.socialcrawl.dev/v1/prism/lookup?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
-H "x-api-key: sc_your_api_key_here"
# Refresh engagement on a batch of posts
curl -X POST "https://www.socialcrawl.dev/v1/prism/post-stats" \
-H "x-api-key: sc_your_api_key_here" \
-H "content-type: application/json" \
-d '{"urls":["https://www.tiktok.com/@nasa/video/7259262686435118378","https://www.youtube.com/watch?v=dQw4w9WgXcQ"]}'
```
`prism/comments`
is the one composite whose cost is genuinely unbounded by your request shape — it pages a thread to completion and bills per page, from
**2cr up to 200cr on a single call**
. A post with tens of thousands of replies will spend the whole budget. Cap it with
`max`
or
`limit`
before you point it at a viral thread.
What Prism composites can I access? [#what-prism-composites-can-i-access]
Five more cross-platform composites live outside the
`/v1/prism/...`
namespace because they belong to a single source's vocabulary —
`/v1/search/everywhere`
,
`/v1/search/news`
,
`/v1/search/forums`
,
`/v1/reddit/omni-search`
, and
`/v1/naver/brief`
— as does the per-platform
`/v1/{platform}/profile/full`
. They behave like composites and are priced like them, they just are not on this page's roster. Browse them all on the
[Prism overview](/prism)
.
How is Prism priced? [#how-is-prism-priced]
Composites are priced per call, not per leg. Three shapes exist:
* **Flat** — one price per call regardless of how many legs run. `reputation` (30cr), `brand-mentions` (50cr), `leads` (50cr), `campaign` (35cr), `crisis-postmortem` (35cr), and `answers` (15cr) all work this way.
* **Param-derived** — the price is fixed by the request shape, so you can compute it before you call. `handle-audit` and `creator-card` are 5cr for up to 4 platforms and +1cr per extra; `share-of-voice` is per brand; `org-radar` is per repo; `app-reviews` is per store; `crisis-radar`, `creator-vet`, `korea-gap`, and `video-intel` each step up once when you opt into their deeper mode.
* **Metered** — a ceiling is held upfront and the unused portion is refunded, because the work depends on what the data turns out to be. `prism/comments` (2-200cr) and `prism/ai-visibility` (2cr per probe) are the two to watch. The three `POST` bulk endpoints are metered too, but **per item at each row's own platform rate**, so a 50-handle `profiles` batch of TikTok handles is 50cr while the same batch of LinkedIn handles is 250cr. Only successful rows are charged.
Quote ranges rather than floors when you budget: the `` table above shows each composite's base tier price, which is the bottom of the range for the metered and param-derived ones.
For `handle-audit`, a public response-cache hit costs 0 credits. A non-200 execution failure after deduction receives a full refund; request-validation errors happen before billing. If every leg fails, the whole call is refunded. See [Endpoint pricing](/docs/endpoint-pricing.md) for the full table.
What should I know about Prism data? [#what-should-i-know-about-prism-data]
* Composites use `GET` with query parameters, except the bulk endpoints (`prism/post-stats`, `prism/profiles`, `prism/comment-lookup`), which take a `POST` JSON body.
* Authentication via the `x-api-key` header.
* Responses follow the unified SocialCrawl schema, so a profile returned by a composite is byte-identical to the same profile from its native endpoint.
* Several composites take an `include` CSV that switches optional legs on or off. On `share-of-voice`, `korea-gap`, `creator-vet`, and `video-intel` that CSV also moves the price, so read it as a cost control rather than a display flag.
* Long-running composites can stream Server-Sent Events when you send `Accept: text/event-stream`, emitting each leg as it settles. This is the right mode for the 30cr-and-up composites, which do real fan-out work before they answer.