# Quickstart Get started Make your first request in a minute: one API key, one HTTP call, one JSON shape for every platform. 1. ## Get an API key Every request is authenticated with an API key in the `x-api-key` header. To try SocialTap right now, use this public test key: Public test key[Get your own key and 100 free credits →](https://staging-fly.socialtap.dev/signup/) `st_test_docs_mZkmkl5JiSWvVgL4v3DLolbtSsjxXm11` It works right now, with no signup: every endpoint answers from [recorded responses](https://staging-fly.socialtap.dev/docs/test-mode/index.md), free. It can't reach an account or spend credits. For live data, use your own key. Keep keys out of source control, for example in an environment variable: Shell: ```shell export SOCIALTAP_API_KEY="st_test_docs_mZkmkl5JiSWvVgL4v3DLolbtSsjxXm11" ``` 2. ## Make a request Endpoints are plain HTTPS `GET` requests with query parameters. This calls the [TikTok Profile API](https://staging-fly.socialtap.dev/docs/reference/tiktok/profile/index.md) with its documented example input: cURL: ```shell curl -G 'https://staging-fly.socialtap.dev/v1/tiktok/profile' \ --data-urlencode 'handle=https://www.tiktok.com/@nasa' \ -H "x-api-key: $SOCIALTAP_API_KEY" ``` Node.js: ```javascript const params = new URLSearchParams({ handle: "https://www.tiktok.com/@nasa", }); const res = await fetch(`https://staging-fly.socialtap.dev/v1/tiktok/profile?${params}`, { headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" }, }); const body = await res.json(); if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`); const { data, meta } = body; console.log(data, meta.credits_charged); ``` Python: ```python import os import requests res = requests.get( "https://staging-fly.socialtap.dev/v1/tiktok/profile", params={"handle": "https://www.tiktok.com/@nasa"}, headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]}, ) body = res.json() if not res.ok: raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}") data, meta = body["data"], body["meta"] print(data, meta["credits_charged"]) ``` Go: ```go package main import ( "encoding/json" "fmt" "log" "net/http" "net/url" "os" ) func main() { q := url.Values{} q.Set("handle", "https://www.tiktok.com/@nasa") req, err := http.NewRequest("GET", "https://staging-fly.socialtap.dev/v1/tiktok/profile?"+q.Encode(), nil) if err != nil { log.Fatal(err) } req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var body struct { Data json.RawMessage `json:"data"` Meta map[string]any `json:"meta"` Error *struct { Code string `json:"code"` Message string `json:"message"` } `json:"error"` } if err := json.NewDecoder(res.Body).Decode(&body); err != nil { log.Fatal(err) } if body.Error != nil { log.Fatalf("%s: %s", body.Error.Code, body.Error.Message) } fmt.Println(string(body.Data), body.Meta["credits_charged"]) } ``` 3. ## Read the response A successful response is a JSON object with two keys: `data`, the item in its resource's [shared schema](https://staging-fly.socialtap.dev/resources/index.md), and `meta`, which describes how the request was served. [List endpoints](https://staging-fly.socialtap.dev/docs/pagination/index.md) add a third key with what you need to fetch the next page. 200 OK: ```json { "data": { "approximate_fields": [], "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=9341391e&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5", "banner_url": null, "bio": "Making the seemingly impossible, possible.✨", "category": null, "country_code": null, "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": 2140425, "following_count": 23, "post_count": 60, "total_like_count": 11385816, "total_view_count": null }, "platform": "tiktok", "platform_specific": {}, "type": "organization", "unknown_fields": [], "url": "https://www.tiktok.com/@nasa", "username": "nasa" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "tiktok", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "7664638705177150477", "url": "https://www.tiktok.com/@nasa" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [], "mode": "live" } } ``` | Field | Type | Description | | --- | --- | --- | | `meta.request_id` | `string` | Unique request ID; include it when contacting support. | | `meta.platform` | `string` | Platform ID of the endpoint (youtube, tiktok, …). | | `meta.source` | `string` | Which upstream strategy produced the data. | | `meta.is_cached` | `boolean` | True when served from the cache (free); see max_age. | | `meta.credits_charged` | `integer` | Credits charged for this request (0 for errors and cache hits). | | `meta.latency_ms` | `integer` | Time SocialTap spent on the request, in milliseconds. | | `meta.fetched_at` | `string` (date-time) | When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits). | | `meta.input` | `object` or `null` | 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. | | `meta.input.kind` | `string` | What the input points to (profile, video, post, …). New values may be added; treat unknown values as other. | | `meta.input.id` | `string` or `null` | Platform-native ID of the item; null when it is only known after the fetch and the request failed. | | `meta.input.url` | `string` or `null` | Canonical URL of the item; null when unknown. | | `meta.credits_remaining` | `integer` or `null` | 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. | | `meta.client_request_id` | `string` or `null` | Your x-client-request-id, echoed; null when you sent none. | | `meta.warnings` | `object[]` | Things to act on that did not fail the request: a deprecated endpoint, partial data. \[\] when none. | | `meta.warnings[].code` | `string` | Machine-readable warning code (see the warnings list). New codes may be added. | | `meta.warnings[].message` | `string` | What to do about it. | | `meta.warnings[].doc_url` | `string` | Where to read more (the changelog entry, the endpoint's docs). | | `meta.warnings[].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. | | `meta.mode` | `string` or `null` | live, or test for a test key's answer: a recorded response (fixture), free and deterministic; null when SocialTap could not tell. New values may be added.
One of `live`, `test` | > [!TIP] > > Test keys are free and deterministic, so build and test your whole integration with one. Switch to a live key (`st_live_…`) when you want live data: only successful requests are charged. ## Errors A failed request returns a non-2xx status and an `error` object with a stable `code`: 400 response: ```json { "error": { "code": "invalid_input", "message": "unknown parameter \"username\"; did you mean \"handle\"? This endpoint accepts: handle, max_age, fields.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 400, "retryable": false, "param": "username", "remediation": "Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.", "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#invalid_input", "details": { "accepted_params": [ "handle", "max_age", "fields" ], "suggestion": "handle" }, "charged": false } } ``` Branch on `code`, never on `message`. The [error reference](https://staging-fly.socialtap.dev/docs/errors/index.md) lists every code and whether it is safe to retry. ## Next steps - [Authentication](https://staging-fly.socialtap.dev/docs/authentication/index.md): The headers you send and receive, keys, scopes and rate limits. - [Credits and caching](https://staging-fly.socialtap.dev/docs/credits/index.md): How requests are priced, and how to get free cache hits. - [API reference](https://staging-fly.socialtap.dev/docs/reference/index.md): Every endpoint, its parameters, response fields, errors and prices. - [Build with AI agents](https://staging-fly.socialtap.dev/docs/agents/index.md): A prompt for your coding agent, the MCP server, the Agent Skill and Markdown docs. ## All endpoints ### [Facebook](https://staging-fly.socialtap.dev/apis/facebook/index.md) - [Facebook Post API](https://staging-fly.socialtap.dev/docs/reference/facebook/post/index.md) `GET /v1/facebook/post` - [Facebook Ad Library Search API](https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md) `GET /v1/facebook/search_ads` - [Facebook Video Transcript API](https://staging-fly.socialtap.dev/docs/reference/facebook/transcript/index.md) `GET /v1/facebook/transcript` ### [Instagram](https://staging-fly.socialtap.dev/apis/instagram/index.md) - [Instagram Post API](https://staging-fly.socialtap.dev/docs/reference/instagram/post/index.md) `GET /v1/instagram/post` - [Instagram Posts API](https://staging-fly.socialtap.dev/docs/reference/instagram/posts/index.md) `GET /v1/instagram/posts` - [Instagram Profile API](https://staging-fly.socialtap.dev/docs/reference/instagram/profile/index.md) `GET /v1/instagram/profile` - [Instagram Reels Transcript API](https://staging-fly.socialtap.dev/docs/reference/instagram/transcript/index.md) `GET /v1/instagram/transcript` ### [Rumble](https://staging-fly.socialtap.dev/apis/rumble/index.md) - [Rumble Comments API](https://staging-fly.socialtap.dev/docs/reference/rumble/comments/index.md) `GET /v1/rumble/comments` - [Rumble Video API](https://staging-fly.socialtap.dev/docs/reference/rumble/post/index.md) `GET /v1/rumble/post` - [Rumble Channel Videos API](https://staging-fly.socialtap.dev/docs/reference/rumble/posts/index.md) `GET /v1/rumble/posts` - [Rumble Channel API](https://staging-fly.socialtap.dev/docs/reference/rumble/profile/index.md) `GET /v1/rumble/profile` - [Rumble Search API](https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/index.md) `GET /v1/rumble/search_posts` - [Rumble Transcript API](https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/index.md) `GET /v1/rumble/transcript` ### [Threads](https://staging-fly.socialtap.dev/apis/threads/index.md) - [Threads Profile API](https://staging-fly.socialtap.dev/docs/reference/threads/profile/index.md) `GET /v1/threads/profile` ### [TikTok](https://staging-fly.socialtap.dev/apis/tiktok/index.md) - [TikTok Comments API](https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/index.md) `GET /v1/tiktok/comments` - [TikTok Post API](https://staging-fly.socialtap.dev/docs/reference/tiktok/post/index.md) `GET /v1/tiktok/post` - [TikTok Posts API](https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/index.md) `GET /v1/tiktok/posts` - [TikTok Profile API](https://staging-fly.socialtap.dev/docs/reference/tiktok/profile/index.md) `GET /v1/tiktok/profile` - [TikTok Transcript API](https://staging-fly.socialtap.dev/docs/reference/tiktok/transcript/index.md) `GET /v1/tiktok/transcript` ### [YouTube](https://staging-fly.socialtap.dev/apis/youtube/index.md) - [YouTube Comments API](https://staging-fly.socialtap.dev/docs/reference/youtube/comments/index.md) `GET /v1/youtube/comments` - [YouTube Video API](https://staging-fly.socialtap.dev/docs/reference/youtube/post/index.md) `GET /v1/youtube/post` - [YouTube Channel Videos API](https://staging-fly.socialtap.dev/docs/reference/youtube/posts/index.md) `GET /v1/youtube/posts` - [YouTube Channel API](https://staging-fly.socialtap.dev/docs/reference/youtube/profile/index.md) `GET /v1/youtube/profile` - [YouTube Transcript API](https://staging-fly.socialtap.dev/docs/reference/youtube/transcript/index.md) `GET /v1/youtube/transcript` --- [HTML version](https://staging-fly.socialtap.dev/docs/) · [Docs index for AI agents](https://staging-fly.socialtap.dev/llms.txt) · [All docs in one file](https://staging-fly.socialtap.dev/llms-full.txt)