---
title: "Should you pull this handle? One call scores a handle across platforms, ranks the best ones, and projects the data volume + credit cost to pull it."
method: GET
path: "/prism/handle-audit"
tags: ["prism"]
---

# Should you pull this handle? One call scores a handle across platforms, ranks the best ones, and projects the data volume + credit cost to pull it.

`GET /prism/handle-audit`

## Request

- Base URL: `https://www.socialcrawl.dev/v1`
- URL: `https://www.socialcrawl.dev/v1/prism/handle-audit`
- Auth: API key in header `x-api-key`

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.

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.

## Query parameters

- `handle` string, required
- `platforms` string
- `sample` integer
- `relevant_to` string

## Headers

- `Cache-Control` string
- `Idempotency-Key` string

## Response `200`

Successful response

- object
  - `success` boolean, required: Whether the request succeeded
  - `platform` string, required: Composite platform namespace
  - `endpoint` string, required: API endpoint path
  - `data` object, required: Handle-audit score-v2 result and evidence contract
    - `handle` string, required
    - `verdict` 'pull' | 'pull_partial' | 'skip' | 'not_found' | 'insufficient_evidence', required
    - `score` integer, nullable, required
    - `score_status` 'complete' | 'partial' | 'insufficient_evidence', required
    - `score_version` '2.0.0', required
    - `evidence_fingerprint` string, required
    - `computed_at` string, date-time, required
    - `evidence_as_of` object, required
      - `oldest` string, date-time, nullable, required
      - `newest` string, date-time, nullable, required
    - `confidence` object, required
      - `tier` 'high' | 'medium' | 'low', required
      - `reason` string, required
    - `evaluated_platforms` string[], required
    - `skipped_platforms` string[], required
    - `stale_platforms` string[], required
    - `score_components` object, required
      - `presence` number, nullable, required
      - `audience` number, nullable, required
      - `engagement` number, nullable, required
      - `activity` number, nullable, required
      - `content_richness` number, nullable, required
    - `component_availability` object, required
      - `presence` boolean, required
      - `audience` boolean, required
      - `engagement` boolean, required
      - `activity` boolean, required
      - `content_richness` boolean, required
    - `component_coverage` object, required
      - `presence` 'complete' | 'partial' | 'unavailable', required
      - `audience` 'complete' | 'partial' | 'unavailable', required
      - `engagement` 'complete' | 'partial' | 'unavailable', required
      - `activity` 'complete' | 'partial' | 'unavailable', required
      - `content_richness` 'complete' | 'partial' | 'unavailable', required
    - `effective_weights` object, required
      - `presence` number, required
      - `audience` number, required
      - `engagement` number, required
      - `activity` number, required
      - `content_richness` number, required
    - `available_weight` number, required
    - `score_aggregation` object, required
      - `best_platform` 'tiktok' | 'instagram' | 'youtube' | 'twitter' | 'threads' | 'bluesky' | 'truthsocial', nullable, required
      - `best_score` number, nullable, required
      - `mean_score` number, nullable, required
      - `best_weight` 0.7, required
      - `mean_weight` 0.3, required
    - `best_platforms` string[], required
    - `platforms` object, required
      - `tiktok` object
        - `found` boolean, required
        - `score` integer, nullable, required
        - `score_status` 'complete' | 'partial' | 'insufficient_evidence', required
        - `score_components` object, required
          - `presence` number, nullable, required
          - `audience` number, nullable, required
          - `engagement` number, nullable, required
          - `activity` number, nullable, required
          - `content_richness` number, nullable, required
        - `component_availability` object, required
          - `presence` boolean, required
          - `audience` boolean, required
          - `engagement` boolean, required
          - `activity` boolean, required
          - `content_richness` boolean, required
        - `component_coverage` object, required
          - `presence` 'complete' | 'partial' | 'unavailable', required
          - `audience` 'complete' | 'partial' | 'unavailable', required
          - `engagement` 'complete' | 'partial' | 'unavailable', required
          - `activity` 'complete' | 'partial' | 'unavailable', required
          - `content_richness` 'complete' | 'partial' | 'unavailable', required
        - `effective_weights` object, required
          - `presence` number, required
          - `audience` number, required
          - `engagement` number, required
          - `activity` number, required
          - `content_richness` number, required
        - `available_weight` number, required
        - `author` object, nullable, required
          - `id` string, required
          - `username` string, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_count` number, nullable, required
        - `signals` object, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_total` number, nullable, required
          - `sampled_posts` integer, nullable, required
          - `median_engagement_rate` number, nullable, required
          - `er_benchmark_ratio` number, nullable, required
          - `days_since_last_post` number, nullable, required
          - `avg_comments_per_post` number, nullable, required
          - `posts_per_week` number, nullable, required
          - `media_fraction` number, nullable, required
          - `avg_text_length` number, nullable, required
        - `evidence` object, required
          - `profile` object, required
            - `state` 'live' | 'stale' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
            - `not_found_reason` 'account_private' | 'account_gone' | 'handle_unresolved', nullable, required
          - `posts` object, required
            - `state` 'sampled' | 'observed_empty' | 'not_supported' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
        - `recommended_endpoints` string[], required
      - `instagram` object
        - `found` boolean, required
        - `score` integer, nullable, required
        - `score_status` 'complete' | 'partial' | 'insufficient_evidence', required
        - `score_components` object, required
          - `presence` number, nullable, required
          - `audience` number, nullable, required
          - `engagement` number, nullable, required
          - `activity` number, nullable, required
          - `content_richness` number, nullable, required
        - `component_availability` object, required
          - `presence` boolean, required
          - `audience` boolean, required
          - `engagement` boolean, required
          - `activity` boolean, required
          - `content_richness` boolean, required
        - `component_coverage` object, required
          - `presence` 'complete' | 'partial' | 'unavailable', required
          - `audience` 'complete' | 'partial' | 'unavailable', required
          - `engagement` 'complete' | 'partial' | 'unavailable', required
          - `activity` 'complete' | 'partial' | 'unavailable', required
          - `content_richness` 'complete' | 'partial' | 'unavailable', required
        - `effective_weights` object, required
          - `presence` number, required
          - `audience` number, required
          - `engagement` number, required
          - `activity` number, required
          - `content_richness` number, required
        - `available_weight` number, required
        - `author` object, nullable, required
          - `id` string, required
          - `username` string, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_count` number, nullable, required
        - `signals` object, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_total` number, nullable, required
          - `sampled_posts` integer, nullable, required
          - `median_engagement_rate` number, nullable, required
          - `er_benchmark_ratio` number, nullable, required
          - `days_since_last_post` number, nullable, required
          - `avg_comments_per_post` number, nullable, required
          - `posts_per_week` number, nullable, required
          - `media_fraction` number, nullable, required
          - `avg_text_length` number, nullable, required
        - `evidence` object, required
          - `profile` object, required
            - `state` 'live' | 'stale' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
            - `not_found_reason` 'account_private' | 'account_gone' | 'handle_unresolved', nullable, required
          - `posts` object, required
            - `state` 'sampled' | 'observed_empty' | 'not_supported' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
        - `recommended_endpoints` string[], required
      - `youtube` object
        - `found` boolean, required
        - `score` integer, nullable, required
        - `score_status` 'complete' | 'partial' | 'insufficient_evidence', required
        - `score_components` object, required
          - `presence` number, nullable, required
          - `audience` number, nullable, required
          - `engagement` number, nullable, required
          - `activity` number, nullable, required
          - `content_richness` number, nullable, required
        - `component_availability` object, required
          - `presence` boolean, required
          - `audience` boolean, required
          - `engagement` boolean, required
          - `activity` boolean, required
          - `content_richness` boolean, required
        - `component_coverage` object, required
          - `presence` 'complete' | 'partial' | 'unavailable', required
          - `audience` 'complete' | 'partial' | 'unavailable', required
          - `engagement` 'complete' | 'partial' | 'unavailable', required
          - `activity` 'complete' | 'partial' | 'unavailable', required
          - `content_richness` 'complete' | 'partial' | 'unavailable', required
        - `effective_weights` object, required
          - `presence` number, required
          - `audience` number, required
          - `engagement` number, required
          - `activity` number, required
          - `content_richness` number, required
        - `available_weight` number, required
        - `author` object, nullable, required
          - `id` string, required
          - `username` string, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_count` number, nullable, required
        - `signals` object, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_total` number, nullable, required
          - `sampled_posts` integer, nullable, required
          - `median_engagement_rate` number, nullable, required
          - `er_benchmark_ratio` number, nullable, required
          - `days_since_last_post` number, nullable, required
          - `avg_comments_per_post` number, nullable, required
          - `posts_per_week` number, nullable, required
          - `media_fraction` number, nullable, required
          - `avg_text_length` number, nullable, required
        - `evidence` object, required
          - `profile` object, required
            - `state` 'live' | 'stale' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
            - `not_found_reason` 'account_private' | 'account_gone' | 'handle_unresolved', nullable, required
          - `posts` object, required
            - `state` 'sampled' | 'observed_empty' | 'not_supported' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
        - `recommended_endpoints` string[], required
      - `twitter` object
        - `found` boolean, required
        - `score` integer, nullable, required
        - `score_status` 'complete' | 'partial' | 'insufficient_evidence', required
        - `score_components` object, required
          - `presence` number, nullable, required
          - `audience` number, nullable, required
          - `engagement` number, nullable, required
          - `activity` number, nullable, required
          - `content_richness` number, nullable, required
        - `component_availability` object, required
          - `presence` boolean, required
          - `audience` boolean, required
          - `engagement` boolean, required
          - `activity` boolean, required
          - `content_richness` boolean, required
        - `component_coverage` object, required
          - `presence` 'complete' | 'partial' | 'unavailable', required
          - `audience` 'complete' | 'partial' | 'unavailable', required
          - `engagement` 'complete' | 'partial' | 'unavailable', required
          - `activity` 'complete' | 'partial' | 'unavailable', required
          - `content_richness` 'complete' | 'partial' | 'unavailable', required
        - `effective_weights` object, required
          - `presence` number, required
          - `audience` number, required
          - `engagement` number, required
          - `activity` number, required
          - `content_richness` number, required
        - `available_weight` number, required
        - `author` object, nullable, required
          - `id` string, required
          - `username` string, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_count` number, nullable, required
        - `signals` object, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_total` number, nullable, required
          - `sampled_posts` integer, nullable, required
          - `median_engagement_rate` number, nullable, required
          - `er_benchmark_ratio` number, nullable, required
          - `days_since_last_post` number, nullable, required
          - `avg_comments_per_post` number, nullable, required
          - `posts_per_week` number, nullable, required
          - `media_fraction` number, nullable, required
          - `avg_text_length` number, nullable, required
        - `evidence` object, required
          - `profile` object, required
            - `state` 'live' | 'stale' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
            - `not_found_reason` 'account_private' | 'account_gone' | 'handle_unresolved', nullable, required
          - `posts` object, required
            - `state` 'sampled' | 'observed_empty' | 'not_supported' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
        - `recommended_endpoints` string[], required
      - `threads` object
        - `found` boolean, required
        - `score` integer, nullable, required
        - `score_status` 'complete' | 'partial' | 'insufficient_evidence', required
        - `score_components` object, required
          - `presence` number, nullable, required
          - `audience` number, nullable, required
          - `engagement` number, nullable, required
          - `activity` number, nullable, required
          - `content_richness` number, nullable, required
        - `component_availability` object, required
          - `presence` boolean, required
          - `audience` boolean, required
          - `engagement` boolean, required
          - `activity` boolean, required
          - `content_richness` boolean, required
        - `component_coverage` object, required
          - `presence` 'complete' | 'partial' | 'unavailable', required
          - `audience` 'complete' | 'partial' | 'unavailable', required
          - `engagement` 'complete' | 'partial' | 'unavailable', required
          - `activity` 'complete' | 'partial' | 'unavailable', required
          - `content_richness` 'complete' | 'partial' | 'unavailable', required
        - `effective_weights` object, required
          - `presence` number, required
          - `audience` number, required
          - `engagement` number, required
          - `activity` number, required
          - `content_richness` number, required
        - `available_weight` number, required
        - `author` object, nullable, required
          - `id` string, required
          - `username` string, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_count` number, nullable, required
        - `signals` object, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_total` number, nullable, required
          - `sampled_posts` integer, nullable, required
          - `median_engagement_rate` number, nullable, required
          - `er_benchmark_ratio` number, nullable, required
          - `days_since_last_post` number, nullable, required
          - `avg_comments_per_post` number, nullable, required
          - `posts_per_week` number, nullable, required
          - `media_fraction` number, nullable, required
          - `avg_text_length` number, nullable, required
        - `evidence` object, required
          - `profile` object, required
            - `state` 'live' | 'stale' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
            - `not_found_reason` 'account_private' | 'account_gone' | 'handle_unresolved', nullable, required
          - `posts` object, required
            - `state` 'sampled' | 'observed_empty' | 'not_supported' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
        - `recommended_endpoints` string[], required
      - `bluesky` object
        - `found` boolean, required
        - `score` integer, nullable, required
        - `score_status` 'complete' | 'partial' | 'insufficient_evidence', required
        - `score_components` object, required
          - `presence` number, nullable, required
          - `audience` number, nullable, required
          - `engagement` number, nullable, required
          - `activity` number, nullable, required
          - `content_richness` number, nullable, required
        - `component_availability` object, required
          - `presence` boolean, required
          - `audience` boolean, required
          - `engagement` boolean, required
          - `activity` boolean, required
          - `content_richness` boolean, required
        - `component_coverage` object, required
          - `presence` 'complete' | 'partial' | 'unavailable', required
          - `audience` 'complete' | 'partial' | 'unavailable', required
          - `engagement` 'complete' | 'partial' | 'unavailable', required
          - `activity` 'complete' | 'partial' | 'unavailable', required
          - `content_richness` 'complete' | 'partial' | 'unavailable', required
        - `effective_weights` object, required
          - `presence` number, required
          - `audience` number, required
          - `engagement` number, required
          - `activity` number, required
          - `content_richness` number, required
        - `available_weight` number, required
        - `author` object, nullable, required
          - `id` string, required
          - `username` string, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_count` number, nullable, required
        - `signals` object, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_total` number, nullable, required
          - `sampled_posts` integer, nullable, required
          - `median_engagement_rate` number, nullable, required
          - `er_benchmark_ratio` number, nullable, required
          - `days_since_last_post` number, nullable, required
          - `avg_comments_per_post` number, nullable, required
          - `posts_per_week` number, nullable, required
          - `media_fraction` number, nullable, required
          - `avg_text_length` number, nullable, required
        - `evidence` object, required
          - `profile` object, required
            - `state` 'live' | 'stale' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
            - `not_found_reason` 'account_private' | 'account_gone' | 'handle_unresolved', nullable, required
          - `posts` object, required
            - `state` 'sampled' | 'observed_empty' | 'not_supported' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
        - `recommended_endpoints` string[], required
      - `truthsocial` object
        - `found` boolean, required
        - `score` integer, nullable, required
        - `score_status` 'complete' | 'partial' | 'insufficient_evidence', required
        - `score_components` object, required
          - `presence` number, nullable, required
          - `audience` number, nullable, required
          - `engagement` number, nullable, required
          - `activity` number, nullable, required
          - `content_richness` number, nullable, required
        - `component_availability` object, required
          - `presence` boolean, required
          - `audience` boolean, required
          - `engagement` boolean, required
          - `activity` boolean, required
          - `content_richness` boolean, required
        - `component_coverage` object, required
          - `presence` 'complete' | 'partial' | 'unavailable', required
          - `audience` 'complete' | 'partial' | 'unavailable', required
          - `engagement` 'complete' | 'partial' | 'unavailable', required
          - `activity` 'complete' | 'partial' | 'unavailable', required
          - `content_richness` 'complete' | 'partial' | 'unavailable', required
        - `effective_weights` object, required
          - `presence` number, required
          - `audience` number, required
          - `engagement` number, required
          - `activity` number, required
          - `content_richness` number, required
        - `available_weight` number, required
        - `author` object, nullable, required
          - `id` string, required
          - `username` string, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_count` number, nullable, required
        - `signals` object, nullable, required
          - `followers` number, nullable, required
          - `verified` boolean, nullable, required
          - `posts_total` number, nullable, required
          - `sampled_posts` integer, nullable, required
          - `median_engagement_rate` number, nullable, required
          - `er_benchmark_ratio` number, nullable, required
          - `days_since_last_post` number, nullable, required
          - `avg_comments_per_post` number, nullable, required
          - `posts_per_week` number, nullable, required
          - `media_fraction` number, nullable, required
          - `avg_text_length` number, nullable, required
        - `evidence` object, required
          - `profile` object, required
            - `state` 'live' | 'stale' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
            - `not_found_reason` 'account_private' | 'account_gone' | 'handle_unresolved', nullable, required
          - `posts` object, required
            - `state` 'sampled' | 'observed_empty' | 'not_supported' | 'not_found' | 'unavailable', required
            - `captured_at` string, date-time, nullable, required
            - `stale_age_seconds` number, nullable, required
            - `failure_reason` 'timeout' | 'upstream_error' | 'invalid_response', nullable, required
        - `recommended_endpoints` string[], required
    - `surface` object, required
      - `posts_estimate` object, required
        - `tiktok` number, nullable
        - `instagram` number, nullable
        - `youtube` number, nullable
        - `twitter` number, nullable
        - `threads` number, nullable
        - `bluesky` number, nullable
        - `truthsocial` number, nullable
        - `total` number, required
      - `comments_estimate` object, required
        - `tiktok` number, nullable
        - `instagram` number, nullable
        - `youtube` number, nullable
        - `twitter` number, nullable
        - `threads` number, nullable
        - `bluesky` number, nullable
        - `truthsocial` number, nullable
        - `total` number, required
      - `estimate_basis` string, required
      - `pull_cost_estimate_credits` object, required
        - `posts_only` number, required
        - `posts_and_comments` number, required
    - `disclaimer` string, required
    - `legs` object[], required
      - `endpoint` string, required
      - `status` integer, required
      - `credits_used` number, required
      - `latency_ms` number, required
      - `error` string, nullable, required
    - `domain_relevance` object, nullable
      - `topic` string, required
      - `score` integer, required
      - `share` number, required
      - `weight` number, required
      - `sampled_posts` integer, required
      - `relevant_posts` integer, required
      - `unjudged_posts` integer, required
      - `too_short_posts` integer, required
      - `judged_posts` object[], required
        - `platform` 'tiktok' | 'instagram' | 'youtube' | 'twitter' | 'threads' | 'bluesky' | 'truthsocial', required
        - `id` string, required
        - `relevant` boolean, required
      - `by_platform` object, required
        - `tiktok` object
          - `sampled_posts` integer, required
          - `relevant_posts` integer, required
          - `share` number, required
        - `instagram` object
          - `sampled_posts` integer, required
          - `relevant_posts` integer, required
          - `share` number, required
        - `youtube` object
          - `sampled_posts` integer, required
          - `relevant_posts` integer, required
          - `share` number, required
        - `twitter` object
          - `sampled_posts` integer, required
          - `relevant_posts` integer, required
          - `share` number, required
        - `threads` object
          - `sampled_posts` integer, required
          - `relevant_posts` integer, required
          - `share` number, required
        - `bluesky` object
          - `sampled_posts` integer, required
          - `relevant_posts` integer, required
          - `share` number, required
        - `truthsocial` object
          - `sampled_posts` integer, required
          - `relevant_posts` integer, required
          - `share` number, required
      - `methodology_version` string, required
      - `relevance_methodology_version` string, required
    - `score_with_domain_relevance` integer, nullable
    - `verdict_with_domain_relevance` 'pull' | 'pull_partial' | 'skip' | 'not_found' | 'insufficient_evidence', nullable
    - `_warnings` string[]
  - `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)