# Prism (/docs/prism)

Cross-platform composites, one call fans out to many sources and returns one merged, computed answer

A Prism endpoint is a **composite**: one call fans out to several platforms in parallel, merges the results, and returns a single computed answer. You do not orchestrate the fan-out, the retries, or the merge yourself.

Base URL: `/v1/prism/...`

  Every count, share and score a Prism composite returns is **computed in code,
  not written by a model**. Several composites first read each row with a
  judgment (is this post about the brand, is this text a question, which search
  result is the product you meant) and publish the probability next to the row;
  code then does the counting and states the method. Where a composite uses an
  LLM to write text (topic names, a narrative), that text describes numbers
  already computed.

## What a composite is

A normal endpoint reads one thing from one source. A composite answers a question that no single source can answer, by calling several of them and doing the reconciliation work in between.

Three properties follow from that, and all three change how you write the client:

1. **A composite has legs, and 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. Read it before you read the numbers.
2. **A composite is priced per call, not per leg.** The price does not go up because a source was slow or a fan-out went wide, except where the request shape itself sets the width.
3. **A composite returns the same unified schema as its parts.** A profile inside a composite response is byte-identical to the same profile from its native endpoint, so one parser handles both.

## When to use a composite instead of N calls

Reach for a composite when the answer needs cross-source reconciliation and you would otherwise write it yourself: deduplication across platforms, weighting one source against another, matching the same entity under two different ids, or holding a fan-out open while slow legs settle.

Stay on the per-platform endpoints when you want one source's raw data, when you need a field the composite does not surface, or when you are refreshing something you already hold. `prism/lookup` and `prism/post-stats` exist precisely for that last case and are priced accordingly.

## How Prism is priced

Composites come in three pricing shapes.

| Shape             | How it works                                                                                                            | Examples                                                                                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flat**          | One price per call regardless of how many legs run                                                                      | `reputation` (30), `brand-mentions` (50), `leads` (50), `campaign` (35), `crisis-postmortem` (35), `answers` (15)                                    |
| **Param-derived** | The price is fixed by the request shape, so you can compute it before you call                                          | `handle-audit` and `creator-card` (5 for up to 4 platforms, +1 per extra); `share-of-voice` per brand; `org-radar` per repo; `app-reviews` per store |
| **Metered**       | A ceiling is held upfront and the unused portion is refunded, because the work depends on what the data turns out to be | `comments` (2-200), `ai-visibility` (2 per probe), and the four `POST` bulk endpoints                                                               |

The bulk endpoints are metered **per item at each row's own platform rate**, so a 50-handle `profiles` batch of TikTok handles is 50 credits while the same batch of LinkedIn handles is 250. Only successful rows are charged.

Quote ranges rather than floors when you budget: the roster below 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, and request-validation errors happen before billing. If every leg fails, the whole call is refunded. Every successful HTTP 200 receives the full request-shaped charge even with partial evidence, and there is no partial refund on that path.

## Quickstart

### 1. Pick a composite by the question you are 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".

### 2. Make the call

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/prism/handle-audit?handle=mrbeast" \
  -H "x-api-key: YOUR_API_KEY"
