TypeScript

SocialTap is the social media scraper API for developers and AI agents. Send a public link, a handle or a search and get live data back in one schema. Failed requests are free.

The TypeScript SDK for the SocialTap API: a method for every endpoint, typed models and errors, retries and pagination. Generated from the SocialTap catalog (version 1.509.29). Docs: https://socialtap.dev/docs.

Install

npm install socialtap
npm pkg set type=module   # the examples are ES modules (or name your file .mjs or .mts)

Zero runtime dependencies (fetch); Node 20.3+, Deno, Bun and Cloudflare Workers (server-side: the API key is a secret). ESM only: in Node, your project needs "type": "module" in its package.json (the second command above) or a .mjs/.mts file, else Node stops at the first import ("Cannot use import statement outside a module"). Run TypeScript directly with Node 22.18+ (node app.ts) or npx tsx app.ts. Params and models use the API's snake_case names; SDK objects (options, credits, errors) are camelCase.

null means unknown. With fields, results are typed PartialModel<T> (every member may be absent). A 2xx that is not the API's envelope (no data, not JSON) throws APIDecodeError; a retry-after longer than MAX_RETRY_AFTER_S throws RetryAfterExceededError instead of retrying early. Results keep the API's objects as sent, members this version doesn't model included. Event is a union narrowed by type; a job item's params are typed by its endpoint.

Authenticate

The client reads your API key from SOCIALTAP_API_KEY, or takes it as an option. Requests send it in the x-api-key header. Get a key at https://socialtap.dev/signup/: every account starts with 100 free credits.

First call: Exact follower and like counts, bio and country

import { SocialTap } from "socialtap";

const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY

const res = await client.tiktok.profile.get({ handle: "nasa" });
console.log(res.data);
console.log(res.credits.charged, res.meta.request_id);

data is a Profile (example response, truncated):

{
  "approximate_fields": [],
  "avatar_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640\u0026refresh_token=29840d4e\u0026x-expires=4070908800\u0026x-signature=SCRUBBED\u0026t=4d5b0474\u0026ps=13740610\u0026shp=a5d48078\u0026shcp=81f88b70\u0026idc=useast5",
  "banner_url": null,
  "bio": "Making the seemingly impossible, possible.✨",
  "category": null,
  "country_code": "US",
  "created_at": "2026-07-20T15:55:49Z",
  "display_name": "NASA",
  "external_links": [
    {
      "title": null,
      "url": "https://science.nasa.gov/feature/artemis-ii-preliminary-lunar-science-report"
    }
  ],
  "id": "7664638705177150477",
  "is_private": false,
  "is_verified": true,
  "location": null,
  "metrics": {
    "follower_count": 2152843,
    "following_count": 23,
    "post_count": 62,
    "total_like_count": 11486661,
    "total_view_count": null
  },
  "platform": "tiktok",
  "platform_specific": {
    "tiktok": {
      "display_name_changed_at": "2026-07-20T15:58:00Z",
      "friend_count": 17,
      "is_business_account": false,
      "is_shop_seller": false,
      "language": "en",
      "liked_post_count": null,
      "sec_uid": "MS4wLjABAAAAU9BRVzC8oCaegVnia8IbqWhPb_-dbU7s00Y3wS1_Nx8g5RUaYvyXrpejgjdxTwd6"
    }
  },
  "type": "organization",
  "unknown_fields": [],
  "url": "https://www.tiktok.com/@nasa",
  "username": "nasa"
}

Every result also carries the envelope meta (request ID, source, cache status, fetch time) and credits (charged by this request, and the balance after it when the API reports it). Failed requests and cache hits are free.

Endpoints

Endpoints newer than this package

A version has a method for every endpoint the API had when it was released. For a newer one, update the package, or send the request yourself: the raw request adds your key and retries and raises errors like a method, and returns the status, headers and body (the envelope, data and meta). Each endpoint's docs page has its path and params.

const res = await client.request({ method: "GET", path: "/v1/tiktok/profile", query: { handle: "nasa" } });
console.log(res.status, res.body);

Errors

Every API error is an APIError subclass named after its code, with status, code, retryable, remediation, requestId and creditsCharged (0: errors are free). Codes this SDK version doesn't know arrive as a plain APIError with their code; no response at all is an APIConnectionError (APITimeoutError for timeouts).

import { APIError, NotFoundError } from "socialtap";

try {
  await client.tiktok.profile.get({ handle: "nasa" });
} catch (err) {
  if (err instanceof NotFoundError) {
    // Check the link or ID. Do not retry.
  } else if (err instanceof APIError) {
    console.error(err.code, err.status, err.retryable, err.remediation, err.requestId);
  } else throw err;
}

Retries and timeouts

