# Prism Handle Audit API (https://www.socialcrawl.dev/platforms/prism/handle-audit)

> Decide whether to pull a handle before paying for a full collection. Score model 2.0.0 returns nullable top-level and per-platform scores, explicit evidence and component coverage, surface estimates, and `legs[]` diagnostics. Unknown numeric values are `null`, not zero. Output is deterministic only for the same (`score_version`, `evidence_fingerprint`) and returned evidence; a later live collection may produce different evidence and a different score. Stale-if-error evidence is eligible for at most 24 hours, and future-dated evidence more than 300 seconds ahead is rejected. 5 credits for any selection of up to 4 supported platforms; +1 credit per selected platform beyond 4. Every successful HTTP 200 receives the full request-shaped charge with no partial refund. A non-200 execution failure receives a full refund when every requested platform is a definitive miss or cannot return usable profile evidence. Scores are advisory estimates from public evidence, not calibrated probabilities.

TL;DR: `GET /v1/prism/handle-audit` costs 5 credits for any selection of up to 4 supported platforms; +1 credit per selected platform beyond 4 and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Request scope

- Default platforms: TikTok, Instagram, YouTube, and X.
- Optional platforms: Threads, Bluesky, and Truth Social.
- Unsupported platforms: Reddit.
- Pricing: 5 credits for any selection of up to 4 supported platforms; +1 credit per selected platform beyond 4.
- Cache: An exact normalized request is cached for 30 minutes; an exact cache hit costs 0 credits.

## Response contract

- Supported platforms are tiktok, instagram, youtube, twitter, threads, bluesky, truthsocial. Default platforms are tiktok, instagram, youtube, twitter. Optional platforms are threads, bluesky, truthsocial. Reddit is deferred and not supported.
- Any unknown platform rejects the whole request with HTTP 400 before billing.
- The identity may be a bare handle or canonical supported profile URL. A YouTube channel ID is YouTube-only: omit `platforms` to audit YouTube or set `platforms=youtube`; other canonical profile URLs do not narrow the default fanout.
- YouTube sampled-post collection sends includeExtras=true.
- Profile evidence states are live, stale, not_found, and unavailable. Posts evidence states are sampled, observed_empty, not_supported, not_found, and unavailable. Stale platforms are also listed in `stale_platforms`. Unknown numeric values are null, not zero, and decision-grade post evidence is required for scoring.
- When a platform's profile evidence is not_found, its `not_found_reason` says why: account_gone (removed, renamed, or never existed), account_private (the account exists but is not publicly readable), or handle_unresolved (no source stated a cause), the same vocabulary the profile endpoints publish as `error.details.reason`. `not_found_reason` is null on every platform whose profile was found or not observed. It is reported only and never changes the score or verdict.
- `observed_empty` is decision-grade evidence of an empty posting history; `days_since_last_post`, `media_fraction`, `avg_text_length`, and the `content_richness` score stay null because no posts were observed.
- Explicitly empty text is observed as length 0 and explicitly empty media is observed as false; unknown text or media stays null. Content-richness uses known-only inputs and re-normalizes across the known inputs instead of treating unknowns as zero.
- `legs[]` is emitted in stable plan order. A genuinely pending leg abandoned at the global deadline is synthesized as 504 / UPSTREAM_TIMEOUT / 0 credits; an early rejected dispatch is 502 / UPSTREAM_ERROR / 0 credits, including when compatible stale evidence recovers the response. A terminal profile failure emits no speculative posts leg.
- Scores are reproducible only when `score_version` and `evidence_fingerprint` are unchanged; score and evidence fields can be null when decision-grade evidence is unavailable.
- Collection has a 6.4-second default budget, a 6.5-second hard cap, and a 7-second public API target. These are configured targets, not measured v2 performance.
- Process-local monotonic last-known-good ordering prevents older writers within one process; global atomic CAS remains future work.
- With `relevant_to`, up to 25 of the posts already sampled (live evidence only, taken in turn across platforms) are judged against your subject by the same published relevance rule as `relevance=filter`. `domain_relevance.score` is the share kept, 0 to 100, with the posts judged listed in `judged_posts`.
- `score_with_domain_relevance` is 0.7 x `score` + 0.3 x `domain_relevance.score`, and `verdict_with_domain_relevance` applies the same thresholds to it. `score`, `verdict`, the five base components, their weights and `evidence_fingerprint` never read the subject.
- `domain_relevance` is null with a `_warnings` entry when fewer than 3 posts could be judged (`domain_relevance_insufficient_sample`) or the judging step did not answer (`domain_relevance_unavailable`). It is a judged estimate to review, not a measurement. Without `relevant_to` none of these fields is present.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | yes | The identity to audit. Accepts a bare handle, a leading @, a supported profile URL, or a YouTube channel ID. A YouTube channel ID is YouTube-only: omit `platforms` or set `platforms=youtube`. |
| `platforms` | no | CSV subset of tiktok,instagram,youtube,twitter,threads,bluesky,truthsocial (default: tiktok,instagram,youtube,twitter). Names are case-insensitive and deduplicated. Unknown platforms are rejected. At most 8 CSV members before deduplication. |
| `sample` | no | Integer from 1 to 25: recent posts sampled per found platform for engagement and activity metrics (default 10). |
| `relevant_to` | no | Optional. Your subject in up to 200 characters, for example relevant_to=video games. Name ONE subject: `A and B` is read as posts about both. Adds domain_relevance (the share of sampled posts about it) and score_with_domain_relevance next to the unchanged score. No extra charge. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/prism/handle-audit" \
  --data-urlencode "handle=mrbeast" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### What does the Prism Handle Audit API return?

Returns a scored audit of a handle across platforms: a verdict, per platform scores, follower and activity signals, and an estimate of the data volume and credits a full pull would cost. The response uses the same JSON envelope as every SocialCrawl endpoint, with the data, credits_used and request_id fields.

### When should I use the Prism Handle Audit endpoint?

Use it to vet a creator or brand name across platforms in one call instead of checking each network separately.

### How much does the Prism Handle Audit API cost?

The price depends on the request, from 5 to 8 credits per call. Every new account gets 100 free credits. Credits for failed or empty calls are refunded automatically, and there is no subscription.

### What parameters does the Prism Handle Audit API need?

The one required parameter is handle (the identity to audit). It also accepts 3 optional parameters, all listed on this page.

### How do I call the Prism Handle Audit API?

Send a GET request to https://www.socialcrawl.dev/v1/prism/handle-audit?handle=mrbeast with your API key in the x-api-key header. An Authorization: Bearer header works too.

See the full Prism API: https://www.socialcrawl.dev/platforms/prism

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- What does the SocialCrawl Prism Handle Audit API return?
- How do I get Prism Handle Audit data with the SocialCrawl API?