```

### 3. Read the coverage block before the numbers

A composite is a fan-out, so check which sources answered before you act on the result. `handle-audit` returns score-v2 evidence, nullable scores, component coverage, surface estimates, and leg diagnostics.

### 4. Read computed fields

Direct post and author endpoints inside a composite response may include the shared computed fields such as `engagement_rate`, `language`, and `content_category`. See [Computed fields](/docs/computed-fields.md) for formulas and null semantics.

## Brand health

_How is this brand doing right now?_

| Endpoint                          | Credits                       | What it returns                                                                                                                                             | Key parameters                                                                             |
| --------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `GET /v1/prism/reputation`        | 30                            | Trustpilot, both app stores, Google Business and web sentiment blended into one weighted score with themed pros, cons and quotes                            | `brand`, `sources`, `country`, `depth`, `place`, `axis`, `include`                         |
| `GET /v1/prism/share-of-voice`    | 20-200                        | Engagement-weighted share of voice across 2-5 brands, split web vs social, with an emotion overlay and ESOV against `market_shares`                         | `brands` (CSV), `category_code`, `market_shares`, `include`, `page_type`                   |
| `GET /v1/prism/brand-mentions`    | 50                            | Mention volume time-series, sentiment split, top sources, and a sample of recent mentions                                                                   | `keyword`, `date_from`, `date_to`, `date_group`, `page_type`                               |
| `GET /v1/prism/crisis-radar`      | 15, or 45 with `confirm=true` | A z-score on today's mention volume and negative share against the brand's own recent baseline, graded calm / watch / alert / crisis                        | `brand`, `sensitivity`, `confirm`, `baseline_days`, `date_to`                              |
| `GET /v1/prism/crisis-postmortem` | 35                            | An incident reconstructed as a timeline across web, Reddit, Hacker News and social, with an origin, a peak, a propagation sequence and a grounded narrative | `brand`, `window_start`, `window_end`, `crisis_terms`                                      |
| `GET /v1/prism/earned-media`      | 25                            | Deduped, ranked news, tech-press and fresh-web clips with an outlet-coverage rollup                                                                         | `brand`, `competitor`, `date_from`, `date_to`, `min_domain_rank`                           |
| `GET /v1/prism/campaign`          | 35                            | Pre / during / post volume against your window, cross-platform engagement, and ranked top amplifiers                                                        | `hashtag` **or** `phrase`, `window_start`, `window_end`, `pre_days`, `post_days`           |
| `GET /v1/prism/demand-signals`    | 30                            | Web mention slope, Reddit posting velocity, commerce review levels and app-review velocity fused into one published demand index with the arithmetic shown  | `keyword`, `google_play_id`, `app_store_id`, `signals`, `amazon_query`, `country`, `depth` |

`share-of-voice` is 20 credits per brand web-only and 40 per brand with social (the default), so the price is fixed by how many brands you pass and whether `include` contains `social`. Pass `competitor` to `earned-media` to see which outlets covered them and not you.

A brand name is often also a word, a song or another company. `brand-mentions`, `share-of-voice`, `earned-media`, `campaign` and `crisis-radar` judge whether each row is about your brand and publish cleaned numbers **next to** the original ones, never in place of them: `sov_pct_about_brand` beside `sov_pct`, `clipping_count_about_brand` and `top_outlets_about_brand` on `earned-media`, `top_amplifiers_about_brand` on `campaign`, `score_about_brand` and `grade_about_brand` on `crisis-radar`. Add `brand_description` (one plain sentence, such as "Samyang's spicy instant noodle brand") when the name is ambiguous. Prices are unchanged.

```bash title="cURL"
# 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: YOUR_API_KEY"
```

## Creators

_Should we work with this person?_

| Endpoint                         | Credits                  | What it returns                                                                                                                             | Key parameters                                                    |
| -------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `GET /v1/prism/handle-audit`     | 5-8                      | A handle scored across platforms, the best ones ranked, and a projection of the data volume and credits a full pull would cost              | `handle`, `platforms`, `sample`                                   |
| `GET /v1/prism/creator-card`     | 5-8                      | One unified author card per platform (followers, verified status, bio, ids), `null` where the handle does not exist                         | `handle`, `platforms`, `include`                                  |
| `GET /v1/prism/creator-vet`      | 50, or 75 cross-platform | Engagement quality, commenter authenticity, posting cadence, and controversy signals from news and forums, in one verdict                   | `handle`, `platform`, `depth`, `include`                          |
| `GET /v1/prism/audience-overlap` | 20                       | Jaccard overlap between two TikTok creators' commenting audiences, with shared-fan count, per-creator unique counts, and a confidence label | `handle_a`, `handle_b`, `platform`, `videos_per_creator`, `depth` |
| `GET /v1/prism/voice`            | 5                        | 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       | `handle`, `platforms`, `cursor`, `include`                        |

`handle-audit` and `creator-card` are 5 credits for up to 4 platforms and +1 per extra. Run `handle-audit` before you spend on the pull.

```bash title="cURL"
# 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: YOUR_API_KEY"

