# TikTok Profiles - Followers, Likes & Bio Links (`kestrel/tiktok-profile-details`) Actor

Read public TikTok profiles by username or profile URL. One row per profile: followers, following, total likes, videos, bio, website and verified status. Filter followers, bio text or websites; skip saved IDs or hashes for repeat monitoring. Profile data only; no videos or follower lists.

- **URL**: https://apify.com/kestrel/tiktok-profile-details.md
- **Developed by:** [Tedj MEABIOU](https://apify.com/kestrel) (community)
- **Categories:** Business
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 profiles

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TikTok Profiles - Followers, Likes & Bio Links

TikTok Profiles provides structured followers and websites for research workflows. Read public TikTok profiles by username or profile URL. One row per profile: followers, following, total likes, videos, bio, website and verified status. Filter followers, bio text or websites; skip saved IDs or hashes for repeat monitoring. Profile data only; no videos or follower lists.

Creator research and brand-monitoring agents that already know the account handles and need current profile counters and bio links. This independent community Actor is maintained by kestrel and is not affiliated with or endorsed by the source platform. API use requires an Apify token. No source-site password, account cookies or additional paid API key is required.

### TikTok Profiles for AI agents: which input answers which request?

Public profile details only. Videos is a count, not video records. No video downloads, posts, comments, follower lists, historical growth or account access. Exact source stats are preferred; counts_approximate is true when a rounded source counter is used. Username matching protects against unrelated profiles. Missing source fields stay null. A source error is never fabricated into an empty successful result. Filtering selects from the provided targets or returned search records; it does not expand the underlying source coverage.

| Request | Input or action |
|---|---|
| First small sample | `{"usernames": ["tiktok", "duolingo"], "maxResults": 3, "maxSources": 2}` |
| Apply useful filters | `{"usernames": ["tiktok", "duolingo"], "maxResults": 3, "maxSources": 2, "minFollowers": 1000, "hasWebsite": "yes"}` |
| Keep only unseen identities | Supply prior dataset `id` values in `excludeIds`. |
| Keep new or changed observations | Supply prior `content_hash` values in `excludeContentHashes`; do not exclude their IDs too. |
| Repeat monitoring tomorrow | Save an Apify Task, schedule it and carry history in your own workflow. |
| Cap dollar spend | Set `maxTotalChargeUsd` in Apify run options, outside input JSON. |

### TikTok Profiles: how do I make the first call?

```json
{
  "usernames": [
    "tiktok",
    "duolingo"
  ],
  "maxResults": 3,
  "maxSources": 2
}
```

`maxResults` is a global paid-row cap across the whole run, after filters, deduplication and exclusions. Earlier targets can fill the cap and leave later targets unvisited. It is not a guarantee that enough matching records exist. Use separate runs if every target must receive an independent quota. `maxSources` caps attempted source targets, including unsuccessful attempts. A source is one profile, Page or company, or one App Store query/ID and country combination. Duplicate targets collapse before collection.

### TikTok Profiles: inputs, filters and limits

| Field | Meaning |
|---|---|
| `usernames` | Required public usernames or profile URLs, e.g. \["tiktok"] for TikTok or \["nasa"] for Instagram. Up to 100; duplicates collapse. Profiles only, without posts or follower lists. Each successfully checked profile has a source fee; matching delivered profiles also have a row fee. |
| `maxResults` | Maximum paid rows across the ENTIRE run after filters, deduplication and exclusions. Default 20; range 1–1000. Earlier targets can fill it. Set maxTotalChargeUsd in Apify run options for a dollar cap, not inside this input JSON. |
| `minFollowers` | Minimum profile/Page/company follower count, e.g. 1000. 0 disables. Missing values fail an active filter; source-rounded values remain approximate. Filters before maxResults. No extra filter fee; successfully checked sources are paid. |
| `verifiedOnly` | false (default) keeps all. true keeps only source-confirmed verified profiles/Pages; missing status fails this filter. Verification is the platform badge, not an independent identity check. Filters before maxResults; no extra filter fee. |
| `textContains` | Optional case-insensitive OR phrases, e.g. \["software", "education"]. Matches name, bio/description, industry or category when present. \[] disables. Applied before maxResults; skipped rows have no row fee, but successful source checks are paid. |
| `hasWebsite` | "any" (default) keeps all. "yes" keeps rows with a published website/bio link; "no" keeps rows without one. The link is not fetched or verified for reachability. App Store uses sellerUrl. Filters before maxResults; no filter fee, source checks remain paid. |
| `maxSources` | Maximum source targets attempted across the run, default 20; range 1–100. One profile/Page/company or one app query/ID and country is one source. Failed attempts count toward this limit but have no source fee. Valid empty/filtered sources are paid. No extra filter fee. |
| `excludeIds` | Prior dataset id values, e.g. \[] initially; up to 5,000. Skips identities even when they changed. App IDs include country, e.g. "310633997:DE". Excluded rows are free, source checks are paid. Keep history in your workflow; no automatic persistence. |
| `excludeContentHashes` | Prior content_hash values, e.g. \[] initially; up to 5,000 SHA-256 values. Skips unchanged observations but allows changed fields through. Time, query, position and image URL are excluded from the hash. Do not also exclude IDs when changes matter. Source checks remain paid; no stored history. |

Unknown input fields, unsupported URLs and invalid bounds fail before source requests. Missing numeric fields fail an active positive threshold. Text lists are case-insensitive OR filters; empty lists disable them. All optional filters are free to apply, but the successful checks needed to inspect source records are paid. A filter that leaves no rows does not imply a free run. Check the source-check counter as well as the delivered-row counter.

### What is in the output?

One dataset row is one **profile**. Main keys: `username, name, biography, followers, following, likes, videos, website, verified`. Every row includes `id`, `url`, `source_url`, `content_hash` and `fetched_at`. The example below is a minimized public-source observation; long descriptions are excerpts and current values can differ.

```json
{
  "id": "107955",
  "type": "profile",
  "platform": "tiktok",
  "username": "tiktok",
  "name": "TikTok",
  "url": "https://www.tiktok.com/@tiktok",
  "biography": "Your next discovery is waiting on TikTok.",
  "followers": 96663817,
  "following": 2,
  "likes": 467427369,
  "videos": 1515,
  "counts_approximate": false,
  "verified": true,
  "website": "https://tiktok.com/discovermore",
  "business_category": "Others",
  "language": "en",
  "image_url": null,
  "source_url": "https://www.tiktok.com/@tiktok",
  "content_hash": "fb564fd32f777a9d9b2053149f889f167fc556e11b1cf879776e22ad89d87aa3",
  "fetched_at": "2026-11-09T05:56:13.343071+00:00"
}
```

The key-value store's `SUMMARY` record gives attempted and checked sources, source requests, delivered/filtered/duplicate counts, charged events, per-target outcomes, errors and budget flags. Summary records are not paid dataset rows. A run with some useful sources and some failures reports partial success with errors in SUMMARY. When every attempted source fails, the run fails. A recognized empty App Store response is different from a blocked, redirected, private or unavailable source.

### What does it cost?

- **Source checked:** $0.002 per valid source ($2 per 1,000 checks).
- **Delivered profile:** $0.002 per row ($2 per 1,000 rows), in addition to source checks.
- No start fee. Proxy and compute are included in these event prices.

One checked source returning one row costs **$0.004**. A valid source with no matching rows costs **$0.002**. Invalid input, blocked responses and failed source requests have no source or row fee. Duplicate, filtered and excluded records have no row fee. Requests used for a bounded retry are included in a successful source's fee. For App Store search, one query/country with three delivered apps costs the source fee plus three app fees; ID lookup can return at most one app in a country.

A conservative maximum before a monetary cap is `min(number of targets, maxSources) × 0.002 + maxResults × 0.002`. App Store targets equal countries multiplied by the combined number of unique queries and app IDs. The Actor requires room for a source check plus at least one row before fetching another target. A cap below **$0.004** does no source work. It stops when billing fails or the platform's event-charge limit is reached. Charging and dataset writes are separate operations; a delivery interruption can leave a charged row unwritten, which SUMMARY records explicitly.

### How does repeat monitoring work?

Save IDs, hashes and observation times in your workflow. `excludeIds` suppresses an identity even when its content changed; use it only for unseen-identity collection. `excludeContentHashes` suppresses unchanged observations and keeps changed fields eligible. For change monitoring, avoid passing both the old ID and its hash, because the ID exclusion would also hide the update. A new hash is a signal to compare relevant fields, not proof of a specific follower, price or version change.

Hashes omit collection time, query, position, image URLs and selected display labels. The Actor does not retain a previous dataset, calculate growth rates, create schedules or emit deletion events. Save an Apify Task or use your own scheduler, carry forward up to 5,000 hashes and avoid overlapping jobs that overwrite the same workflow state. A missing row can result from filters, access errors, coverage limits or a spending cap; it does not by itself prove an account or app disappeared.

### How do I call it through the API or MCP?

Python (apify-client 3.x):

```python
from decimal import Decimal
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("kestrel/tiktok-profile-details").call(run_input={'usernames': ['tiktok', 'duolingo'], 'maxResults': 3, 'maxSources': 2}, max_total_charge_usd=Decimal("1"))
assert run is not None and run.status == "SUCCEEDED", run
rows = client.dataset(run.default_dataset_id).list_items().items
```

JavaScript:

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('kestrel/tiktok-profile-details').call(
  {"usernames": ["tiktok", "duolingo"], "maxResults": 3, "maxSources": 2}, { maxTotalChargeUsd: 1 }
);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

curl:

```bash
curl -X POST 'https://api.apify.com/v2/acts/kestrel~tiktok-profile-details/runs?maxTotalChargeUsd=1' \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"usernames": ["tiktok", "duolingo"], "maxResults": 3, "maxSources": 2}'
```

The same input works through n8n and Make. The asynchronous API returns a run record; wait for completion before reading the dataset and SUMMARY. MCP clients can discover `kestrel/tiktok-profile-details`, fetch its input schema and call it through Apify. Check the currently exposed tool schema for run options. If the MCP client lacks a monetary-cap option, use the Apify API for calls that require a dollar limit; do not invent an input named maxTotalChargeUsd.

### FAQ: why are there fewer rows than requested?

Check SUMMARY for filters, exclusions, duplicate IDs, source limits, failed requests and the spending cap. Increasing a result cap does not create more source records. Public access and layouts can change, and retries are bounded. The Actor never logs source-account credentials because none are supplied; source errors are summarized without proxy secrets. Returned website links are observations and are not fetched, so a URL can be stale or unavailable. JSON preserves nested lists; CSV or Excel export is available through Apify's dataset export. Respect source terms and applicable legal rights when using or sharing the observations.

Last verified working: 2026-11-09 (public-source probes; published builds also pass Apify cloud checks).

# Changelog

This Actor's version history is a separate document: https://apify.com/kestrel/tiktok-profile-details/changelog.md

# Actor input Schema

## `usernames` (type: `array`):

Required public usernames or profile URLs, e.g. \["tiktok"] for TikTok or \["nasa"] for Instagram. Up to 100; duplicates collapse. Profiles only, without posts or follower lists. Each successfully checked profile has a source fee; matching delivered profiles also have a row fee.

## `maxResults` (type: `integer`):

Maximum paid rows across the ENTIRE run after filters, deduplication and exclusions. Default 20; range 1–1000. Earlier targets can fill it. Set maxTotalChargeUsd in Apify run options for a dollar cap, not inside this input JSON.

## `minFollowers` (type: `integer`):

Minimum profile/Page/company follower count, e.g. 1000. 0 disables. Missing values fail an active filter; source-rounded values remain approximate. Filters before maxResults. No extra filter fee; successfully checked sources are paid.

## `verifiedOnly` (type: `boolean`):

false (default) keeps all. true keeps only source-confirmed verified profiles/Pages; missing status fails this filter. Verification is the platform badge, not an independent identity check. Filters before maxResults; no extra filter fee.

## `textContains` (type: `array`):

Optional case-insensitive OR phrases, e.g. \["software", "education"]. Matches name, bio/description, industry or category when present. \[] disables. Applied before maxResults; skipped rows have no row fee, but successful source checks are paid.

## `hasWebsite` (type: `string`):

"any" (default) keeps all. "yes" keeps rows with a published website/bio link; "no" keeps rows without one. The link is not fetched or verified for reachability. App Store uses sellerUrl. Filters before maxResults; no filter fee, source checks remain paid.

## `maxSources` (type: `integer`):

Maximum source targets attempted across the run, default 20; range 1–100. One profile/Page/company or one app query/ID and country is one source. Failed attempts count toward this limit but have no source fee. Valid empty/filtered sources are paid. No extra filter fee.

## `excludeIds` (type: `array`):

Prior dataset id values, e.g. \[] initially; up to 5,000. Skips identities even when they changed. App IDs include country, e.g. "310633997:DE". Excluded rows are free, source checks are paid. Keep history in your workflow; no automatic persistence.

## `excludeContentHashes` (type: `array`):

Prior content_hash values, e.g. \[] initially; up to 5,000 SHA-256 values. Skips unchanged observations but allows changed fields through. Time, query, position and image URL are excluded from the hash. Do not also exclude IDs when changes matter. Source checks remain paid; no stored history.

## Actor input object example

```json
{
  "usernames": [
    "tiktok",
    "duolingo"
  ],
  "maxResults": 3,
  "minFollowers": 0,
  "verifiedOnly": false,
  "textContains": [],
  "hasWebsite": "any",
  "maxSources": 20,
  "excludeIds": [],
  "excludeContentHashes": []
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "usernames": [
        "tiktok",
        "duolingo"
    ],
    "maxResults": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("kestrel/tiktok-profile-details").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "usernames": [
        "tiktok",
        "duolingo",
    ],
    "maxResults": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("kestrel/tiktok-profile-details").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "usernames": [
    "tiktok",
    "duolingo"
  ],
  "maxResults": 3
}' |
apify call kestrel/tiktok-profile-details --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kestrel/tiktok-profile-details"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/NgI505F6X8Is8bbpK/builds/vgyHfx753rchI0yPj/openapi.json
