TikTok: How to Verify That Search Monitoring Really Works

HTTP 200 does not guarantee that daily TikTok monitoring collected any videos. Search results may be located in aweme_list or search_item_list[].aweme_info; a script that reads only the first array can finish without an error and write an empty report. A reliable check separately confirms transport and application status, extracts both supported response structures, and records how many unique videos were extracted in that run.

What to diagnose

Imagine a task where a team collects public videos for several queries every morning to spot new posts about a product. An important outcome of this process is a reproducible list of records with descriptions, authors, publication dates, and available metrics. If the report suddenly comes back empty, the cause could be JSON handling, a changed set of results, previously seen videos appearing again, or an actual request failure. A single number—such as the length of aweme_list—cannot distinguish these cases.

The jsonscraper TikTok Scraper API’s /searchVideo endpoint accepts the required keyword parameter and additional parameters: count, cursor, date_posted, sort_by, and region. The endpoint documentation describes pagination using cursor; pass it as an opaque value from the previous response. The count parameter sets the desired number of results, not a guarantee of complete coverage of posts.

Separate the check into four signals

Useful diagnostics combine four independent checks. First, the HTTP request completed successfully. Second, the response’s outer status is ok, and the inner tiktok.status_code indicates success. Third, a tiktok object is present, and records are extracted from both documented response locations. Fourth, after deduplication, records with IDs suitable for storage remain. Log the number of extracted items before and after deduplication: the difference shows whether duplicates appeared during normalization.

Leave a missing field empty rather than substituting an invented value. For example, a particular record may not include a view count. Saving the original JSON alongside the normalized row makes it possible to check later whether information was lost during parsing or was absent from the original response.

A minimal request and normalization in Python

The jsonscraper specification defines the base URL https://tiktok.evelode.com and passing the key in the license_key query parameter. The example below uses documented parameters; the key is read from an environment variable and is not printed to the log. Install the dependency with python -m pip install requests, then set JSONSCRAPER_TIKTOK_LICENSE_KEY in the environment.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def extract_videos(payload):
    """Collect videos from both known search-response structures."""
    tiktok = payload.get("tiktok") or {}
    videos = []

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            videos.append(item)

    for item in tiktok.get("search_item_list") or []:
        if isinstance(item, dict):
            aweme = item.get("aweme_info")
            if isinstance(aweme, dict):
                videos.append(aweme)

    return videos


def main():
    params = {
        "license_key": KEY,
        "keyword": "example product query",
        "count": 20,
        "region": "US",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API returned an outer status other than ok")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("The response is missing the tiktok object")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("The inner status_code is not the successful value 0")

    raw_videos = extract_videos(payload)
    unique = {}
    for video in raw_videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique.setdefault(str(video_id), video)

    snapshot = {
        "collected_at": datetime.now(timezone.utc).isoformat(),
        "keyword": params["keyword"],
        "status": payload.get("status"),
        "status_code": tiktok.get("status_code"),
        "raw_items": len(raw_videos),
        "unique_items": len(unique),
        "has_more": tiktok.get("has_more"),
        "cursor": tiktok.get("cursor"),
        "videos": list(unique.values()),
    }

    Path("snapshots").mkdir(exist_ok=True)
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    Path(f"snapshots/{stamp}.json").write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    print({
        "status": snapshot["status"],
        "status_code": snapshot["status_code"],
        "raw_items": snapshot["raw_items"],
        "unique_items": snapshot["unique_items"],
        "has_more": snapshot["has_more"],
    })


if __name__ == "__main__":
    main()

The script checks the transport layer with raise_for_status(), then validates the outer status, the presence of the tiktok object, and the inner status_code. It then extracts records from both search structures, deduplicates them by aweme_id, and saves a snapshot with the collection time. If there are no suitable records, the file still contains run details, making it possible to distinguish a saved empty result from a missing report.

Turn snapshots into a team signal

Run the script on a schedule using cron, CI, or a workflow scheduler. Store separate snapshots for each query, or include the keyword in the filename. A status table only needs to record the run time, status, number of extracted and unique records, and the has_more flag. Send an alert when a request raises an exception, required parts of the response are missing, or the number of extracted records changes sharply compared with your own history.

This comparison detects a pipeline anomaly, but does not by itself explain the cause. A lower number of results may reflect the current result set rather than an API or parser failure. That is why it is useful to save the original JSON, compare identical parameters, and check the IDs found. Choose an alert threshold based on observations for your own query, not a universal number.

For pagination, use the cursor from the response and stop when the API indicates there are no more results. Save the cursors and request parameters used so a run can be reproduced. The date_posted and sort_by parameters let you set a time filter and sort order; if the task requires repeatable comparisons, keep them fixed between runs.

How to interpret the result

Once this is in place, the team has a verifiable answer to three practical questions: did the request succeed, where are the results in the JSON, and how many unique videos made it into the saved snapshot? This shortens the path from an empty table to a diagnosis: first check statuses and structure, then parameters, duplicates, and the contents of the original response.

The response schema and available fields may differ between records. In a jsonscraper live check on October 25, 2026, a search returned fields for IDs, descriptions, authors, and statistics; values for an individual record should be treated as optional. A working report stores the data actually received and does not replace missing values with zeroes.

You can start with the TikTok Scraper API page and check exact endpoints and parameters in the official API documentation. This check is useful before launching monitoring: the report becomes an observable result whose quality can be diagnosed.