# 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: YOUR_API_KEY"
```

## Commerce and apps

_What do buyers actually say?_

| Endpoint                         | Credits               | What it returns                                                                                                                           | Key parameters                                                                          |
| -------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `GET /v1/prism/product-reviews`  | 30                    | Amazon, Google Shopping and Trustpilot reviews folded into a per-source rating, a retailer comparison, and the themes moving the rating   | `query`, `asin` **or** `gid`, `sources`, `country`, `depth`, `competitors`              |
| `GET /v1/prism/review-integrity` | 30                    | A deterministic, statistical verdict on whether a product's reviews look genuine, comparing its ratings across the same sources           | `query`, `asin` **or** `gid`, `sources`, `country`                                      |
| `GET /v1/prism/app-reviews`      | 10 one store, 15 both | Google Play and App Store reviews together: rating summaries, topic clusters, sentiment over time, feature requests, developer reply rate | `google_play_id`, `app_store_id`, `query`, `stores`, `country`, `language`, `depth`     |
| `GET /v1/prism/apps-lookup`      | 30                    | One app's two store listings side by side (rating, installs, price, the gap between stores) with a title-match confidence guard           | `title`, `google_play_id` **or** `app_store_id`, `stores`, `country`, `match_threshold` |

`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, and its title-match guard is what stops two apps sharing a name from being merged.

When you pass a name instead of an id, these composites (and `reputation`) look at the top few search results on each source and judge which one is the product, business or app you meant, instead of taking the first hit, so an accessory, a reseller or a same-name app is no longer graded as yours. The choice is reported per source in `entity_resolution` (`resolved_by`, `index`, `title`, `confidence`), and when no result is the right one the source is left out with `entity_not_found:<source>` in `_warnings`. Pass `asin`, `gid` or a store id to skip the judgment.

```bash title="cURL"
# Reviews for one product across marketplaces
curl "https://www.socialcrawl.dev/v1/prism/product-reviews?asin=B0DGHMNQ5Z" \
  -H "x-api-key: YOUR_API_KEY"
```

## Developer ecosystem

_How is this tool landing with engineers?_

| Endpoint                      | Credits | What it returns                                                                                                                        | Key parameters                                       |
| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `GET /v1/prism/devtool-pulse` | 20      | Repo dossier, Hacker News reaction, Reddit chatter and dev-blog echo, with a summary label                                             | `query`, `repo`, `subreddit`, `date_from`, `date_to` |
| `GET /v1/prism/launch-echo`   | 20      | The top Hacker News threads and their comments, the blog echo, and optionally the repo behind it                                       | `query`, `repo`, `threads`, `date_from`, `date_to`   |
| `GET /v1/prism/org-radar`     | 6-51    | A GitHub org's top repos, each expanded into a full dossier (releases, open-issue load, top feature request, top complaint), rolled up | `org`, `repos`, `sort`, `include`                    |

`launch-echo` is the single-moment view; `devtool-pulse` is the standing one. `org-radar` is 1 credit base plus 5 per repo expanded, up to 10 repos. Set `repos` to control it.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/prism/org-radar?org=vercel&repos=3" \
  -H "x-api-key: YOUR_API_KEY"
