Docs menu

Docs

Quickstart

Make your first request in a minute: one API key, one HTTP call, one JSON shape for every platform.

1. Your API key

Every request is authenticated with an API key sent in the x-api-key header. Keys belong to an account and spend that account's credit balance.

Keep the key out of source control, for example in an environment variable:

Shell
export SOCIALTAP_API_KEY="your-api-key"

2. Make a request

Endpoints are plain HTTPS GET requests with query parameters. This calls the YouTube Transcript API with its documented example input:

cURL
curl -G 'https://staging.socialtap.dev/v1/youtube/transcript' \
  --data-urlencode 'url=https://www.youtube.com/watch?v=dQw4w9WgXcQ' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
JavaScript
const params = new URLSearchParams({
  url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
});
const res = await fetch(`https://staging.socialtap.dev/v1/youtube/transcript?${params}`, {
  headers: { "x-api-key": process.env.SOCIALTAP_API_KEY },
});
const { data, meta } = await res.json();
Python
import os
import requests

res = requests.get(
    "https://staging.socialtap.dev/v1/youtube/transcript",
    params={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
    headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]},
)
body = res.json()
data, meta = body["data"], body["meta"]

Response

A successful response is a JSON object with two keys: data, the item in its resource's shared schema, and meta, which describes how the request was served. List endpoints add a third key with what you need to fetch the next page.

200 OK
{
  "data": {
    "available_languages": [
      "en",
      "de-DE",
      "ja"
    ],
    "duration_ms": 213000,
    "id": "dQw4w9WgXcQ",
    "is_auto_generated": false,
    "language": "en",
    "platform": "youtube",
    "segments": [
      {
        "end_ms": 3040,
        "start_ms": 1360,
        "text": "[♪♪♪]"
      },
      {
        "end_ms": 21880,
        "start_ms": 18640,
        "text": "♪ We're no strangers to love ♪"
      },
      {
        "end_ms": 26960,
        "start_ms": 22640,
        "text": "♪ You know the rules and so do I ♪"
      }
    ],
    "source": "captions",
    "text": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules and so do I ♪ ♪ A full commitment's what I'm thinking of ♪ ♪ You wouldn't get this from any other guy ♪ ♪ I just wanna tell you how I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let …",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "meta": {
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
    "platform": "youtube",
    "source": "captions",
    "is_cached": false,
    "credits_charged": 1,
    "latency_ms": 511,
    "fetched_at": "2026-10-25T12:00:00Z"
  }
}

Long arrays and strings are shortened for display.

FieldTypeDescription
meta.request_idstringUnique request ID; include it when contacting support.
meta.platformstringPlatform ID of the endpoint (youtube, tiktok, …).
meta.sourcestringWhich upstream strategy produced the data.
meta.is_cachedbooleanTrue when served from the cache (free); see max_age.
meta.credits_chargedintegerCredits charged for this request (0 for errors and cache hits).
meta.latency_msintegerTime SocialTap spent on the request, in milliseconds.
meta.fetched_atstring (date-time)When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).

Errors

A failed request returns a non-2xx status and an error object with a stable code:

404 response
{
  "error": {
    "code": "not_found",
    "message": "The item does not exist or was deleted.",
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f"
  }
}

Branch on code, never on message. The error reference lists every code and whether it is safe to retry.

Next steps

All endpoints

Facebook

Instagram

TikTok

YouTube