Submit a Profile Job

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.

Note

All requests require your Megomi API key, via either the Authorization: Bearer <key> header or the X-API-Key header.

Endpoints

Method	Path	Returns
POST	/api/v1/tiktok/profile	Submit a profile lookup
GET	/api/v1/tiktok/profile/{requestId}	Poll a submitted profile job

Request & Response

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. Max 100 chars
userId	string	One of handle or userId	TikTok numeric user id. Max 64 chars

Response body

Field	Type	Description
requestId	string	Opaque ID for this request. Keep it to poll GET /api/v1/tiktok/profile/{requestId} later
handle	string	Resolved TikTok handle
userId	string	Resolved TikTok numeric user id
status	string	queued | processing | success | not-found | blocked | timed-out | cancelled
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
result	object | null	The TikTok profile JSON (user/stats/itemList). null until the job resolves
finishReason	string | null	Present once the job reaches a terminal status

Responses come back 200 with a terminal result if the job resolves within the hold window. Otherwise 202 — poll GET /api/v1/tiktok/profile/{requestId}, or resubmit the same target (it coalesces onto the still-in-flight job, at no extra charge).

cURL

curl -X POST "https://api.megomi.com/api/v1/tiktok/profile" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"handle": "@creator"}'

Node.js

const res = await fetch("https://api.megomi.com/api/v1/tiktok/profile", {
  method: "POST",
  headers: {
    "x-api-key": process.env.MEGOMI_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({ handle: "@creator" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.megomi.com/api/v1/tiktok/profile",
    json={"handle": "@creator"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
print(res.json())

PHP

<?php
$ch = curl_init("https://api.megomi.com/api/v1/tiktok/profile");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY", "content-type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["handle" => "@creator"]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);

Go

body, _ := json.Marshal(map[string]string{"handle": "@creator"})
req, _ := http.NewRequest("POST", "https://api.megomi.com/api/v1/tiktok/profile", bytes.NewReader(body))
req.Header.Set("x-api-key", "YOUR_API_KEY")
req.Header.Set("content-type", "application/json")
resp, _ := http.DefaultClient.Do(req)

200 · success

{
  "requestId": "req_9f1kQ3zP7mLxA2dR",
  "handle": "creator",
  "userId": "6852391238123456789",
  "status": "success",
  "coalesced": false,
  "cached": false,
  "result": { "user": { "id": "6852...", "uniqueId": "creator" }, "stats": { "followerCount": 128400 } },
  "finishReason": null
}

202 · queued

{
  "requestId": "req_7bN0wVh4TzKx9pQe",
  "handle": "creator",
  "userId": "",
  "status": "queued",
  "coalesced": false,
  "cached": false,
  "result": null
}

400

{ "status": 400, "title": "Bad Request", "detail": "handle or userId is required" }

401

{ "status": 401, "title": "Unauthorized", "detail": "invalid API key" }

402

{
  "status": 402,
  "title": "Payment Required",
  "detail": "insufficient credit balance",
  "required": 1,
  "balance": 0
}

403 · blocked

{
  "status": 403,
  "title": "Forbidden",
  "detail": "the source blocked this profile lookup (age-gated, bot-checked, or otherwise inaccessible)",
  "requestId": "req_2wYh8LmN5vRtCx1s",
  "handle": "creator",
  "userId": "",
  "finishReason": "blocked"
}

Poll a submitted job

If your submit came back 202, fetch the result later with the requestId:

GET/api/v1/tiktok/profile/{requestId}

Returns the current state of the request. A 404 means the requestId doesn’t belong to your key. A blocked job returns 403, same shape as the submit response above.

Field	Type	Description
requestId	string	The request you polled
handle	string	Resolved TikTok handle
userId	string	Resolved TikTok numeric user id
status	string	Current job status
requestCount	number	How many times this job has been requested
result	object | null	The TikTok profile JSON, null until resolved
finishReason	string | null	Present once terminal
createdAt	string	ISO-8601 timestamp
finishedAt	string | null	ISO-8601 timestamp, once terminal

cURL

curl "https://api.megomi.com/api/v1/tiktok/profile/req_9f1kQ3zP7mLxA2dR" \
  -H "x-api-key: YOUR_API_KEY"

Node.js

const res = await fetch(
  "https://api.megomi.com/api/v1/tiktok/profile/req_9f1kQ3zP7mLxA2dR",
  { headers: { "x-api-key": process.env.MEGOMI_API_KEY } },
);
const data = await res.json();