Use TikTok Keyword Search & Discovery Scraper with Python

Search TikTok by keyword or phrase and get matching videos with engagement stats, author profiles, music metadata, hashtags, and location tags, with optional discovery expansion for more results.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "enableExpansion": false,
  "excludeAds": false,
  "expansionSources": [
    "suggestions",
    "hashtags",
    "sounds"
  ],
  "includeHashtagMetadata": true,
  "maxExpansionQueriesPerSeed": 3,
  "maxResultsPerQuery": 3,
  "publishedWithin": "all",
  "queries": [
    "viral"
  ],
  "searchType": "videos",
  "sortBy": "relevance",
  "uniqueAuthors": false
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`searchType`	string	required	Videos: keyword video search. Photos: slideshow/photo search. Hashtags: hashtag metadata plus its top videos (uses the Hashtags field).
`queries`	array	optional	Keywords or phrases to search for (searchType=videos or photos). Each query is searched independently.
`hashtags`	array	optional	Hashtags to look up (searchType=hashtags). The # is optional, e.g. coffee or #coffee.
`maxResultsPerQuery`	integer	optional	Maximum posts to collect per query or hashtag, before filters. TikTok itself usually returns about 150-220 posts per query even when you ask for more. For hashtags, the metadata row is not counted against this limit.
`sortBy`	string	optional	Client-side sort applied after collecting results. TikTok's web search does not support server-side sorting, so this only reorders the posts TikTok returned.
`publishedWithin`	string	optional	Client-side filter that drops posts older than the selected window, based on each post's creation time. TikTok ranks results by relevance, not date, so a narrow window can return fewer posts than requested; the actor scans up to 5x the requested count (capped at 500) to fill it.
`minDurationSeconds`	integer	optional	Drop videos shorter than this. Leave blank for no minimum.
`maxDurationSeconds`	integer	optional	Drop videos longer than this. Leave blank for no maximum.
`excludeAds`	boolean	optional	Drop posts TikTok flags as paid advertisements.
`minLikeCount`	integer	optional	Drop posts with fewer likes than this. Leave blank for no minimum.
`minViewCount`	integer	optional	Drop posts with fewer plays/views than this. Leave blank for no minimum.
`uniqueAuthors`	boolean	optional	Keep at most one post per creator, so the results read like a creator shortlist. When a sort is selected, the top-ranked post from each creator is kept.
`maxPostsPerAuthor`	integer	optional	Optional cap on how many posts one creator may contribute. Ignored when One Post Per Author is on.
`enableExpansion`	boolean	optional	After each keyword search, run extra searches derived from its own results: related searches, its top hashtags and its most-reused sound. Increases run time and the number of posts found. Videos only.
`expansionSources`	array	optional	Which discovery sources to use when expansion is on. All three can be combined.
`maxExpansionQueriesPerSeed`	integer	optional	Maximum number of extra searches to run per keyword when expansion is on. Each one costs roughly as much run time as the original search.
`includeHashtagMetadata`	boolean	optional	For hashtag searches: emit a metadata row with the hashtag's post count, view count, description and images. Also attaches metadata to hashtag-expansion posts when expansion is on.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/82OM6joIyE5cLSohl/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

Questions before you run

Which inputs are required?

The published required fields are searchType

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build glvpB5jtOmv1fSco2 and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.