```

## AI visibility and research

| Endpoint                           | Credits     | What it returns                                                                                                                           | Key parameters                                                                                            |
| ---------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `GET /v1/prism/ai-visibility`      | 2 per probe | Per-brand appearance percentage per AI engine, plus a ranking of the domains those answers cite                                           | `brand`, `topic` **or** `prompts`, `competitors`, `engines`, `runs`, `preset`, `include`, `brand_domains` |
| `GET /v1/prism/answers`            | 15          | One question sent to Perplexity, Grok and Tavily, each answer kept verbatim, citations merged, plus an agreement matrix                   | `query`, `engines`, `include`                                                                             |
| `GET /v1/prism/audience-questions` | 30          | Real questions harvested from Reddit and YouTube threads (Naver KnowledgeiN for a topic in Hangul), clustered by intent (who / what / why / how / vs) in the audience's own wording | `topic`, `platforms`, `max_questions`, `threads_per_source`, `timeframe`                                  |

A probe on `ai-visibility` is one prompt times one run times one engine, so a 5-prompt, 3-run, 2-engine sweep is 60 credits. The ceiling across the widest possible sweep is 1605, 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. No per-platform endpoint covers this.

`audience-questions` judges every title and comment for whether it asks a real question, so questions written without a "?" (common in Korean) are kept and rhetorical ones are not. `methodology.question_detection` reports how many the judgment added and removed against the old question-mark rule.

```bash title="cURL"
# 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: YOUR_API_KEY"
```

## Go-to-market, hiring, and Korea

| Endpoint                          | Credits                     | What it returns                                                                                                                                                | Key parameters                                                |
| --------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `GET /v1/prism/leads`             | 50                          | A ranked feed of public posts and comments where people ask for alternatives to a named competitor or say they are switching away                              | `competitor`, `product_category`, `freshness`, `limit`        |
| `GET /v1/prism/comment-leads`     | 37 held, refunded to actual | Buyer leads from the comments under a TikTok keyword search, opening only the posts worth opening, with the bill itemised                                     | `query`, `offer`, `posts`, `open`, `comments_per_post`, `include` |
| `GET /v1/prism/employer-brand`    | 30                          | Reddit, web, YouTube and Naver chatter about working at a company, contrasted with the tone of its own LinkedIn voice                                          | `company`, `linkedin_url`, `surfaces`, `phrases`, `timeframe` |
| `GET /v1/prism/truthsocial-pulse` | 20                          | One Truth Social account's profile, recent posts, detail drill on the top ones, and the news echo, with an activity and sentiment read                         | `handle`, `drill`, `posts`, `news_query`, `cursor`            |
| `GET /v1/prism/korea-gap`         | 15 web-only, 40 with social | 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 | `query`, `include`, `date_from`, `date_to`, `display`         |

Truth Social has no search, so `truthsocial-pulse` is the way to watch an account without chaining calls. On `korea-gap` the social leg is the default. Drop `social` from `include` if you only need the web comparison.

### Buyer leads from comments

`prism/comment-leads` finds the people who want what you sell in the comments under a keyword search, and opens only the posts worth opening, because fetching and reading every post's comments is where the cost goes.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/prism/comment-leads?query=standing+desk+setup&offer=Height-adjustable+standing+desks+delivered+to+your+home" \
  -H "x-api-key: YOUR_API_KEY"
```

It searches TikTok for `query` (TikTok only for now), judges each post that reports comments for whether people who want your `offer` would plausibly comment under it, skips the clearly off-offer ones, and opens the busiest of the rest, up to `open` (1 to 20, default 12). Each fetched comment is labelled for purchase intent, for being a real question, for spam, and for whether your offer would help its author. A comment is a lead when purchase intent is at least 0.5, spam is under 0.5 and offer fit is at least 0.5. `include=askers` adds comments that ask a question your offer answers.

| Input               | Meaning                                                                          |
| ------------------- | -------------------------------------------------------------------------------- |
| `query`             | The keyword search to run (required, up to 100 characters)                       |
| `offer`             | What you sell, in one or two plain sentences (up to 300). Defaults to `query`    |
| `posts`             | How many posts to search, 1 to 90, default 30                                    |
| `open`              | The most posts whose comments are fetched, 1 to 20, default 12                   |
| `comments_per_post` | The most comments read from each opened post, 1 to 200, default 50               |

Each entry of `leads[]` carries the comment id and text, the commenter's public username and display name as the platform shows them, the post it came from and every probability. `posts_opened` and `skipped_posts` say which posts were opened and why the others were not (`no_comments`, `no_url`, `below_gate`, `over_open_limit`). `economics` shows the bill: posts searched and opened, comments fetched and judged, credits by leg, `credits.held` and `credits.refunded`, `naive_credits_estimate` (what opening every post would have cost at the same prices), `credits_saved_vs_naive` and `credits_per_lead`.

