POST /api/v1/tiktok/profile — 1 credit per request
Look up a TikTok profile by its handle (uniqueId) or numeric userId. The result is the TikTok profile JSON — user, stats, and itemList — close to as returned by TikTok’s own web app. Send the profile in the JSON body, or as query parameters to get the extended response (see below).
Endpoint
Section titled “Endpoint”| Method | Path | Returns |
|---|---|---|
| POST | /api/v1/tiktok/profile |
Profile details |
Request & Response
Section titled “Request & Response”Request body
Section titled “Request body”Provide either handle or userId — exactly one is required. If both are given, handle takes precedence.
| Name | Type | Required | Description |
|---|---|---|---|
handle |
string | One of handle or userId |
TikTok handle (uniqueId), case-insensitive, a leading @ is stripped. Letters, digits, . and _ only. Max 100 chars. A profile URL (https://www.tiktok.com/@<handle>) or a profile share link also works. A video, sound or other URL is a 400 that names what it is |
userId |
string | One of handle or userId |
TikTok numeric user id (digits only) or the secUid (MS4wLjABAAAA + base64url). Max 64 chars. A https://www.tiktok.com/share/user/<id> URL or share link is read as a user id. A numeric id that belongs to no account, or a secUid this API has never seen, ends in an uncharged 403. Once a profile has been looked up by handle or numeric id, its secUid works too |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
requestId |
string | Opaque ID for this request. Keep it if you plan to resubmit later |
handle |
string | Resolved TikTok handle |
userId |
string | Resolved TikTok numeric user id |
status |
string | "success" — the only value a 200 response carries |
coalesced |
boolean | true if this request attached to an already-in-flight job for the same profile |
cached |
boolean | true if served from a fresh, previously-scraped result. Free if your key already paid for this target in the last 10 minutes; charged otherwise |
result |
object | The TikTok profile JSON (user/stats/itemList) |
finishReason |
string | target-found on a freshly fetched answer; absent on a cached one |
Extended response (query parameters)
Section titled “Extended response (query parameters)”Send the profile as query parameters instead of a body, ?handle=nasa or ?user_id=<id>, to get TikTok’s full user and stats objects. Using any query parameter switches on the extended response. Send the profile in the body or in the query, never both (400).
| Name | Type | Description |
|---|---|---|
handle |
string | Same rules as the body’s handle. Pass handle or user_id |
user_id |
string | Same rules as the body’s userId |
The extended response keeps every field above and adds:
| Field | Type | Description |
|---|---|---|
success |
boolean | Always true on a 200 |
credits_charged |
integer | Credits this request cost; 0 for a profile your key already paid for |
credits_remaining |
integer | Your balance after this request |
cached_at |
string | When a cached answer was fetched. Cached answers only |
user |
object | TikTok’s user object in its own web field names. A field is present only when TikTok sent it. Avatar links expire, so download them |
stats |
object | followerCount, followingCount, heart, heartCount, videoCount, diggCount, friendCount, each present only when TikTok reported it |
itemList |
array | Always []: a profile lookup returns no videos |
curl -X POST "https://api.megomi.my.id/api/v1/tiktok/profile?handle=nasa" \ -H "x-api-key: YOUR_API_KEY"The submit waits for its job to finish, up to 45 seconds, and answers as soon as a result is ready. Only a 200 is ever charged. Otherwise you get 404 (profile doesn’t exist), 403 (blocked by TikTok), or 503 (no data fetched in time) — none of which are charged. Resubmitting the same target either way attaches to the still-in-flight job or returns the by-then-resolved result inline, at no extra charge.
curl -X POST "https://api.megomi.my.id/api/v1/tiktok/profile?handle=nasa" \ -H "x-api-key: YOUR_API_KEY"const params = new URLSearchParams({ handle: "nasa" });const res = await fetch(`https://api.megomi.my.id/api/v1/tiktok/profile?${params}`, { method: "POST", headers: { "x-api-key": process.env.MEGOMI_API_KEY },});const data = await res.json();import requests
res = requests.post( "https://api.megomi.my.id/api/v1/tiktok/profile", params={"handle": "nasa"}, headers={"x-api-key": "YOUR_API_KEY"},)print(res.json())<?php$url = "https://api.megomi.my.id/api/v1/tiktok/profile?" . http_build_query(["handle" => "nasa"]);$ch = curl_init($url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);echo curl_exec($ch);q := url.Values{}q.Set("handle", "nasa")req, _ := http.NewRequest("POST", "https://api.megomi.my.id/api/v1/tiktok/profile?"+q.Encode(), nil)req.Header.Set("x-api-key", "YOUR_API_KEY")resp, _ := http.DefaultClient.Do(req){ "requestId": "req_9f1kQ3zP7mLxA2dR", "handle": "nasa", "userId": "6676352902760727557", "status": "success", "coalesced": false, "cached": false, "result": { "handle": "nasa", "userId": "6676352902760727557", "nickname": "NASA", "verified": true, "privateAccount": false, "isCommerceUser": false, "avatarUrl": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/avatar~c5_1080x1080.jpeg", "followerCount": 2400000, "followingCount": 12, "heartCount": 31200000, "videoCount": 376, "friendCount": 3 }, "finishReason": "target-found", "success": true, "credits_charged": 1, "credits_remaining": 999, "user": { "id": "6676352902760727557", "shortId": "", "uniqueId": "nasa", "nickname": "NASA", "avatarLarger": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/avatar~c5_1080x1080.jpeg", "avatarMedium": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/avatar~c5_720x720.jpeg", "avatarThumb": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/avatar~c5_100x100.jpeg", "signature": "Exploring the universe and our home planet.", "createTime": 1550594547, "verified": true, "secUid": "MS4wLjABAAAAexampleSecUid", "ftc": false, "openFavorite": false, "bioLink": { "link": "https://www.nasa.gov/", "risk": 0 }, "commentSetting": 0, "commerceUserInfo": { "commerceUser": false }, "duetSetting": 0, "stitchSetting": 0, "privateAccount": false, "secret": false, "isADVirtual": false, "roomId": "", "uniqueIdModifyTime": 0, "ttSeller": false, "downloadSetting": 0, "profileTab": { "showMusicTab": false, "showQuestionTab": false, "showPlayListTab": true }, "followingVisibility": 1, "nowInvitationCardUrl": "", "nickNameModifyTime": 0, "isEmbedBanned": false, "canExpPlaylist": true, "profileEmbedPermission": 1, "language": "en", "eventList": [], "isOrganization": 0 }, "stats": { "followerCount": 2400000, "followingCount": 12, "heart": 31200000, "heartCount": 31200000, "videoCount": 376, "diggCount": 0, "friendCount": 3 }, "itemList": []}{ "status": 400, "title": "Bad Request", "detail": "handle or userId is required" }{ "status": 401, "title": "Unauthorized", "detail": "invalid API key" }{ "status": 402, "title": "Payment Required", "detail": "insufficient credit balance", "required": 1, "balance": 0}{ "status": 403, "title": "Forbidden", "detail": "TikTok answered this profile lookup with a captcha challenge; you were not charged. Retry in a few minutes", "requestId": "req_2wYh8LmN5vRtCx1s", "handle": "nasa", "userId": "", "finishReason": "captcha-challenge"}{ "status": 404, "title": "Not Found", "detail": "TikTok reports no account with this handle; you were not charged. This answer is cached for an hour", "requestId": "req_5mPq1XwK8jVcT4nR", "finishReason": "user-not-found"}{ "status": 503, "title": "Service Unavailable", "detail": "no data fetched within 45s; you were not charged. The lookup is still running: submitting the same request again shortly may return it from cache, and is never charged twice", "requestId": "req_1qLr6PxV8nWtE3sJ", "finishReason": "no-data-fetched"}