TikTok Video Metadata Scraper 🎥

Extracts clean, structured metadata from TikTok video URLs — including title, description, duration, author, engagement stats, and more.

---

✅ Summary

This Actor scrapes TikTok video pages and outputs normalized JSON data for analytics, automation, or archiving.

---

📌 Use cases

• Social media analytics dashboards
• Monitoring competitor or influencer content
• Researching TikTok engagement trends
• Feeding structured video data into ML/AI pipelines

---

🚀 Quick Start (Apify Console)

1. Open the Actor in Apify Console.
2. Paste one or more TikTok video URLs into the Input field as startUrls.
3. Click Run — the Actor will fetch video metadata and save results into the default Dataset.

Example input:

{
  "startUrls": [
    {"url": "https://www.tiktok.com/@orcaocean3/video/7534292343000730893"},
    {"url": "https://www.tiktok.com/@example/video/987654321"}
  ]
}

---

🖥️ Quick Start (CLI)

$apify run -p input.json

Where input.json contains the example above.

---

🐍 Quick Start (apify-client, Python)

from apify_client import ApifyClient

client = ApifyClient('<APIFY_TOKEN>')

run = client.actor("<USERNAME>/<ACTOR-NAME>").call(
    run_input={
        "startUrls": [
            {"url": "https://www.tiktok.com/@orcaocean3/video/7534292343000730893"}
        ]
    }
)

# Fetch results
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

---

📥 Inputs

• startUrls (array of objects or strings) — TikTok video URLs to scrape.

  • Each entry can be { "url": "..." } or just a string URL.
  • At least one is required.

---

⚙️ Configuration

Name	Type	Required	Default	Example value	Description
startUrls	Array	Yes	None	[ {"url": "https://www.tiktok.com/@user/video/123"} ]	List of TikTok video URLs to scrape.
ALL_RESULTS	Key-Value Store	No	N/A	JSON array	Consolidated results of all scraped videos.
defaultDatasetId	Dataset	Always	Auto	—	Each video’s metadata is stored as one item.
APIFY_TOKEN	Env var	Yes (API/CLI)	—	<APIFY_TOKEN>	Required when running via API/CLI.

➡️ Example in Console: paste startUrls into the JSON input editor. In CLI, provide APIFY_TOKEN as an environment variable.

---

📤 Outputs

• Dataset — Each TikTok video is stored as a dataset item.
• Key-Value Store — ALL_RESULTS contains the full array of scraped results.

Example dataset item:

{
  "id": "7534292343000730893",
  "url": "https://www.tiktok.com/@orcaocean3/video/7534292343000730893",
  "title": "Orca show at Tenerife 🐋",
  "description": "A beautiful orca performance at Loro Parque",
  "duration_seconds": 30,
  "duration": "30s",
  "videoUrl": "https://.../video.mp4",
  "cover": "https://.../cover.jpg",
  "playCount": "1.2k",
  "shareCount": "34",
  "likeCount": "502",
  "commentCount": "27",
  "author": {
    "uniqueId": "orcaocean3",
    "nickname": "tenerife_loroparque_orcaocean",
    "avatarThumb": "https://.../avatar.jpg",
    "verified": false
  },
  "fetched_at": "2025-09-15T22:10:00Z"
}

---

🔑 Environment variables

• APIFY_TOKEN — Required for CLI and API runs.

---

▶️ How to Run

Console

1. Go to Actor > Input.
2. Paste TikTok URLs.
3. Run and view results in Dataset.

CLI

$APIFY_TOKEN=<APIFY_TOKEN> apify call <USERNAME>/<ACTOR-NAME> -p input.json

API (Python) — see snippet above.

---

⏱ Scheduling & 🔔 Webhooks

• In Console, use Schedules to run regularly.
• Add Webhooks to receive a callback after each run completes.

---

🐞 Logs & Troubleshooting

• "No TikTok URLs provided" → ensure startUrls is included.
• "No video data found" → URL may not be a valid TikTok video.
• Network timeouts → retry run or schedule with delay.

---

🔒 Permissions & Storage

• Requires Dataset + Key-Value Store access.
• Needs valid APIFY_TOKEN for CLI/API runs.

---

📝 Changelog / Versioning tip

Maintain version notes in Apify Console > Actor > Versions for transparency.

---

🗒️ Notes / TODOs

• TODO: Confirm if Actor should also handle TikTok profile URLs (currently only video pages are supported).
• TODO: Verify maximum number of URLs per run (depends on platform limits).

---

📚 References

• Apify Docs: Actors
• Apify Docs: Storage
• Apify Docs: Schedules & Webhooks

---

🔍 What I inferred from main.py

• Actor expects startUrls input key (array or dict).
• Each video scraped is pushed to the dataset and also consolidated into ALL_RESULTS in Key-Value Store.
• No explicit authentication or extra params — only TikTok URLs required.
• Assumed that profile URLs are not supported (marked TODO).