You pay for what is opened: 1 credit a search page, 1 a comment page fetched, and 1 for every started 25 comments labelled. Judging which posts to open is free. The default request holds 37 credits and refunds what did not run. Most of the saving comes from opening the busiest posts first; the judgment mainly skips posts that are clearly off-offer. Leads are labels for your own review, and nothing is contacted.

## Background screening

`prism/adverse-screen` reads the recent public posts of a person's own profiles and points a reviewer at the posts that may be adverse, each with a citation. It is built for background-screening and KYC teams.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/prism/adverse-screen?twitter=elonmusk&name=Elon+Musk&categories=fraud_or_financial_crime,violence_or_threats" \
  -H "x-api-key: YOUR_API_KEY"
```

| Input                                                                  | Meaning                                                                                                                                        |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `linkedin`, `twitter`, `facebook`, `instagram`, `threads`, `tiktok`    | One profile per platform, as a handle or a profile URL. At least one is required                                                              |
| `name`, `employer`, `city`                                             | The person's name, and optionally employer and city, for the identity check                                                                   |
| `categories`                                                           | A subset of `fraud_or_financial_crime`, `violence_or_threats`, `hate_or_harassment`, `drugs`, `sanctions_or_terror_links`, `sexual_misconduct`, `reputational_other`. Default: all |
| `since`, `limit`                                                       | Screen posts on or after a date (`YYYY-MM-DD`), and at most `limit` recent posts per profile (1 to 100, default 50)                           |
| `screen_unconfirmed`                                                   | `true` also screens profiles whose identity is only possible or could not be judged                                                           |

**Identity first.** With `name`, each profile is first checked against the named person, and only profiles judged to be their own are screened. The rest are listed in `profiles` with the verdict and are not screened, so a namesake's posts are never attributed to the person. A profile judged to be someone else is never screened, even with `screen_unconfirmed=true`. Without `name` there is no identity check and you vouch for the profiles.

**What it judges.** For each post and each category you ask for: does the author engage in, admit, threaten or promote it. A separate check keeps posts that report, quote, warn about or condemn what someone else did (news, a scam warning) from counting as the author's conduct. Every flag in `flags[]` cites its post (`platform`, `post_id`, `url`, `published_at`, an `excerpt`) with the probability per category and a severity from 1 (minor) to 3 (severe). `category_counts` counts flagged and uncertain posts, and `requires_review` is `true` when anything is flagged.

**What it never does.** There is no summary, no verdict and no score about the person, and `automated_decision` is always `false`: a flag is a pointer to a post for a human reviewer to read, and a flag alone must never reject a candidate. Political opinion, religion, health, sexuality, gender, ethnicity, nationality, age and disability are never screened or inferred. It reads public posts only; private accounts return nothing. It reads post text, not images, video or audio. `sanctions_or_terror_links` and `sexual_misconduct` had no real positives in the measurement set, so they are unmeasured; see [how we measure](/docs/labels.md#how-we-measure).

It costs 25 credits for one profile plus 10 for each further profile (4 profiles cost 55), refunded down to the profiles actually screened. A call that found profiles but screened none keeps 5. `screen_complete` is `false` when a profile or a post could not be screened, and `_warnings` says why.

## Per-object workhorses

The cheap ones you call constantly rather than once a week.

| Endpoint                        | Credits                                         | What it returns                                                                                                                                 | Key parameters                                     |
| ------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `GET /v1/prism/lookup`          | No surcharge, you pay the resolved endpoint     | Paste a link to a single post, video, product or repo and get the right endpoint's unified response back                                        | `url`, `include`                                   |
| `GET /v1/prism/comments`        | 2-200 metered, Instagram a flat 5               | Every comment on a TikTok, YouTube, Facebook, Reddit, Hacker News or Instagram post, paged to the end, replies nested where the platform allows | `url`, `max`, `replies`, `sort`, `limit`, `cursor` |
| `GET /v1/prism/video-intel`     | 5, or 15 with `include=transcript`              | One video URL to detail, stats, top comments and a commenter sample, across YouTube, TikTok, Rumble and Instagram                               | `url`, `comments`, `include`                       |
| `POST /v1/prism/post-stats`     | Metered per successful URL at its platform rate | Up to 100 mixed-platform post URLs, one row of current engagement per URL, in the order you sent them                                           | `urls`, `include`                                  |
| `POST /v1/prism/profiles`       | Metered per item at each platform's own tier    | Up to 50 `(platform, handle)` pairs to one canonical Author per row, byte-identical to the single `GET` profile endpoint, or up to 25 with each handle's first page of posts | `items`, `include`, `since`                        |
| `POST /v1/prism/comment-lookup` | Metered per item, only `found` items charged    | Re-check up to 25 comments you already know about, each result marked found / not found / errored / deferred                                    | `items`                                            |
| `POST /v1/prism/post-comments` | Metered per page at each platform's comment endpoint price | The comments under up to 25 post URLs from eight platforms, one row per URL, in the order you sent them | `items`, `per_post`, `since` |

`lookup` sniffs the platform and resource, dispatches, and adds no surcharge: a social post routes to 1 credit, an Amazon product to 5. It takes ITEM links only, so a profile, channel or storefront URL is a free 400 pointing you at that platform's own `/profile` endpoint. The `resolved` block names the platform, endpoint, and archetype so an agent knows the shape that follows.

`post-stats` bills 1 credit on most platforms, 2 for an Instagram post and 5 for LinkedIn; `profiles` bills 1 credit on most platforms and 5 for LinkedIn. Dead, errored, and unsupported URLs are refunded and never fail a `post-stats` batch, and only successful rows are charged on `profiles`. `profiles` supports 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 universal-search fan-out. With `"include": "posts"` (up to 25 items) each `ok` row also carries a `posts` block with that handle's first page of posts on Instagram, TikTok, YouTube, X, Threads and Facebook, for 1 credit more per row whose page came back with posts; `since` and a per-item `stop_at_id` stop each page where your last check ended. See [Batch endpoints](/docs/batch.md#profiles-with-their-latest-posts). For more than 50 handles or post URLs, `POST /v1/prism/jobs` runs up to 5,000 `profiles` or `post-stats` items in the background at the same per-row prices; see [Background jobs](/docs/batch.md#background-jobs-for-thousands-of-items).

`comment-lookup` takes each item as either `{ comment_url }` or `{ platform, post_url, comment_id }`, bills TikTok at 2 and Instagram at 5 (more with `deep_scan`), and holds at most 100 credits for the whole batch. Store each row's `lookup.position_hint` and pass it back next run to keep a daily refresh near the floor.

```bash title="cURL"
# 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: YOUR_API_KEY"

# Refresh engagement on a batch of posts
curl -X POST "https://www.socialcrawl.dev/v1/prism/post-stats" \
  -H "x-api-key: YOUR_API_KEY" \
  -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
  **2 up to 200 credits 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.

## All endpoints

  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 are just not on
  this page's roster.

## Platform notes

- **Composites use `GET` with query parameters**, except the bulk endpoints (`post-stats`, `profiles`, `comment-lookup`, `post-comments`), which take a `POST` JSON body.
- **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 30-credit-and-up composites, which do real fan-out work before they answer.
- **A leg can fail without failing your call.** Read the coverage signal before the numbers.
- Responses follow the unified SocialCrawl schema, so a profile returned by a composite is byte-identical to the same profile from its native endpoint.

## Next steps

- [Universal search](/docs/search/everywhere.md): The composite that fans one query across social platforms.
- [Endpoint pricing](/docs/endpoint-pricing.md): The full registry-derived cost table.
- [Streaming](/docs/streaming.md): Consuming a composite leg by leg over SSE.