Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: SocialCrawl Prism API
version: 1.0.0
description: 'Unified social media data API - one API key, one consistent response format, 50 platforms, 400 endpoints. Power AI agents with clean social data.
Slim variant: inline examples removed and the shared error responses hoisted into components. The full annotated spec is at https://www.socialcrawl.dev/openapi.json.'
contact:
name: SocialCrawl
url: https://www.socialcrawl.dev
email: support@socialcrawl.dev
servers:
- url: https://www.socialcrawl.dev/v1
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Prism
description: Prism endpoints
paths:
/prism/lookup:
get:
summary: 'Universal URL dispatcher: any social/commerce URL → the right detail endpoint''s…'
description: Sniffs the platform + endpoint from a URL and returns that endpoint's unified data, with no surcharge. You pay the resolved endpoint's own cost. The join key the whole API runs on is `url`. Supports TikTok, Instagram, YouTube, X/Twitter, Facebook, LinkedIn, Bluesky, Pinterest, Reddit, Threads, Rumble, Truth Social, GitHub, Amazon, and Spotify links. The `resolved` block names the platform, endpoint, and archetype of the response so agents know the shape that follows; `legs[]` reports the dispatched call's status, cost, and latency.
tags:
- Prism
operationId: get_prism_lookup
security:
- ApiKeyAuth: []
x-credit-tier: standard
x-credit-cost: 0
parameters:
- name: url
in: query
required: true
description: Absolute http(s) URL of the post / profile / product to resolve.
schema:
type: string
- name: include
in: query
required: false
description: CSV of optional flags to forward verbatim to the resolved endpoint (e.g. `trim`). Each member must be an optional param of that endpoint.
schema:
type: string
- name: Cache-Control
in: header
required: false
description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
schema:
type: string
responses:
'200':
description: Successful response
headers:
X-Credits-Used:
description: Net credits charged for this response. Idempotency replays report 0.
schema:
type: integer
minimum: 0
X-Credits-Remaining:
description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
schema:
type: integer
minimum: 0
X-Idempotent-Replay:
description: Present with value `true` only when this response replays a settled idempotency record.
schema:
type: string
enum:
- 'true'
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the request succeeded
platform:
type: string
description: Platform name
endpoint:
type: string
description: API endpoint path
data:
type: object
description: Platform-specific response data
properties:
metrics:
type: object
description: Key performance metrics
properties:
total_views:
type: integer
description: Total view count
total_likes:
type: integer
description: Total like count
total_comments:
type: integer
description: Total comment count
engagement_rate:
type: number
description: Computed engagement rate (0-1)
period:
type:
- string
- 'null'
description: Time period for the analytics data
breakdown:
type:
- array
- 'null'
description: Per-item or per-period breakdown
items:
type: object
description: Breakdown entry
_warnings:
type: array
description: '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''.'
items:
type: string
description: One advisory notice.
credits_used:
type: integer
description: Number of credits consumed
credits_remaining:
type:
- integer
- 'null'
description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
request_id:
type: string
description: Unique request identifier for support
cached:
type: boolean
description: Whether the response was served from cache
idempotent_replay:
type: boolean
description: True only when this response is an idempotency replay
required:
- success
- platform
- endpoint
- data
- credits_used
- credits_remaining
- request_id
- cached
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'402':
$ref: '#/components/responses/Error402'
'404':
$ref: '#/components/responses/Error404'
'405':
$ref: '#/components/responses/Error405'
'409':
$ref: '#/components/responses/Error409'
'413':
$ref: '#/components/responses/Error413'
'422':
$ref: '#/components/responses/Error422'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'502':
$ref: '#/components/responses/Error502'
'503':
$ref: '#/components/responses/Error503'
/prism/comments:
get:
summary: Every comment on a post, replies nested, server-paginated to completion
description: 'Give it any TikTok, YouTube, Facebook, Reddit, Hacker News, or Instagram post URL and it harvests every top-level comment (paginated to the end) with replies nested where the platform supports it (TikTok, YouTube, Facebook). Reddit and Hacker News return their whole nested thread; Instagram is top-level only. Pass `sort=top` to get the most-liked comments first (ranked by `engagement.likes`): ideal for pulling the top comments on a high-volume post; pair it with `limit` to cap how many you get back (e.g. `sort=top&max=500&limit=200` scans ~500 and returns the top 200). YouTube sorts upstream so its top set is exact; other platforms are sorted across the scanned set. Metered at 1 credit per internal page call (minimum 2): `sort`/`limit` never change the price, which always follows pages scanned (`max`). Instagram is the exception: an Instagram post URL is a flat 5 credits per call whatever `max` and `replies` you pass, because that source returns the comment set in one mobile-upstream call rather than by page. Returns sync JSON, or a typed SSE stream when you send `Accept: text/event-stream`: a `page` chunk lands as each page settles. The `next_cursor` is one opaque token that resumes every leg; `legs[]` reports each page''s status, cost, and latency.'
tags:
- Prism
operationId: get_prism_comments
security:
- ApiKeyAuth: []
x-credit-tier: standard
x-credit-cost: 1
x-credit-cost-formula: 1 credit per comment page scanned, except on Instagram, where a post URL is a flat 5 credits whatever `max` and `replies` you pass
parameters:
- name: url
in: query
required: true
description: Absolute http(s) URL of the post whose comments to harvest.
schema:
type: string
- name: max
in: query
required: false
description: Stop after roughly this many top-level comments (1-5000, default 1000). Whole pages are returned, so the actual count can slightly exceed this. Drives billing and, for `sort=top`, the depth of the ranking scan.
schema:
type: integer
- name: replies
in: query
required: false
description: Expand replies for comments that have them, where the platform supports it (default true; TikTok/YouTube/Facebook only). Pair with `replies=false` when you only want the top comments.
schema:
type: boolean
- name: cursor
in: query
required: false
description: Opaque composite cursor from a prior response's `next_cursor` to resume harvesting.
schema:
type: string
- name: sort
in: query
required: false
description: '`recent` (default: natural order) or `top` (most-liked first, ranked by each comment''s like count). With `top`, the response adds `sorted_by: "likes_desc"`. On Instagram, `top` returns the platform''s own ranked head (`sorted_by: "popular"`) rather than a re-sort, and that head is finite: use the default `recent` to harvest a whole Instagram thread.'
schema:
type: string
enum:
- top
- recent
- name: limit
in: query
required: false
description: Cap on how many top-level comments to return after sorting/scanning (1-5000, defaults to `max`). Truncates only the returned set, never what was scanned or billed. The response reports `returned`.
schema:
type: integer
- name: Cache-Control
in: header
required: false
description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
schema:
type: string
responses:
'200':
description: Successful response
headers:
X-Credits-Used:
description: Net credits charged for this response. Idempotency replays report 0.
schema:
type: integer
minimum: 0
X-Credits-Remaining:
description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
schema:
type: integer
minimum: 0
X-Idempotent-Replay:
description: Present with value `true` only when this response replays a settled idempotency record.
schema:
type: string
enum:
- 'true'
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the request succeeded
platform:
type: string
description: Platform name
endpoint:
type: string
description: API endpoint path
data:
type: object
description: Platform-specific response data
properties:
metrics:
type: object
description: Key performance metrics
properties:
total_views:
type: integer
description: Total view count
total_likes:
type: integer
description: Total like count
total_comments:
type: integer
description: Total comment count
engagement_rate:
type: number
description: Computed engagement rate (0-1)
period:
type:
- string
- 'null'
description: Time period for the analytics data
breakdown:
type:
- array
- 'null'
description: Per-item or per-period breakdown
items:
type: object
description: Breakdown entry
_warnings:
type: array
description: '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''.'
items:
type: string
description: One advisory notice.
credits_used:
type: integer
description: Number of credits consumed
credits_remaining:
type:
- integer
- 'null'
description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
request_id:
type: string
description: Unique request identifier for support
cached:
type: boolean
description: Whether the response was served from cache
idempotent_replay:
type: boolean
description: True only when this response is an idempotency replay
required:
- success
- platform
- endpoint
- data
- credits_used
- credits_remaining
- request_id
- cached
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'402':
$ref: '#/components/responses/Error402'
'404':
$ref: '#/components/responses/Error404'
'405':
$ref: '#/components/responses/Error405'
'409':
$ref: '#/components/responses/Error409'
'413':
$ref: '#/components/responses/Error413'
'422':
$ref: '#/components/responses/Error422'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'502':
$ref: '#/components/responses/Error502'
'503':
$ref: '#/components/responses/Error503'
/tiktok/profile/full:
get:
summary: TikTok profile, recent posts, and computed analytics in one call
description: 'Fans out to the TikTok profile and recent-posts endpoints in parallel and returns the unified author, the recent-post list, and computed metrics: average engagement rate, posting cadence (with the window it was measured over), the top post, and the format mix. The profile leg is the only critical leg: if posts can''t be fetched the call still returns the profile with post-dependent metrics null, and every leg''s status is surfaced in legs[]. Flat 5 credits.'
tags:
- Prism
operationId: get_tiktok_profile_full
security:
- ApiKeyAuth: []
x-credit-tier: standard
x-credit-cost: 5
parameters:
- name: handle
in: query
required: false
description: handle
schema:
type: string
- name: user_id
in: query
required: false
description: user_id
schema:
type: string
- name: posts
in: query
required: false
description: How many recent posts to fetch + average the computed metrics over (1-100, default 25).
schema:
type: integer
- name: cursor
in: query
required: false
description: Pass a prior response's posts_cursor to deepen the post window.
schema:
type: string
- name: include
in: query
required: false
description: CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload.
schema:
type: string
- name: Cache-Control
in: header
required: false
description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
schema:
type: string
responses:
'200':
description: Successful response
headers:
X-Credits-Used:
description: Net credits charged for this response. Idempotency replays report 0.
schema:
type: integer
minimum: 0
X-Credits-Remaining:
description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
schema:
type: integer
minimum: 0
X-Idempotent-Replay:
description: Present with value `true` only when this response replays a settled idempotency record.
schema:
type: string
enum:
- 'true'
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the request succeeded
platform:
type: string
description: Platform name
endpoint:
type: string
description: API endpoint path
data:
type: object
description: Platform-specific response data
properties:
metrics:
type: object
description: Key performance metrics
properties:
total_views:
type: integer
description: Total view count
total_likes:
type: integer
description: Total like count
total_comments:
type: integer
description: Total comment count
engagement_rate:
type: number
description: Computed engagement rate (0-1)
period:
type:
- string
- 'null'
description: Time period for the analytics data
breakdown:
type:
- array
- 'null'
description: Per-item or per-period breakdown
items:
type: object
description: Breakdown entry
_warnings:
type: array
description: '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''.'
items:
type: string
description: One advisory notice.
credits_used:
type: integer
description: Number of credits consumed
credits_remaining:
type:
- integer
- 'null'
description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
request_id:
type: string
description: Unique request identifier for support
cached:
type: boolean
description: Whether the response was served from cache
idempotent_replay:
type: boolean
description: True only when this response is an idempotency replay
required:
- success
- platform
- endpoint
- data
- credits_used
- credits_remaining
- request_id
- cached
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'402':
$ref: '#/components/responses/Error402'
'404':
$ref: '#/components/responses/Error404'
'405':
$ref: '#/components/responses/Error405'
'409':
$ref: '#/components/responses/Error409'
'413':
$ref: '#/components/responses/Error413'
'422':
$ref: '#/components/responses/Error422'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'502':
$ref: '#/components/responses/Error502'
'503':
$ref: '#/components/responses/Error503'
/instagram/profile/full:
get:
summary: Instagram profile, recent posts, and computed analytics in one call
description: 'Fans out to the Instagram profile and recent-posts endpoints in parallel and returns the unified author, the recent-post list, and computed metrics: average engagement rate, posting cadence (with the window it was measured over), the top post, and the format mix. The profile leg is the only critical leg: if posts can''t be fetched the call still returns the profile with post-dependent metrics null, and every leg''s status is surfaced in legs[]. Flat 5 credits.'
tags:
- Prism
operationId: get_instagram_profile_full
security:
- ApiKeyAuth: []
x-credit-tier: standard
x-credit-cost: 5
parameters:
- name: handle
in: query
required: false
description: handle
schema:
type: string
- name: posts
in: query
required: false
description: How many recent posts to fetch + average the computed metrics over (1-100, default 25).
schema:
type: integer
- name: cursor
in: query
required: false
description: Pass a prior response's posts_cursor to deepen the post window.
schema:
type: string
- name: include
in: query
required: false
description: CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload.
schema:
type: string
- name: Cache-Control
in: header
required: false
description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
schema:
type: string
responses:
'200':
description: Successful response
headers:
X-Credits-Used:
description: Net credits charged for this response. Idempotency replays report 0.
schema:
type: integer
minimum: 0
X-Credits-Remaining:
description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
schema:
type: integer
minimum: 0
X-Idempotent-Replay:
description: Present with value `true` only when this response replays a settled idempotency record.
schema:
type: string
enum:
- 'true'
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the request succeeded
platform:
type: string
description: Platform name
endpoint:
type: string
description: API endpoint path
data:
type: object
description: Platform-specific response data
properties:
metrics:
type: object
description: Key performance metrics
properties:
total_views:
type: integer
description: Total view count
total_likes:
type: integer
description: Total like count
total_comments:
type: integer
description: Total comment count
engagement_rate:
type: number
description: Computed engagement rate (0-1)
period:
type:
- string
- 'null'
description: Time period for the analytics data
breakdown:
type:
- array
- 'null'
description: Per-item or per-period breakdown
items:
type: object
description: Breakdown entry
_warnings:
type: array
description: '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''.'
items:
type: string
description: One advisory notice.
credits_used:
type: integer
description: Number of credits consumed
credits_remaining:
type:
- integer
- 'null'
description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
request_id:
type: string
description: Unique request identifier for support
cached:
type: boolean
description: Whether the response was served from cache
idempotent_replay:
type: boolean
description: True only when this response is an idempotency replay
required:
- success
- platform
- endpoint
- data
- credits_used
- credits_remaining
- request_id
- cached
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'402':
$ref: '#/components/responses/Error402'
'404':
$ref: '#/components/responses/Error404'
'405':
$ref: '#/components/responses/Error405'
'409':
$ref: '#/components/responses/Error409'
'413':
$ref: '#/components/responses/Error413'
'422':
$ref: '#/components/respon
# --- truncated at 32 KB (504 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-prism-api-openapi.yml