SignalShelf · Developer documentation

TikTok profile

Sample profile responses are available. Live profile lookups are disabled in production pending source authorization and deployment-region verification.

Request

POST /api/v1/profiles · authenticate with the x-api-key header.

Parameter	Type	Required	Description
`platform`	string	Yes	"tiktok"
`handle`	string	Yes	Username without @.
`mode`	string	No	"live" for real data, "demo" for a free labeled sample. Default "demo".
`freshness`	string	No	Oldest cached result you accept: "1h", "24h" (default), "7d", or "live" to force a refresh.

REQUEST EXAMPLE

curl "$SIGNALSHELF_BASE_URL/api/v1/profiles" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SIGNALSHELF_API_KEY" \
  --data '{"platform":"tiktok","handle":"khaby.lame","mode":"demo","freshness":"24h"}'

const response = await fetch(`${process.env.SIGNALSHELF_BASE_URL}/api/v1/profiles`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.SIGNALSHELF_API_KEY },
  body: JSON.stringify({platform: "tiktok", handle: "khaby.lame", mode: "demo", freshness: "24h"}),
});
const { data, meta } = await response.json();

import os, requests

response = requests.post(
    f"{os.environ['SIGNALSHELF_BASE_URL']}/api/v1/profiles",
    headers={"x-api-key": os.environ["SIGNALSHELF_API_KEY"]},
    json={"platform":"tiktok","handle":"khaby.lame","mode":"demo","freshness":"24h"},
    timeout=30,
)
data = response.json()["data"]

Example response

Labeled sample fixture. Values are illustrative and do not describe a real creator.

EXAMPLE

{
  "data": {
    "platform": "tiktok",
    "handle": "khaby.lame",
    "name": "Sample creator",
    "bio": "Illustrative sample data for exploring SignalShelf. Not a real profile lookup.",
    "followers": 128400,
    "following": 842,
    "posts": 326,
    "verified": false,
    "url": "https://www.tiktok.com/@khaby.lame",
    "avatar": null,
    "sample": true,
    "provider": "sample-fixture",
    "details": {
      "likes": 0,
      "friends": 0,
      "liked_videos": 0,
      "sec_uid": null,
      "language": null,
      "is_private": false,
      "is_organization": false,
      "commerce_user": null,
      "tiktok_seller": null,
      "avatar_medium": null,
      "avatar_thumb": null
    }
  },
  "meta": {
    "event_id": "sample",
    "mode": "demo",
    "cache": "SAMPLE",
    "credits_charged": 0,
    "fetched_at": null,
    "age_seconds": null,
    "duration_ms": 0
  }
}

Profile fields

Every platform returns these fields. Fields a platform does not expose are null (or [] for links); they are never guessed.

Field	Type	Description
`platform`	string	Platform you requested.
`handle`	string	Normalized handle (lowercase, no @).
`name`	string	Display name.
`bio`	string	Profile description, as shown publicly.
`followers`	number	Follower or subscriber count.
`following`	number	Accounts this profile follows.
`posts`	number	Total posts, videos, pins or repositories, depending on platform.
`verified`	boolean	Platform verification badge, when exposed.
`url`	string	Canonical public profile URL.
`avatar`	string \| null	Profile picture URL (largest available).
`sample`	boolean	Always false for live data; true only in sample mode.
`provider`	string	Engine that produced the data.
`details`	object	Platform-specific fields, listed below.

TikTok-specific fields (details)

Returned inside data.details.

Field	Type	Description
`details.likes`	number	Total likes received.
`details.friends`	number	Mutual follows.
`details.liked_videos`	number	Videos this user liked.
`details.sec_uid`	string \| null	Stable secure user ID.
`details.language`	string \| null	Account language.
`details.is_private`	boolean	Whether this profile is private. Only public profile-header fields are returned for private accounts.
`details.is_organization`	boolean	Organization account.
`details.commerce_user`	string \| null	Commerce-enabled account.
`details.tiktok_seller`	string \| null	TikTok Shop seller.
`details.avatar_medium`	string \| null	Medium avatar URL.
`details.avatar_thumb`	string \| null	Thumbnail avatar URL.

Response metadata

Field	Type	Description
`meta.cache`	string	HIT (served from cache, 0 credits), MISS (fresh fetch) or SAMPLE.
`meta.credits_charged`	number	Credits charged for this request.
`meta.fetched_at`	string	When the data was fetched from the source.
`meta.age_seconds`	number	Age of the data at response time.
`meta.duration_ms`	number	Server processing time.

Errors

Every failure is free: reserved credits are refunded automatically.

Field	Type	Description
`404 PROFILE_NOT_FOUND`	error	The profile does not exist publicly.
`422 PROFILE_UNAVAILABLE`	error	The source did not expose even the public profile fields for this account.
`503 SOURCE_NOT_AUTHORIZED`	error	Live access for this platform is disabled in production pending source authorization. No credits are charged.
`503 SOURCE_AUTH_REQUIRED`	error	The source demanded a login for this request. Retry later.
`503 UPSTREAM_RATE_LIMITED`	error	The source is rate limiting. Retry after the Retry-After header.
`402 INSUFFICIENT_CREDITS`	error	Not enough credits for a fresh lookup. Cached and sample results stay free.

Limitations

TikTok live profile requests are disabled in production pending written source authorization and independent review. Live access also remains unverified from this deployment region.

TikTok live profile requests are disabled in production until written source authorization and an independent review are complete. Live access has not passed verification from this deployment region.

Local parser tests and successful page reads do not grant permission to commercialize a source method.

For a private account, only fields exposed in its public profile header are returned; no private posts or media are included.

Live availability varies by region. SignalShelf does not route around regional restrictions; TikTok live access is unverified and production-gated pending source authorization.

Explore the API in your workspace. Sample results and accepted cache hits cost zero credits. Open the playground →