Search TikTok Users

Search for TikTok users by keyword or username.

Description

This endpoint allows you to search for TikTok users using keywords. It returns a paginated list of user profiles matching your search query, including profile information and statistics.

Endpoint

POST /api/v1/search-tiktok-users

Request Headers

Header	Type	Description
Content-Type	string	Must be application/json.
Authorization	string	Your API key (Bearer token). e.g. Bearer sk_xxx

Request Body

Parameter	Type	Description	Required	Default
query	string	The search query/keyword.	Yes
cursor	number	Optional cursor for pagination. Pass the cursor from a previous response to get the next page.	No
count	number	Number of results to fetch per request.	No	API default
requestSource	string	Optional. Source of the request (e.g., MAKE_DOT_COM, ZAPIER, API).	No	API

The search query can be a username, partial username, or keywords related to user profiles.

Responses

Success (200 OK)

Returns a JSON object containing an array of user search results with pagination information.

{
  "userList": [
    {
      "user": {
        "id": "6123456789012345678",
        "uniqueId": "searchresultuser",
        "nickname": "Search Result User",
        "avatarThumb": "https://...jpeg",
        "signature": "User bio/description",
        "verified": true,
        "secUid": "MS4wLjABAAAA...",
        "privateAccount": false
      },
      "stats": {
        "followerCount": 123456,
        "followingCount": 234,
        "heartCount": 5678901,
        "videoCount": 456,
        "diggCount": 789
      }
    }
    // ... more search results
  ],
  "cursor": 20,
  "hasMore": true
}

Response Headers:

• Content-Type: application/json

• X-RateLimit-Limit: The rate limit for the user.
• X-RateLimit-Remaining: The remaining number of requests for the user.

Error Responses

400 Bad Request

Indicates an issue with the request parameters.

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

Possible error messages:

• Invalid JSON in request body
• 'query' parameter is required and must be a non-empty string.
• The search service could not process the query.
• The search 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

No users found matching the search query.

{
  "error": "No users found for query: [query]"
}

500 Internal Server Error

An unexpected error occurred on the server.

{
  "error": "An unexpected server error occurred while searching TikTok users: [specific error message]"
}

Possible error messages:

• Service not configured. Please contact support.
• Service authentication failed. Please contact support.
• An unexpected server error occurred...

502 Bad Gateway

Indicates an issue with an upstream service.

{
  "error": "Received invalid data structure from search service."
}

Possible error messages:

• The search service is currently unavailable.
• Received invalid data structure from search service.
• Error fetching search results from the upstream service.

503 Service Unavailable

Rate limit exceeded with an upstream service.

{
  "error": "Rate limit exceeded. Please try again later."
}

Example Request

cURL

curl -X POST \
  https://app.dumplingai.com/api/v1/search-tiktok-users \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "query": "cooking" }'

Node.js (fetch)

async function searchTikTokUsers(apiKey, query, cursor = null) {
  const url = 'https://app.dumplingai.com/api/v1/search-tiktok-users';
  const body = { query };
  if (cursor !== null) body.cursor = cursor;

  const options = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify(body)
  };

  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(`Found ${data.userList.length} users`);
    console.log(`Has more: ${data.hasMore}`);
    return data;
  } catch (error) {
    console.error('Failed to search TikTok users:', error);
    return null;
  }
}

// Example usage - search and paginate through results:
async function getAllSearchResults(apiKey, query) {
  let allUsers = [];
  let cursor = null;
  let hasMore = true;

  while (hasMore) {
    const data = await searchTikTokUsers(apiKey, query, cursor);
    if (!data) break;

    allUsers = allUsers.concat(data.userList);
    hasMore = data.hasMore;
    cursor = data.cursor;
  }

  console.log(`Total users found: ${allUsers.length}`);
  return allUsers;
}

// getAllSearchResults('YOUR_API_KEY', 'cooking');

Notes

• Use the cursor field from the response to paginate through search results.
• The hasMore field indicates whether there are additional pages available.
• Search results include both profile information and statistics for each user.
• This endpoint is useful for influencer discovery, competitor analysis, and audience research.
• Results are ranked by relevance to the search query.

Credit Cost

This endpoint costs 10 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.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

query · string · required

cursor · number

count · number

requestSource · enum<string>

Optional identifier describing where the API request originated.

Available options:

API,

WEB,

MAKE_DOT_COM,

ZAPIER,

N8N,

PLAYGROUND,

DEFAULT_AUTOMATION,

AGENT_PREVIEW,

AGENT_LIVE,

AUTOPILOT,

STUDIO

Response

200

application/json

TikTok user search results returned.

userList · object[]

cursor · number | null

hasMore · boolean | null