TikTok · Profile Beta

TikTok Profile API

Returns a public TikTok account: user ID, username, display name, bio, bio link, avatar, verification badge, whether the account is private, its business category, join date and exact follower, following, video and total like counts. Accepts a username with or without the @, a tiktok.com profile URL, or a numeric user ID.

GET https://staging.socialtap.dev/v1/tiktok/profile

Try it in the playgroundQuickstart

  • From 1 credit per request
  • Sources: Public page

Use cases

  • Track creator growth over time
  • Vet influencers before a campaign
  • Enrich CRM or lead lists with TikTok accounts
  • Resolve a post author's ID to a full profile

Example request

Send a GET request with your key in the x-api-key header.

cURL
curl -G 'https://staging.socialtap.dev/v1/tiktok/profile' \
  --data-urlencode 'handle=nasa' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
TypeScript
const params = new URLSearchParams({
  handle: "nasa",
});
const res = await fetch(`https://staging.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
import os

import requests

res = requests.get(
    "https://staging.socialtap.dev/v1/tiktok/profile",
    params={"handle": "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
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"
)

func main() {
	q := url.Values{}
	q.Set("handle", "nasa")
	req, err := http.NewRequest("GET", "https://staging.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"])
}

Parameters

NameTypeDescriptionExample
handle requiredstring
max 2,048 chars
TikTok username with or without the @ (nasa, @nasa), a profile URL (tiktok.com/@nasa, m.tiktok.com/@nasa, with or without query parameters), or a numeric user ID (tiktok.com/share/user/<id> or the bare ID). Usernames are case-insensitive.nasa

handle takes TikTok profile links. A link of another kind or platform fails free with invalid_input, naming the endpoint that takes it. Parameters not listed here are rejected (with a suggestion for a likely typo), so a misspelled one never silently changes nothing: see Requests.

Every endpoint also accepts max_age, fields.

Example response

A 200 response is {data, meta}: data is a profile object, meta describes the request (meta fields).

200 OK
{
  "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=SCRUBBED&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",
    "type": "organization",
    "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"
  }
}

Response fields

data follows the shared Profile schema, identical on every platform.

FieldTypeDescription
data.platformstringPlatform ID (tiktok, youtube, …).
data.idstringPlatform-native account ID (string; YouTube UC…, Reddit without t2_).
data.usernamestring or nullHandle without the @; null when the account has none.
data.display_namestring or nullDisplay name, channel title or page name; null when empty or not exposed.
data.urlstring (uri)Canonical profile URL.
data.typestringCoarse account kind, as the platform labels it; unknown when it does not (TikTok labels organizations only). New values may be added; treat unknown values as unknown.
One of person, organization, community, unknown
data.biostring or nullProfile bio, channel description or page about text; null when empty or not exposed.
data.avatar_urlstring (uri) or nullProfile picture URL (largest available). Platform CDN URLs can expire within hours.
data.banner_urlstring (uri) or nullHeader or cover image URL.
data.is_verifiedboolean or nullPlatform verification badge; null where the platform has no badge.
data.is_privateboolean or nullTrue when the account's posts are not public.
data.categorystring or nullPlatform category label (e.g. Musician, Media & Entertainment), as shown; not normalized. Often set only for business or creator accounts.
data.external_linksobject[]Links in the bio or channel links; [] if none or not exposed.
data.external_links[].urlstring (uri)Link target, absolute (https:// is added where the platform stores the link without a scheme).
data.external_links[].titlestring or nullLink label shown by the platform.
data.locationstring or nullSelf-declared location text.
data.country_codestring or nullISO 3166-1 alpha-2 country the platform states for the account.
data.created_atstring (date-time) or nullAccount creation or join date, RFC 3339 UTC (some platforms give only the day: see approximate_fields).
data.metricsobjectCounts at fetch time; null = hidden or not exposed, 0 = zero.
data.metrics.follower_countinteger or nullFollowers or subscribers.
data.metrics.following_countinteger or nullAccounts this profile follows.
data.metrics.post_countinteger or nullPosts or videos as the platform counts them on the profile (for a private account, posts the caller cannot see).
data.metrics.total_like_countinteger or nullLikes received across all of the profile's posts (not likes given).
data.metrics.total_view_countinteger or nullLifetime views across all of the profile's posts.
data.approximate_fieldsstring[]JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.follower_count); [] when all exact.

Pricing

You pay only for successful requests. The price depends on which source produced the result, reported as meta.source.

SourcePrice per successful requestPer 1,000 requests
Public page page1 credit$0.50–$0.80
meta.sourceSourceWhat it means
pagePublic pageData embedded in the platform's public web page.

Your balance must be at least 1 credit to start a request; with less, it is refused with insufficient_credits (HTTP 402) and costs nothing. Only that minimum is set aside when the request starts.

meta.credits_charged and the x-credits-charged header show what you paid. How credits work · Packs

Errors

Errors cost nothing. Codes marked “Yes, later” under Retry can succeed on a later attempt; the others return the same answer every time.

CodeHTTPRetryMeaningWhat to do
invalid_input400NoThe request parameters are missing or malformed, or the URL is not a supported link for this endpoint.Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.
unauthorized401NoThe x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired).Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).
forbidden403NoThe API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include.Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.
insufficient_credits402NoThe account does not have enough credits for this request.Buy a credit pack, then repeat the request; do not retry automatically.
spend_limit_reached402NoThe API key reached its spend limit for the current period; the account may still have credits.Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.
rate_limited429Yes, laterThe account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request.Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more.
not_found404NoThe item does not exist or was deleted.Check the URL or ID; do not retry.
private_or_unavailable403NoThe item exists but is private, age- or region-gated, or requires a login to view.Only public items can be fetched; do not retry.
upstream_blocked503Yes, laterThe platform refused every attempt.Retry later with backoff; failed requests are free.
upstream_error502Yes, laterThe platform failed or returned something unexpected.Retry with backoff; failed requests are free.
overloaded503Yes, laterSocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged.Retry after the number of seconds in the retry-after header; failed requests are free.
internal500Yes, laterUnexpected SocialTap error.Retry with backoff; contact support with the request_id if it persists.

not_found and private_or_unavailable are item-level: the request was fine, the item can't be returned.

Test mode

A key starting with st_test_ gets recorded responses, free and the same every time (test mode). These inputs return their recording; any other input returns the example above.

InputAnswer
qq7x2nouser0z404 not_found
scout2015200 OK
duolingo200 OK
@khaby.lame200 OK
bts_official_bighit200 OK
zzq9x81nouser404 not_found
https://www.tiktok.com/@nasa Default200 OK
7000000000000000001404 not_found
https://www.tiktok.com/share/user/107955200 OK

Magic inputs: send one of these as handle to get that error.

ErrorValue
invalid_inputsocialtap_test_invalid_input
insufficient_creditssocialtap_test_insufficient_credits
spend_limit_reachedsocialtap_test_spend_limit_reached
rate_limitedsocialtap_test_rate_limited
not_foundsocialtap_test_not_found
private_or_unavailablesocialtap_test_private_or_unavailable
upstream_blockedsocialtap_test_upstream_blocked
upstream_errorsocialtap_test_upstream_error
overloadedsocialtap_test_overloaded
internalsocialtap_test_internal

FAQ

How much does the TikTok Profile API cost?
1 credit for public page results (meta.source = page), charged only for successful requests. SocialTap credits cost $0.50–$0.80 per 1,000 depending on the pack.
Am I charged for failed requests?
No. Requests that return an error cost 0 credits. Responses served from the cache are free too.