TikTok Hashtag Scraper

Extract TikTok video URLs by hashtag and download original quality videos without watermarks

What does this actor do?

This Apify actor searches TikTok by hashtag and extracts video URLs from hashtag pages. It can download the actual video files in their original quality (without TikTok watermarks) or just collect comprehensive metadata. Videos are stored in the key-value store with direct download links provided in the dataset.

Features

• 🔍 Hashtag Search: Find videos by any TikTok hashtag
• 📥 Original Quality Downloads: Download videos in their original quality without TikTok watermarks
• 📊 Metadata Extraction: Collect comprehensive video information
• 🔒 Authentication Support: Use cookies for restricted content
• ⚡ Proxy Support: Built-in proxy rotation for reliable scraping
• 🎯 Quality Selection: Choose from best, 720p, 1080p, or audio-only
• 📈 Batch Processing: Download multiple videos from hashtag results

Input

Parameter	Type	Required	Description
queryInput	string	Required	Hashtag to search for (without # symbol, e.g., "fyp", "viral", "dancing")
maxVideos	integer	Optional	Maximum number of videos to process (1-100). Default: 10
downloadMode	string	Optional	Choose download mode. Options: videos (download original videos without watermarks) or metadata_only (metadata only). Default: videos
quality	string	Optional	Video quality preference. Options: best, 720p, 1080p, audio_only. Default: best
useProxy	boolean	Optional	Enable proxy for scraping. Default: true
maxDownloadSpeed	integer	Optional	Maximum download speed in KB/s (0 = unlimited). Default: 0
cookies	string	Optional	TikTok cookies for authentication (JSON or Netscape format)
proxyConfiguration	object	Optional	Custom proxy configuration

Usage

Basic Hashtag Search

To scrape videos from a hashtag, simply provide the hashtag name:

{
  "queryInput": "fyp"
}

Advanced Configuration

For more control over the scraping process:

{
  "queryInput": "cooking",
  "maxVideos": 25,
  "downloadMode": "videos",
  "quality": "720p",
  "useProxy": true,
  "maxDownloadSpeed": 500
}

Metadata Only Mode

To collect video information without downloading files (useful for getting URLs to original videos without watermarks):

{
  "queryInput": "travel",
  "downloadMode": "metadata_only",
  "maxVideos": 50
}

With Authentication

For accessing restricted or region-locked content:

{
  "queryInput": "private_hashtag",
  "cookies": "{\"name\": \"sessionid\", \"value\": \"your_session_id\", \"domain\": \".tiktok.com\"}",
  "useProxy": true
}

How it works

1. Hashtag Search: The actor navigates to https://www.tiktok.com/tag/{hashtag}
2. Content Discovery: Uses advanced scraping techniques to find video URLs
3. Video Processing: Downloads original quality videos (without TikTok watermarks) or extracts metadata as requested
4. Storage: Saves videos to key-value store with download URLs
5. Results: Outputs comprehensive dataset with all collected information

Output

The actor returns a dataset containing metadata for each processed video. When downloading videos, additional fields are included.

Sample Output

[
  {
    "video_id": "7123456789012345678",
    "title": "Amazing cooking tutorial #fyp #cooking",
    "author": "chef_master",
    "url": "https://www.tiktok.com/@chef_master/video/7123456789012345678",
    "download_url": "https://api.apify.com/v2/key-value-stores/abc123/records/7123456789012345678.mp4",
    "file_size": 15432000,
    "file_extension": "mp4",
    "quality_requested": "best",
    "downloaded_format": "h264",
    "duration": 45,
    "view_count": 2500000,
    "like_count": 150000,
    "publish_date": "2024-03-15",
    "description": "Quick and easy pasta recipe! 🍝 #pasta #recipe #cooking",
    "thumbnail": "https://p16-sign-va.tiktokcdn.com/...",
    "collected_at": "2024-03-20T10:30:00Z"
  }
]

Output Schema

Field	Type	Description
video_id	string	Unique TikTok video identifier
title	string	Video title/caption
author	string	Creator username
url	string	Original TikTok video URL
download_url	string	Direct download link (when videos are downloaded)
file_size	integer	File size in bytes (when downloaded)
file_extension	string	File format (mp4, webm, etc.)
quality_requested	string	Quality setting used
downloaded_format	string	Actual format downloaded
duration	integer	Video duration in seconds
view_count	integer	Number of views
like_count	integer	Number of likes
publish_date	string	Upload date (YYYY-MM-DD)
description	string	Full video description
thumbnail	string	Thumbnail image URL
collected_at	string	ISO timestamp of collection

Tips and best practices

Choosing Hashtags

• Start with popular hashtags like "fyp", "viral", "trending"
• Use specific niche hashtags for targeted content
• Test with small maxVideos count first

Performance Optimization

• Disable proxy for faster downloads when not needed
• Use metadata-only mode for quick data collection
• Set download speed limits to prevent hanging on slow connections
• Batch processing with reasonable video counts

Authentication

• Export cookies from a logged-in TikTok session
• Use JSON format for multiple cookies
• Required for private accounts or geo-restricted content

Troubleshooting

"No videos found for hashtag"

Possible causes:

• Hashtag doesn't exist or has no public videos
• Content requires authentication
• TikTok rate limiting or geographic restrictions

Solutions:

1. Try a different, more popular hashtag
2. Provide TikTok cookies for authentication
3. Enable proxy settings
4. Reduce maxVideos parameter

"Download failed" errors

Possible causes:

• Video is private, deleted, or region-locked
• Network connectivity issues
• TikTok anti-bot measures

Solutions:

1. Check if video is still available on TikTok
2. Use proxy configuration
3. Add authentication cookies
4. Reduce concurrent downloads

Note: Downloads are of original videos without TikTok watermarks, so some videos may not be available if they have specific licensing restrictions.

Slow performance

Solutions:

1. Set useProxy: false for direct connections
2. Configure maxDownloadSpeed to prevent timeouts
3. Use metadata_only mode for faster data collection
4. Reduce maxVideos for quicker results

Authentication issues

How to get TikTok cookies:

1. Open TikTok in your web browser and log in
2. Open Developer Tools (F12)
3. Go to Application/Storage → Cookies → https://www.tiktok.com
4. Copy cookies in JSON format or export as Netscape format
5. Paste into the cookies input field

Resources

• Apify Platform Documentation
• Apify Actor Development
• TikTok Developer Documentation

Support

For issues or questions:

• Check the Apify Community Forum
• Review Apify Status for platform issues
• Create an issue in the actor's repository