--- title: "Turn a person's or a company's name into ranked candidate accounts on Instagram, TikTok, X and LinkedIn (Threads on request), with a match level and a match confidence per platform, for human review." method: GET path: "/prism/find-accounts" tags: ["prism"] --- # Turn a person's or a company's name into ranked candidate accounts on Instagram, TikTok, X and LinkedIn (Threads on request), with a match level and a match confidence per platform, for human review. `GET /prism/find-accounts` ## Request - Base URL: `https://www.socialcrawl.dev/v1` - URL: `https://www.socialcrawl.dev/v1/prism/find-accounts` - Auth: API key in header `x-api-key` Runs the existing account searches for `name` on each platform (`instagram/search/profiles`, `tiktok/search/users`, `twitter/search/users`, and `linkedin/search/people` for a person or `linkedin/search/companies` for a company), keeps the top `candidates` public accounts of each (private accounts are dropped), and ranks them. Each platform returns `candidates` (rank, handle, display name, profile URL, followers, verified flag, a bio excerpt and `choice_probability`, the judged probability that this account is the target's own) and one `match`: `handle` is the leading candidate, `level` is `same`, `possible` (connected but not shown to be the target's own, such as a fan or regional account), `different`, `uncertain` (the ranking was flat or the check was unsure), or `none` (none of the candidates is the target's own account, or the search found nothing), with `confidence` (the weaker of the ranking and the check), `basis` and `evidence` (`website_match`, `cross_link`, `bio_consistent`, `fan_or_parody`). The leading candidate is always checked a second time against the name and context you sent; a ranking alone is never a match. With `website`, an account that links to that site and is platform-verified is taken as the match without judging (`basis: exact_link`); an unverified account linking to it is judged like the rest. `employer` (person only) and `location` give the judgment context. These are automated labels for a human reviewer, not an identification: `automated_decision` is false and the response never states who runs an account. If the judgment is unavailable, candidates come back in search order with `match.level` null, `_warnings` says why, and the judging credits are refunded. LinkedIn is included by default for a company only, because its search costs 10 credits. Threads (`threads/search/users`) is searched only when named in `platforms`. Each platform's `match` also carries `match_confidence` (0 to 1, null when there is no candidate), how sure the response is that `handle` is the target's own account, and `accepted`, true when `match_confidence` is at or above `match_confidence_floor` (0.6). `data.items` lists the accepted accounts, one per platform at most, as canonical author rows with their `match`; a platform below the floor lists no item, so a reader of `items` gets no match rather than a guess. With `website`, `match.evidence` adds `domain` (the site checked), `domain_match` and `domain_source` (`external_url` or `bio`): whether the leading account's own website, or else a link or a domain in its bio, is that domain or a subdomain of it. The account's own website is the strong evidence: it lifts a flat ranking (`uncertain`) or a `same` to at least 0.9. A link or domain in the bio is weaker, because a reseller or a fan names the site too: it lifts only a `same`, to at least 0.75. An email address at the domain is not a domain match, an own website on another domain overrules the bio, and a `possible` or `different` account is never lifted. A profile, link-in-bio or site-builder page given as `website` (LinkedIn, a Google Site, a link page) is not checked. With `profile_check=true`, the leading candidate on Instagram, TikTok, Threads and (for a company) LinkedIn, whose search results carry no bio or website, is looked up on its profile before the check, so the domain check and the check read its bio and website; X search results already carry both. ## Query parameters - `name` string, required - `type` 'person' | 'company' - `platforms` string - `employer` string - `location` string - `website` string - `candidates` integer - `profile_check` boolean ## Headers - `Cache-Control` string - `Idempotency-Key` string ## Response `200` Successful response - object - `success` boolean, required: Whether the request succeeded - `platform` string, required: Platform name - `endpoint` string, required: API endpoint path - `data` object, required: Platform-specific response data - `metrics` object: Key performance metrics - `total_views` integer: Total view count - `total_likes` integer: Total like count - `total_comments` integer: Total comment count - `engagement_rate` number: Computed engagement rate (0-1) - `period` string, nullable: Time period for the analytics data - `breakdown` object[], nullable: Per-item or per-period breakdown - `_warnings` string[]: Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'. - `credits_used` integer, required: Number of credits consumed - `credits_remaining` integer, nullable, required: Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction. - `request_id` string, required: Unique request identifier for support - `cached` boolean, required: Whether the response was served from cache - `idempotent_replay` boolean: True only when this response is an idempotency replay - `meta` object: Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it. - `hint` object: One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces. - `code` string: creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat - `message` string: One sentence for a person or an agent to read. - `method` string: GET or POST. - `path` string: The call the hint points to. ## Other responses - `400`: Invalid request - missing or malformed parameters - `401`: Unauthorized - missing or invalid API key - `402`: Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit - `404`: Not found - the endpoint does not exist, or the requested resource was not found upstream - `405`: Method not allowed - wrong HTTP verb for this endpoint - `409`: Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation - `410`: Gone - the discover run's retention passed and its rows were deleted; start a new run - `413`: Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling - `422`: Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC) - `429`: Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits. - `500`: Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit - `502`: Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge - `503`: Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge - `504`: Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After --- [API](https://skmtc.dev/socialcrawl/apis/socialcrawl-api.md) · [All operations](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/revisions/a0ad2511004a?raw)