Description
This endpoint allows you to fetch a paginated list of videos from a specified TikTok user’s profile. It returns comprehensive video metadata including statistics, timestamps, and pagination support for accessing more videos.
Endpoint
POST /api/v1/get-tiktok-profile-videos
| 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 |
|---|
handle | string | The TikTok user handle (username). | Yes | |
maxCursor | string | Optional cursor for pagination. Pass the max_cursor from a previous response to get the next page. | No | |
trim | boolean | Whether to get a trimmed/simplified response. | No | false |
requestSource | string | Optional. Source of the request (e.g., MAKE_DOT_COM, ZAPIER, API). | No | API |
The handle is the username you see on TikTok, like stoolpresidente. Do not include the @ symbol.
Responses
Success (200 OK)
Returns a JSON object containing an array of videos and pagination information.
{
"aweme_list": [
{
"aweme_id": "7460293617584139566",
"desc": "Video description text here",
"create_time": 1736092800,
"statistics": {
"comment_count": 1234,
"digg_count": 56789,
"download_count": 123,
"play_count": 987654,
"share_count": 456
},
"video": {
"duration": 15,
"cover": {
"url_list": ["https://..."]
}
},
"author": {
"unique_id": "username",
"nickname": "Display Name"
}
}
// ... more videos
],
"max_cursor": "1736092800000",
"min_cursor": "1735488000000",
"has_more": 1,
"extra": {
"now": 1736179200000
}
}
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": "'handle' parameter is required and must be a non-empty string."
}
Invalid JSON in request body'handle' parameter is required and must be a non-empty string.The video service could not process the handle.The video 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 videos: [specific error message]"
}
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 format from video service."
}
The video service is currently unavailable.Received invalid data format from video service.Error fetching video data 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/get-tiktok-profile-videos \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "handle": "stoolpresidente" }'
Node.js (fetch)
async function getTikTokProfileVideos(apiKey, handle, maxCursor = null) {
const url = 'https://app.dumplingai.com/api/v1/get-tiktok-profile-videos';
const body = { handle };
if (maxCursor) body.maxCursor = maxCursor;
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(`Fetched ${data.aweme_list.length} videos`);
console.log(`Has more: ${data.has_more}`);
return data;
} catch (error) {
console.error('Failed to fetch TikTok profile videos:', error);
return null;
}
}
// Example usage:
// getTikTokProfileVideos('YOUR_API_KEY', 'stoolpresidente');
Notes
- Use the
max_cursor field from the response to paginate through all videos.
- The
has_more field indicates whether there are additional pages available (1 = yes, 0 = no).
- Video statistics include view counts, likes (digg_count), comments, shares, and downloads.
Credit Cost
This endpoint costs 1 credit 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.