Description

This endpoint allows you to fetch detailed public profile information for a specified TikTok user, including user details, statistics, and a list of recent items (if available from the service).

Endpoint

POST /api/v1/get-tiktok-profile

Request Headers

HeaderTypeDescription
Content-TypestringMust be application/json.
AuthorizationstringYour API key (Bearer token). e.g. Bearer sk_xxx

Request Body

ParameterTypeDescriptionRequiredDefault
handlestringThe TikTok user handle (username).Yes
requestSourcestringOptional. Source of the request (e.g., MAKE_DOT_COM, ZAPIER, API). Defaults to API if not provided or if sent via header.NoAPI

The handle is the username you see on TikTok, like stoolpresidente.

Responses

Success (200 OK)

Returns a JSON object containing the user’s profile data.

{
  "user": {
    "id": "6659752019493208069", // TikTok's internal user ID
    "shortId": "", // Short ID if available
    "uniqueId": "stoolpresidente", // The handle/username
    "nickname": "Dave Portnoy", // Display name
    "avatarLarger": "https://p16-sign-va.tiktokcdn.com/...jpeg", // URL to larger avatar
    "avatarMedium": "https://p16-sign-va.tiktokcdn.com/...jpeg", // URL to medium avatar
    "avatarThumb": "https://p16-sign-va.tiktokcdn.com/...jpeg", // URL to thumbnail avatar
    "signature": "El Presidente/Barstool Sports Founder.", // User's bio/signature
    "createTime": 1550594547, // Timestamp of account creation
    "verified": true, // Whether the account is verified
    "secUid": "MS4wLjABAAAAINC_ElRR-l1RCcnEjOZhNO-9wOzAMf-YHXqRY8vvG9bEhMRa6iu23TaE3JPZYXBD", // Secured User ID
    "ftc": false,
    "relation": 0,
    "openFavorite": false,
    "bioLink": { // Optional: details about the link in bio
      "link": "https://www.barstoolsports.com/bios/Surviving-Barstool",
      "risk": 0
    },
    "commentSetting": 0,
    "commerceUserInfo": { "commerceUser": false },
    "duetSetting": 0,
    "stitchSetting": 0,
    "privateAccount": false, // Whether the account is private
    "secret": false,
    "isADVirtual": false,
    "roomId": "",
    "uniqueIdModifyTime": 0,
    "ttSeller": false,
    "region": "US", // User's region
    "downloadSetting": 0,
    "profileTab": {
      "showMusicTab": false,
      "showQuestionTab": false,
      "showPlayListTab": true
    },
    "followingVisibility": 1,
    "recommendReason": "",
    "nowInvitationCardUrl": "",
    "nickNameModifyTime": 0,
    "isEmbedBanned": false,
    "canExpPlaylist": true,
    "profileEmbedPermission": 1,
    "language": "en", // Profile language
    "eventList": [],
    "suggestAccountBind": false,
    "isOrganization": 0
  },
  "stats": {
    "followerCount": 4100000, // Number of followers
    "followingCount": 74, // Number of accounts followed
    "heart": 190400000, // Total hearts received (legacy or alternative field)
    "heartCount": 190400000, // Total hearts received
    "videoCount": 2017, // Number of videos posted
    "diggCount": 0, // Number of diggs (likes) given - may not always be populated
    "friendCount": 52 // Number of friends
  },
  "itemList": [] // List of recent items/videos, structure might vary or be empty
}

Response Headers:

  • Content-Type: application/json
  • X-RateLimit-Limit: Your current rate limit ceiling.
  • X-RateLimit-Remaining: Remaining requests in the current window.

Error Responses

400 Bad Request

Indicates an issue with the request parameters.

{
  "error": "'handle' parameter is required and must be a non-empty string."
}

Possible error messages:

  • Invalid JSON in request body
  • 'handle' parameter is required and must be a non-empty string.
  • The profile service could not process the handle.
  • The profile service reported an issue.

401 Unauthorized

API key is missing, invalid, or inactive.

{
  "error": "API key is invalid or missing."
}

403 Forbidden

API key does not have enough credits.

{
  "error": "Insufficient credits. Please top up your account."
}

404 Not Found

The requested TikTok profile could not be found.

{
  "error": "TikTok profile not found for handle: [handle]"
}

500 Internal Server Error

An unexpected error occurred on the server.

{
  "error": "An unexpected server error occurred while fetching the TikTok profile: [specific error message]"
}

Possible error messages:

  • Service not configured. Please contact support.
  • Service authentication failed. Please contact support.
  • An unexpected server error occurred... (for other internal issues)

502 Bad Gateway

Indicates an issue with an upstream service.

{
  "error": "Received invalid data format from profile service."
}

Possible error messages:

  • The profile service is currently unavailable.
  • Received invalid data format from profile service.
  • Error fetching profile data from the upstream service.

503 Service Unavailable

Rate limit exceeded with an upstream service.

{
  "error": "Rate limit exceeded with the profile service. Please try again later."
}

Example Request

cURL

curl -X POST \
  https://api.dumpling.ai/api/v1/get-tiktok-profile \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "handle": "stoolpresidente" }'

Node.js (fetch)

async function getTikTokProfile(apiKey, handle) {
  const url = 'https://api.dumpling.ai/api/v1/get-tiktok-profile';
  const options = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({ handle })
  };

  try {
    const response = await fetch(url, options);
    const data = await response.json();
    if (!response.ok) {
      console.error(`Error: ${response.status}`, data);
      return null;
    }
    console.log(data);
    return data;
  } catch (error) {
    console.error('Failed to fetch TikTok profile:', error);
    return null;
  }
}

// Example usage:
// getTikTokProfile('YOUR_API_KEY', 'stoolpresidente');

Notes

  • The itemList in the response may vary in content and structure depending on the profile and the data provided by the upstream service. It might be empty for some profiles.

Credit Cost

This endpoint costs 2 credits per successful request. For more details, see our Credit Costs page.

Rate Limiting

This endpoint is subject to standard API rate limits. Check the X-RateLimit-Limit and X-RateLimit-Remaining headers in the response to monitor your usage.