---

README.md

🌟 TikTok User Info Fetcher — Fast profile insights & safe exports

📖 Summary

A production-ready Apify Actor that fetches public TikTok user profile summary data and metrics (followers, posts, bio, avatar) from a trusted third‑party endpoint — plug-and-play on Apify Console, privacy-conscious, and built for reliable batch runs.

---

💡 Use cases / When to use

• Bulk-collect TikTok profile summaries for research, monitoring, or analytics
• Enrich internal databases with follower counts, usernames, and avatars
• Build lightweight lists for outreach, verification, or compliance checks
• Quick audits of account metadata without full video scraping

---

⚡ Quick Start (Console — one-click)

1. Open this Actor in the Apify Console.
2. Paste a JSON input (see input.example.json) into the Console Input field.
3. Click Run Actor — the Actor will fetch each username and push results to the Dataset and the OUTPUT key-value store.

Designed for speed and safe data collection — runs in seconds for single profiles and scales with concurrency.

---

⚙️ Quick Start (CLI + API)

CLI (apify-cli)

$apify run --input input.example.json

Python (apify-client) — minimal example

from apify_client import ApifyClient

client = ApifyClient('<APIFY_TOKEN>')
run = client.actor('<ACTOR_ID>').call(run_input={
    "usernames": ["example_user1", "example_user2"],
    "concurrency": 2
})
print('Run finished, dataset available at:', run['defaultDatasetId'])

Replace <APIFY_TOKEN> and <ACTOR_ID> with your values.

---

📝 Inputs (fields & schema)

This Actor accepts a flexible input schema that supports a single username, a list, or pasted multi-line values.

Key fields:

• usernames / username / user_value — required (one or more): username strings, full profile URLs, or comma/newline-separated values.
• concurrency — optional: how many usernames to fetch in parallel. Default: 2 (min 1).
• timeout_seconds — optional: request timeout for external API calls (default reasonable value used by Actor).

Console JSON input example

{
  "usernames": [
    "farhanahmedprottoy_09",
    "example_user2"
  ],
  "concurrency": 2
}

---

⚙️ Configuration

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
usernames	array	✅ Yes	None	["user1","user2"]	Accepts single username, URL, or comma/newline-separated string.
concurrency	integer	⚙️ Optional	2	4	Parallel fetches; increase for batch runs but watch rate limits.
timeout	integer	⚙️ Optional	30	60	Per-request timeout for external calls (seconds).

---

📄 Outputs (Dataset / KV examples)

One dataset item is pushed per requested username. All run results are available under the OUTPUT key-value store.

Example Dataset item

{
  "_requested_username": "example_user",
  "user_name": "example_user",
  "full_name": "Example Name",
  "profile_pic_url": "https://.../avatar.jpg",
  "profile_pic_url_hd": "https://.../avatar_hd.jpg",
  "biography": "Short bio...",
  "followers_exact": 12345,
  "followers_short": "12.3K",
  "following_exact": 100,
  "following_short": "100",
  "posts": 42,
  "heart": 123456,
  "_http_status": 200
}

---

🔑 Environment Variables

• APIFY_TOKEN — required for CLI / API runs. Use Console secrets or CI secrets.
• APIFY_RUN_ID — provided by Apify Console (read-only).
• HTTP_PROXY / HTTPS_PROXY — optional when using custom proxies (see Proxy Configuration).

Placeholders used in examples: <APIFY_TOKEN>, <PROXY_USER:PASS@HOST:PORT>

---

▶️ How to Run (Console, CLI, API)

Console

• Paste the JSON input and click Run Actor.

CLI

$apify run --input input.example.json

API

Use apify-client (example above) to call the Actor programmatically. Results are stored in the Dataset and OUTPUT KV on completion.

---

⏰ Scheduling & Webhooks

• Use the Apify Console scheduler to run on cron schedules for regular monitoring.
• Add a Webhook to receive run:finished events and trigger downstream workflows (notifications, ETL, or storage transfer).

---

🕾️ Logs & Troubleshooting

• Console logs stream live while the run executes.
• Common issues: malformed usernames, network timeouts, or API rate-limits from the upstream service.
• If an item contains an _error or non-200 _http_status, check the raw preview fields in the dataset row and retry with the same input.

---

🔒 Permissions & Storage Notes

• The Actor does not log secrets. Provide any secrets via Console secrets only.
• Dataset rows may contain publicly available profile metadata. Respect platform terms when storing or sharing collected data.

---

🔟 Changelog / Versioning

• v1.0 — Initial release: username extraction, external API fetch, flexible input parsing, transformation to consistent output schema, and Dataset/KV export.

---

🖌 Notes / TODOs

• TODO: Confirm preferred default request timeout and expose it in the input schema if desired.
• TODO: Add optional rate-limit/backoff policy controls for large batches.

---

🌍 Proxy Configuration

This Actor performs outbound requests to a third‑party endpoint. Use Apify Proxy or your own proxy to mitigate geo or network restrictions.

Quick enable (Console): Toggle Use Apify Proxy in the Run form or set HTTP_PROXY / HTTPS_PROXY environment variables.

Custom proxy example

export HTTP_PROXY="http://<PROXY_USER:PASS@HOST:PORT>"
export HTTPS_PROXY="http://<PROXY_USER:PASS@HOST:PORT>"

Security note: Store proxy credentials as Console secrets — never paste them as plaintext in public inputs or logs.

Advanced: TODO: Consider proxy rotation and backoff strategies for high-volume runs.

---

📚 References

• Apify Actor README best practices — (official Apify Console docs)
• Apify input/output schema docs — (official Apify docs)
• Apify CLI & apify-client usage — (official Apify docs)

---

🤔 What I inferred from main.py

• Input parsing is flexible: accepts single usernames, arrays, comma or newline-separated lists, or prefill values from actor.json.
• The Actor sends requests to a third‑party endpoint and normalizes various possible response shapes into a consistent profile record.
• Results are pushed to the Dataset and saved to an OUTPUT file (data_result.json) in the run workspace.
• Concurrency is supported and can be tuned via the concurrency input.

---

input.example.json

{
  "usernames": [
    "farhanahmedprottoy_09",
    "example_user2"
  ],
  "concurrency": 2
}

CONFIG.md

CONFIG.md — Quick deploy notes

• Set your APIFY_TOKEN in your environment or Console secrets before using the CLI or API.
• If you depend on an external third-party endpoint, verify its Terms of Service before batch usage.
• Consider adding a run-level backoff if you expect large batches to avoid upstream rate limits.

---