Skip to main content
GET
/
tiktok
/
profile
/
{task_id}
Get TikTok profile scrape result
curl --request GET \
  --url https://api.vidnavigator.com/v1/tiktok/profile/{task_id} \
  --header 'X-API-Key: <api-key>'
{
  "status": "success",
  "data": {
    "task_id": "<string>",
    "task_status": "processing",
    "profile_url": "<string>",
    "profile": {},
    "filters": {
      "max_posts": 123,
      "after_date": "<string>",
      "before_date": "<string>",
      "min_likes": 123,
      "max_likes": 123
    },
    "stats": {
      "videos_scanned": 123,
      "videos_matched": 123,
      "pages_consumed": 123
    },
    "videos": [
      {
        "id": "<string>",
        "track": "<string>",
        "artists": [
          "<string>"
        ],
        "duration": 123,
        "title": "<string>",
        "description": "<string>",
        "timestamp": 123,
        "views": 123,
        "likes": 123,
        "reposts": 123,
        "comments": 123,
        "thumbnails": [
          {}
        ],
        "url": "<string>"
      }
    ],
    "pagination": {
      "limit": 123,
      "offset": 123,
      "total_items": 123,
      "has_next": true,
      "has_prev": true,
      "next_cursor": "<string>",
      "prev_cursor": "<string>"
    },
    "download_url": "https://storage.googleapis.com/bucket/api/tiktok_profiles/user/task.json?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Signature=...",
    "error_message": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "completed_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z"
  }
}
Poll a TikTok profile scrape task and retrieve cursor-paginated videos once the background job finishes.

​
Overview

This endpoint is the second half of the TikTok profile scraping workflow. Use it after you submit a scrape with POST /tiktok/profile. It serves three purposes:
  • check whether the task is still running
  • retrieve the filtered video results page by page
  • get a temporary download_url for the full JSON result when available
This endpoint does not consume credits.

​
Request Parameters

ParameterInRequiredDescription
task_idpathYesTask ID returned by POST /tiktok/profile
cursorqueryNoOpaque pagination cursor from a previous response
limitqueryNoMaximum number of videos to return, between 1 and 500. Default is 50.

​
How Pagination Works

Pagination is cursor-based, but the cursor encodes an absolute offset. That means you can safely change limit between requests without skipping or duplicating videos. Typical flow:
  1. Call the endpoint with no cursor.
  2. Read data.pagination.next_cursor.
  3. Pass that value back as the next request’s cursor.
  4. Stop when has_next is false.

​
Polling Lifecycle

The task_status field will be one of:
  • processing: the scrape is still running
  • completed: the scrape finished and results are ready
  • failed: the scrape ended with an error
While the task is still processing:
  • profile may be null
  • videos will be empty
  • download_url will usually be null
Once completed:
  • videos contains a cursor-paginated page of matching posts
  • pagination tells you whether more pages exist
  • download_url may contain a temporary signed URL for the full JSON result

​
Example Requests

curl "https://api.vidnavigator.com/v1/tiktok/profile/tt_profile_abc123?limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

​
Fetch the Next Page

cURL
curl "https://api.vidnavigator.com/v1/tiktok/profile/tt_profile_abc123?limit=25&cursor=eyJvZmZzZXQiOjI1fQ==" \
  -H "X-API-Key: YOUR_API_KEY"

​
Example Completed Response

{
  "status": "success",
  "data": {
    "task_id": "tt_profile_abc123",
    "task_status": "completed",
    "profile_url": "https://www.tiktok.com/@tiktok",
    "profile": {
      "uploader": "tiktok",
      "follower_count": 12345678
    },
    "filters": {
      "max_posts": 50,
      "after_date": "20240101",
      "before_date": null,
      "min_likes": 10000,
      "max_likes": null
    },
    "stats": {
      "videos_scanned": 120,
      "videos_matched": 50,
      "pages_consumed": 8
    },
    "videos": [
      {
        "id": "7351234567890123456",
        "track": "Original sound",
        "artists": ["Creator Name"],
        "duration": 28,
        "title": "Example TikTok",
        "description": "Video caption text here",
        "timestamp": 1712345678,
        "views": 250000,
        "likes": 22000,
        "reposts": 180,
        "comments": 950,
        "thumbnails": [],
        "url": "https://www.tiktok.com/@tiktok/video/7351234567890123456"
      }
    ],
    "pagination": {
      "limit": 25,
      "offset": 0,
      "total_items": 50,
      "has_next": true,
      "has_prev": false,
      "next_cursor": "eyJvZmZzZXQiOjI1fQ==",
      "prev_cursor": null
    },
    "download_url": "https://storage.googleapis.com/bucket/api/tiktok_profiles/user/task.json?...",
    "error_message": null,
    "created_at": "2026-04-25T20:00:00Z",
    "completed_at": "2026-04-25T20:01:12Z",
    "expires_at": "2026-04-25T21:00:00Z"
  }
}

​
Understanding the Response

​
profile

Contains profile-level metadata returned by the scraper, such as uploader information and follower counts when available.

​
stats

Helps you understand what happened during the scrape:
  • videos_scanned: total TikTok entries iterated before filtering
  • videos_matched: entries that passed your filters
  • pages_consumed: estimated number of TikTok API pages fetched during the scrape

​
videos

This is the current page of matched TikTok videos. Each item includes public metadata such as:
  • id
  • title
  • description
  • timestamp
  • views
  • likes
  • comments
  • url

​
download_url

When present, this is a short-lived signed URL pointing to the full scrape result as one JSON file. It is useful for large profiles, browser downloads, and no-code integrations. If it is null, either:
  • the task has not finished yet, or
  • signed URL generation is not configured and you should paginate through videos instead

​
Error Cases

  • 400 invalid_cursor: the supplied cursor is invalid
  • 404 task_not_found: task does not exist, expired, or does not belong to the current user

​
Tips

  • poll every few seconds while task_status is processing
  • switch to download_url for large completed jobs
  • do not assume tasks live forever; they expire after about 1 hour
  • call the endpoint again later if you need a freshly minted download_url
  • use the expires_at value to avoid polling a task after it has already expired

Authorizations

​
X-API-Key
string
header
required

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Path Parameters

​
task_id
string
required

ID returned by POST /tiktok/profile.

Query Parameters

​
cursor
string

Opaque pagination cursor returned as next_cursor from the previous response. Omit to fetch the first page.

​
limit
integer
default:50

Maximum number of videos to include in the response.

Required range: 1 <= x <= 500

Response

Task found. task_status may be processing, completed, or failed.

​
status
enum<string>
Available options:
success
​
data
object

TikTok profile scrape task result body returned by GET /tiktok/profile/{task_id}.