StatusSupportGet API keyDashboard
OverviewIntroduction

Overview

Introduction

Use with AI

Every SocialTap endpoint takes the same API key and answers in one schema per kind of data. Each operation has its own page: parameters, the response field by field, prices, errors and a real example.

Base URL

Every endpoint is served over HTTPS from one base URL:

Base URL
https://socialtap.dev

Authentication

Send your API key in the x-api-key header with every request. Authentication

Header
x-api-key: <your key>

Endpoints

Data endpoints are GET requests with query parameters. Each returns {data, meta}, or {data, page, meta} for lists, where data follows one of 27 schemas, the same on every platform: ads, albums, comments, communities, downloads, effects, embeds, engagement stats, events, hashtags, livestreams, offers, places, playlists, podcasts, posts, products, profiles, reviews, sounds, suggestions, topics, transcripts, trends, usernames, web pages, web results.

Amazon

Apple Music

Bluesky

Facebook

Facebook Ad Library

Facebook Marketplace

Facebook Events

Google Ads Transparency Center

Instagram

Kick

Komi

Kwai

Lnk.Bio

LinkedIn

LinkedIn Ad Library

Linkme

Linktree

Pillar

Pinterest

Reddit

Rumble

Snapchat

SoundCloud

Spotify

Telegram

Threads

TikTok

TikTok Ad Library

TikTok Shop

Truth Social

Twitch

X

YouTube

Conventions

data follows the resource's shared schema; null means unknown, never 0 or "". Errors are non-2xx responses with this body: branch on error.code, never on the message (error codes).

Error body
{
  "error": {
    "code": "<code>",
    "message": "…",
    "request_id": "…",
    "status": "…",
    "retryable": "…",
    "param": "…",
    "remediation": "…",
    "doc_url": "…",
    "details": "…",
    "charged": "…"
  }
}

The meta object

request_idstring

Unique request ID; include it when contacting support.

platformstring

Platform ID of the endpoint (youtube, tiktok, …).

sourcestring

Which upstream strategy produced the data.

is_cachedboolean

True when served from the cache (free); see max_age.

credits_chargedinteger

Credits charged for this request (0 for errors and cache hits).

latency_msinteger

Time SocialTap spent on the request, in milliseconds.

fetched_atstring date-time

When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).

inputobjectnullable

What the request's url or handle resolved to: kind, platform ID and canonical URL, so you can confirm what was fetched; null for searches.

ShowHide 3 child fields
kindstring

What the input points to (profile, video, post, …). New values may be added; treat unknown values as other.

idstringnullable

Platform-native ID of the item; null when it is only known after the fetch and the request failed.

urlstringnullable

Canonical URL of the item; null when unknown.

credits_remainingintegernullable

Account balance after this request (the x-credits-remaining header); for a busy account an estimate that may not yet subtract concurrent requests (about a second of usage), never below the real balance; null when SocialTap could not read it.

client_request_idstringnullable

Your x-client-request-id, echoed; null when you sent none.

warningsobject[]

Things to act on that did not fail the request: a deprecated endpoint, partial data, items a list's walk leaves out. [] when none.

ShowHide 4 child fields
codestring

Machine-readable warning code (see the warnings list). New codes may be added.

messagestring

What to do about it.

doc_urlstring

Where to read more (the changelog entry, the endpoint's docs).

fieldsstring[]

partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.

List endpoints

Repeat the same request with cursor set to page.next_cursor while page.has_more is true (pagination guide).

limitintegermin 1

Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.

cursorstring

page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.

has_moreboolean

True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.

next_cursorstringnullable

Pass as cursor, with the same other parameters, to get the next page; null at the end.

next_cursor_expires_atstring date-timenullable

When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.

end_reasonstringnullable

Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.

One ofendplatform_limitmax_pages

Parameters every endpoint accepts

max_ageintegermin 0

Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.

fieldsstring

Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.

Request headers

HeaderTypeDescription
x-api-keystringYour API key.
authorizationstringBearer <your API key>: the same key as x-api-key, in the form most HTTP and MCP clients send (x-api-key wins when both are sent).
x-account-idstringDashboard session only: the account (acct_…) to act on, one of Session.accounts (default: the person's own); one they aren't on is refused (forbidden, reason not_a_member). API keys ignore it.
x-client-request-idstringYour own ID for the request (1–128 printable ASCII characters): echoed back and logged with ours, so support can find a request whose response never reached you.
traceparentstringW3C Trace Context of your trace: recorded with the request (its trace ID) so a trace can be matched to ours; SocialTap starts its own trace.
idempotency-keystringOn any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.
preferstringRFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.
cache-controlstringmax-age=N accepts a cached response up to N seconds old, like the max_age parameter (max_age wins when both are sent). Other directives are ignored.

Response headers

HeaderTypeDescription
x-request-idstringUnique request ID; include it when contacting support.
x-credits-chargedintCredits charged for this request (0 for errors and cache hits).
x-credits-remainingintAccount balance after this request; for a busy account an estimate that may not yet subtract concurrent requests (about a second of usage), never below the real balance.
retry-afterintSeconds to wait before retrying; sent only with the codes whose retry_after is set in the error codes list (never on credit errors).
allowstringMethods the endpoint accepts (method_not_allowed only).
ageintSeconds since the data was fetched (cache hits only).
x-client-request-idstringYour x-client-request-id, echoed (also meta.client_request_id).
ratelimit-policystringThe account's runaway-protection ceiling as an IETF RateLimit-Policy field, as enforced: a token bucket of q requests (twice the ceiling in requests per second, at least 10) that refills in w seconds: "account";q=<requests>;w=<seconds>. Not a plan limit.
ratelimitstringWhat is left of the ceiling (IETF RateLimit field): "account";r=<requests that may be sent at once now>;t=<seconds until the bucket is full again>.
deprecationstringRFC 9745: the endpoint is deprecated, as of this date (@<unix seconds>; may be in the future). Also in meta.warnings.
sunsetstringRFC 8594: when a deprecated endpoint stops answering (HTTP-date); from then on it answers endpoint_retired.
linkstringRFC 8288 links: rel="next" is the next page of a list (while page.has_more), the same request with cursor set; rel="deprecation" is a deprecated endpoint's notice.
locationstringOn 202 answers: the job's URL (GET it, free, for its status).
preference-appliedstringRFC 7240: respond-async when Prefer: respond-async turned the request into a job (202).
idempotent-replayedbooltrue when the answer replays an earlier request with the same Idempotency-Key (it shows the resource's current state).

Account, billing, jobs and webhooks

The operations SocialTap serves itself. Their JSON answers are {data, meta} (plus page on cursor-paged lists); every one is free unless it says otherwise.

Status

Account

Team

Signup

API keys

Billing

Events

Jobs

Notifications

Requests

Docs

Webhooks

Their meta

meta
ShowHide 5 child fields
client_request_idstringnullable

Your x-client-request-id, echoed; null when you sent none.

credits_chargedinteger

Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).

credits_remainingintegernullable

Account balance; null without an account (signup) or when SocialTap could not read it.

request_idstring

Unique request ID; include it when contacting support.

warningsobject[]

Things to act on that did not fail the request. [] when none.

ShowHide 4 child fields
codestring

Machine-readable warning code (see the warnings list). New codes may be added.

doc_urlstring

Where to read more (the changelog entry, the endpoint's docs).

fields?string[]

partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.

messagestring

What to do about it.

Last updated