Metadata-Version: 2.4
Name: tiktok-followers-scraper
Version: 0.1.0
Summary: Export TikTok followers and following lists to CSV from Python, no login (via the Apify actor).
Author: Atlan
License: MIT License
        
        Copyright (c) 2026 Atlan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://balticassets.eu/en/data/tiktok-followers-scraper/
Project-URL: Repository, https://github.com/Atlannn/tiktok-followers-scraper
Project-URL: Apify, https://apify.com/s_actors/tiktok-followers-scraper
Keywords: tiktok,tiktok-scraper,tiktok-followers,scraper,apify,csv,influencer-marketing,lead-generation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: apify-client>=1.8
Dynamic: license-file

# tiktok-followers-scraper

Export the followers and following list of any public TikTok profile to CSV from Python.

The scraping runs on Apify as the [TikTok Followers Scraper](https://apify.com/s_actors/tiktok-followers-scraper) actor
(no login, no cookies). This repo is a small client: it starts the actor with `apify-client`, waits for the run
and saves the rows to a CSV file.

Each row is one account: username, name, bio, email in bio, followers, likes, videos, verified badge and the
time of the follow. The CSV columns are taken from the actor output, so new fields appear automatically.

## Install

```bash
pip install -r requirements.txt
export APIFY_TOKEN=your_token      # Windows PowerShell: $env:APIFY_TOKEN="your_token"
```

Get a token in Apify Console → Settings → Integrations. A free Apify account works.

## Usage

```bash
# last 200 followers of two profiles
python tiktok_followers.py @nasa garyvee --max 200 -o output/followers.csv

# followers and following of one profile
python tiktok_followers.py @nasa --lists both

# influencers only: 10k+ followers, with an email in the bio
python tiktok_followers.py @nasa --min-followers 10000 --only-email

# accounts whose bio mentions coaching
python tiktok_followers.py @garyvee --keywords coach coaching
```

| Option | Meaning |
|---|---|
| `--lists` | `followers` (default), `following` or `both` |
| `--max` | accounts per list per profile, up to 10 000 (TikTok shows only the latest 10 000) |
| `--exact-time` | exact follow time per account, slower |
| `--min-followers` / `--max-followers` | filter by the account's own follower count |
| `--verified-only` | blue badge only |
| `--only-email` | only accounts with an email in the bio |
| `--keywords` | words in bio, name or username |
| `-o` | output CSV path |

## Use from your own code

```python
from apify_client import ApifyClient
import tiktok_followers as tf

client = ApifyClient("your_token")
rows = tf.fetch(client, {"profiles": ["@nasa"], "lists": "followers", "maxPerProfile": 50})
tf.write_csv(rows, "output/nasa.csv")
```

## Track new followers on a schedule

The actor can return only new followers and unfollows since the previous run (`onlyNew`, `detectUnfollows`).
Set that up as a scheduled task in Apify Console; see the
[actor page](https://apify.com/s_actors/tiktok-followers-scraper) for how it works.

## Sample output

A real run on 4 Nov 2026: `python tiktok_followers.py @nasa --max 5` returned 5 rows and 28 columns.
Usernames are masked here; the CSV you get has full values.

| list | position | username | nickname | bio | verified | followerCount | likeCount | videoCount |
|---|---|---|---|---|---|---|---|---|
| followers | 1 | sp\*\*\*\*\*\*\*ah | 💤 | | False | 22 | 9 | 7 |
| followers | 2 | jo\*\*\*\*\*\*\*43 | 💰 | The ultimate pursuit of truth | False | 19 | 5 | 1 |
| followers | 3 | mi\*\*\*\*\*\*\*cc | minh skibidi bell | | False | 54 | 37 | 3 |

All columns: `input`, `sourceUsername`, `sourceNickname`, `sourceUserId`, `sourceFollowerCount`,
`sourceFollowingCount`, `list`, `position`, `userId`, `username`, `nickname`, `profileUrl`, `bio`, `bioEmail`,
`verified`, `privateAccount`, `isSeller`, `followerCount`, `followingCount`, `likeCount`, `videoCount`,
`friendCount`, `avatarUrl`, `secUid`, `followedAt`, `followedAfter`, `followedBefore`, `scrapedAt`.

Without `--exact-time` each row carries a time window (`followedAfter` / `followedBefore`) instead of the exact
`followedAt`.

## What it is useful for

- **Influencer and lead lists**: followers of a competitor or niche account, filtered by follower count and
  email in the bio, as a CSV for outreach.
- **Audience analysis**: load the CSV into pandas or Google Sheets and look at follower sizes, verified share
  and bio keywords.
- **Competitor research**: the accounts a profile follows (`--lists following`).
- **Growth tracking**: schedule the actor to get only new followers and unfollows.

## FAQ

**Do I need to log in to TikTok?** No. The actor works on public profiles without a login or cookies.

**How many followers can I export?** Up to 10 000 per list per profile: TikTok shows only the latest 10 000
followers of an account to anyone.

**Does it work with private accounts?** No, only public ones.

**Where does my token go?** Nowhere but to Apify. The script reads `APIFY_TOKEN` from the environment and never
writes it to a file or to the CSV.

**Is it legal to use?** The data is public, but what you do with it, including emails from bios, is on you:
check GDPR and TikTok's terms before using it for outreach.

## Notes

- Only public accounts. Some accounts hide their following list.
- Pricing is set by the actor and shown on its Apify page; this repo adds nothing to it.
- More: [Baltic Assets, TikTok data tools](https://balticassets.eu/en/data/tiktok-followers-scraper/)

MIT licence.
