# Prism Profiles API (https://www.socialcrawl.dev/platforms/prism/profiles)

> Batch profile lookup for handle vetting. POST a JSON body with an `items` array of 1-50 `{ platform, handle, custom_id? }` objects (handle accepts an @handle, a bare handle, or a pasted profile URL); returns one row per item: the canonical Author object (same shape as the single GET profile endpoint), a `status` of ok / not_found / unsupported / error / deferred, the caller's `custom_id` echoed, and the credits that row cost: in input order. Per-item isolation: one dead or private handle never fails the batch. Billing is per item at each platform's own credit tier (most platforms 1 credit; LinkedIn 5); only successful rows are charged, everything else is refunded. Supported platforms: instagram, tiktok, youtube, twitter, threads, twitch, snapchat, truthsocial, bluesky, kwai, reddit, telegram, linkedin (a member, or a company page as a `linkedin.com/company/…` URL), facebook. A LinkedIn lookup that is rate limited is retried once and then answered `deferred` at no charge: re-request it. Never cached. Optionally streams Server-Sent Events when the client sends `Accept: text/event-stream`. Send `include: "posts"` (up to 25 items) to add each handle's first page of posts beside its profile: every ok row gains a `posts` block with the same post rows, `next_cursor` and `has_more` as that handle's own post list endpoint (`endpoint` names it: instagram profile/posts, tiktok profile/videos, youtube channel/videos, twitter user/tweets, threads user/posts, facebook profile/posts, reddit profile/posts, telegram profile/posts, linkedin profile/posts or company/posts; other platforms answer `posts.status: "unsupported"`). `since` on the body and `stop_at_id` on an item stop each page at a date or at a post you already hold, as on those endpoints, and `posts.stopped_at` says which. Add `posts_limit` (1 to 100) to walk each handle's post list until that many posts are held: `posts.pages` is the pages charged and `posts.stopped` says why the walk ended (`limit`, `end`, `window`, `page_cap`). `include: "posts,about"` also returns `activity` (`last_post_at`, `posts_30d`, `posts_90d`, `media_mix`) and `stats` (`avg_likes`, `avg_comments`, `engagement_rate`) on every row, computed from the posts held. Add `comments` to `include` (it implies posts) to read the comments of each handle's top posts: the `comments_top_posts` posts (default 3) with the most comments among the posts walked (a post without a comment count is ranked by views after them, or rank all by views with `comments_select_by: "views"`) each gain `comments` with `items` (the same comment rows as that platform's comment endpoint: instagram, tiktok and facebook post/comments, youtube video/comments, twitter tweet/replies, linkedin post/comments, reddit post/comments, threads post/comments), `total` (the post's comment count), `truncated` and `next_cursor`, up to `comments_per_post` (default 20) per post; the row's `comments` block gives `status` (ok, partial, failed, deferred, empty, unsupported) and the credits. One post that fails never drops the row. The profile in `data` is unchanged.

TL;DR: `POST /v1/prism/profiles` costs 1 credit per successful row on most platforms and 5 on LinkedIn, charged at each handle's own platform tier. Up to 50 items per call: the call holds the summed worst case up front and refunds every not_found, unsupported, errored and deferred row. With include: "posts" (up to 25 items) a row also costs its post list page, 1 credit (5 on LinkedIn), charged only when that page came back with posts. With posts_limit the call walks the list and charges each page that came back with posts; it holds the most pages the limit can take (10 at most per handle) and refunds the unused ones, and a dry run shows that hold. With include: "comments" each selected post's comments cost what that platform's comment endpoint charges per page (1 credit on most platforms, 5 on Instagram, LinkedIn and Reddit), charged only for pages that came back with comments; the call holds comments_top_posts times the pages comments_per_post can take and refunds the rest and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `items` | yes | JSON array of 1-50 items (1-25 with include: "posts"). Each item is `{ "platform": "tiktok", "handle": "@scout2015", "custom_id"?: "…", "stop_at_id"?: "…" }`. `handle` accepts an @handle, a bare handle, or a pasted profile URL. `stop_at_id` (only with include: "posts") is the id or URL of the newest post you already hold for that handle: its page stops just before it. |
| `include` | no | Optional. A comma-separated set of "posts" and "about". "posts" adds the handle's first page of posts to every ok row (`posts`), for the price of that page (1 credit), charged only when the page came back with posts. Caps the batch at 25 items. "about" reads an Instagram handle through its About panel (same price) and adds `country` to a row when the account declares one (an Instagram country, a Facebook page address, a TikTok account region, or a YouTube channel country), as an ISO code with its `source`; beside "posts" it also adds `activity` and `stats`, computed from the posts held. "comments" implies "posts" and reads the comments of each handle's top posts (see comments_top_posts), priced per page at that platform's comment endpoint price. |
| `since` | no | Optional, with include: "posts". Only posts published on or after this date (YYYY-MM-DD or an ISO 8601 timestamp); each page stops at the first older post and `posts.stopped_at` is `since`. |
| `posts_limit` | no | Optional, with include: "posts". An integer from 1 to 100: walk each handle's post list until that many posts are held (each page that came back with posts is charged, up to 10 pages per handle). Without it, one page. |
| `comments_top_posts` | no | Optional, with include: "comments". An integer from 1 to 50 (default 3): how many of each handle's walked posts, those with the most comments, get their comments read. |
| `comments_per_post` | no | Optional, with include: "comments". An integer from 1 to 200 (default 20): the most comments read per selected post, walked page by page on that platform's comment endpoint. |
| `comments_select_by` | no | Optional, with include: "comments". "comments" (default) picks the posts with the most comments, then posts without a comment count by views; "views" picks the most viewed posts. (comments \| views) |

## Code example

```bash
curl -X POST "https://www.socialcrawl.dev/v1/prism/profiles" \
  -H "x-api-key: sc_YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"items":[{"platform":"tiktok","handle":"@scout2015"},{"platform":"linkedin","handle":"williamhgates","custom_id":"vet-1"}]}'
```

## FAQ

### What does the Prism Profiles API return?

Returns a profile for each platform and handle pair you send, in the order you sent them, with a status per row and the same shape as the single profile call. 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 Profiles endpoint?

Use it to vet many handles at once instead of calling the profile endpoint per handle; creator-card is for one handle across several platforms. Not for one handle across several platforms (prism/creator-card), or a single profile where its own endpoint is simpler (tiktok/profile, instagram/profile).

### How much does the Prism Profiles API cost?

The price depends on the request, from 1 to 126375 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 Profiles API need?

The one required parameter is items (jSON array of 1-50 items). It also accepts 6 optional parameters, all listed on this page.

### How do I call the Prism Profiles API?

Send a POST request to https://www.socialcrawl.dev/v1/prism/profiles with a JSON body and 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 Profiles API return?
- How do I get Prism Profiles data with the SocialCrawl API?