Retryable failures (the codes above, connection errors, timeouts) are retried 2 times by default with exponential backoff and jitter, honoring retry-after. A GET retry sends max_age set to the seconds since the first attempt: if the first response was lost in transit, the retry is served free from the cache. Timeouts are per attempt: 60 s by default, and 300 s for endpoints that may transcribe audio (facebook.ad_transcript, facebook.transcript, instagram.transcript, kick.transcript, reddit.transcript, rumble.transcript, tiktok.transcript, twitch.transcript, youtube.transcript), because speech-to-text on long media takes minutes, and for create-and-wait's long-polls. Most requests answer in a few seconds. A timeout you set, on the client or on one request, applies to every endpoint, and so does maxRetries.

Pagination

List endpoints return one page (data, page.has_more, page.next_cursor). iterate() returns a Paginator (for await over items, .byPage() for pages) with two guards, maxPages and maxCredits; afterwards pagesFetched, creditsCharged, stopReason ("end", or the guard that stopped it) and endReason (the API's page.end_reason) say what happened. Each page is checked against its catalog price before it is fetched, and an empty page with has_more is not the end.

const items = client.amazon.dealProducts.iterate({}, { maxPages: 10, maxCredits: 100 });
for await (const item of items) {
  console.log(item);
}
console.log(items.pagesFetched, items.creditsCharged, items.stopReason, items.endReason);

Account, API keys, jobs, webhooks and events

The gateway's own routes (account, usage, credit ledger, API keys, jobs, webhook endpoints, events) are free and have methods too, named from their operation IDs (<noun>.<verb>, or <noun>.<sub>.<verb> for a sub-resource). They answer the same envelope (data, meta, credits) with their own meta; cursor-paged list routes have iterate like list endpoints. Every POST sends an idempotency-key header (yours, or a new UUID kept for the call's retries), so it is retried like a GET and a retry never repeats the work; replayed says when the API answered from an earlier request with the same key, and status is 202 when accepted work continues. Each route needs a key with the scope below (a key never gets a scope its creator lacks).

const res = await client.account.get();
console.log(res.data, res.meta.request_id);

Jobs and webhooks

Many requests (or one long list walk) run as a background job at the synchronous prices; failed items are free. The create-and-wait helper creates one, long-polls it until it ends and returns every result; one Idempotency-Key covers the create's retries, so a retry never runs a job twice. Webhook deliveries are signed per Standard Webhooks: verify the raw body with your endpoint's secret before trusting it, and deduplicate on the event ID.

const { job, results } = await client.jobs.createAndWait({ requests: [{ custom_id: "row-1", endpoint: "tiktok.profile", params: { handle: "nasa" } }] });
for (const r of results) console.log(r.custom_id, r.status, r.error?.code);

// A webhook delivery: the raw body, the request headers, your endpoint's secret.
const event = await client.webhooks.verify(rawBody, request.headers, process.env.SOCIALTAP_WEBHOOK_SECRET!);

Tools for AI agents

The SDK hands the SocialTap MCP server's tools to a model: each tool's name, description (its price and rules included) and input JSON Schema, and a call that sends one stateless MCP request with your key. A tool behaves exactly as it does for an MCP client: concise results (detail: "full" for every field), next_cursor to continue, and failures returned as the tool's output (error with retryable and remediation) so the model can act on them. Transport failures raise as for any request, and tools that may be repeated are retried.

// The Vercel AI SDK (ai is an optional peer dependency): the default tools (call_endpoint reaches every endpoint),
// or socialtapTools({ tools: [...] }) / socialtapTools({ tools: "all" }).
import { generateText, stepCountIs } from "ai";
import { socialtapTools } from "socialtap/ai";

// model: any AI SDK model; prompt: the task. The model calls the tools, the SDK runs them with your key.
const { text } = await generateText({ model, tools: socialtapTools(), stopWhen: stepCountIs(5), prompt });

// Any other tool-calling API: hand TOOLS (name, description, inputSchema) to the model, run its calls with callTool.
import { SocialTap, TOOLS, callTool } from "socialtap";

const r = await callTool(new SocialTap(), "find_endpoint", { query: "Exact follower and like counts, bio and country" });
console.log(r.isError, r.output);

CLI

The package's bin: every endpoint as a command (JSON on stdout; a list walk with --all prints one item per line), the agent tools, and init, which sets up coding agents.

npx socialtap tiktok profile --handle nasa
npx socialtap endpoints          # every command, its params and price
npx socialtap tool find_endpoint '{"query":"Exact follower and like counts, bio and country"}'
npx socialtap init               # Claude Code, Codex, Cursor, Gemini CLI: the Agent Skill + the MCP server

init installs the Agent Skill the site publishes (its discovery index, digest checked) into each agent's user skills directory and registers the MCP server with your key (--api-key, or SOCIALTAP_API_KEY) in each agent's own user config: Claude Code through claude mcp add-json, Codex's config.toml, Cursor's mcp.json, Gemini CLI's settings.json. It sets up every agent it finds (--agent <id> to choose) and is safe to run again.

Versioning

The version is derived from the API contract: major = API version, minor = the contract's revision (it grows with every additive change, a new endpoint included), patch = the SDK generator's revision. Questions and bug reports: support@socialtap.dev.