# Instagram & TikTok Engagement Rate - Grade Any Creator List (`that_red_bird/creator-engagement-grader`) Actor

Paste any Instagram or TikTok scraper dataset and get each creator's engagement rate, an A-F grade against creators of the same size, and an estimated sponsored-post price. No login.

- **URL**: https://apify.com/that_red_bird/creator-engagement-grader.md
- **Developed by:** [mohamed alaya](https://apify.com/that_red_bird) (community)
- **Categories:** Social media, Marketing, Lead generation
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 creator gradeds

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

## Instagram & TikTok Engagement Rate - Grade Any Creator List

Give it the dataset of an Instagram or TikTok scraper and it works out each creator's engagement rate and grades it from 0 to 100 (A to F) against creators of the same size.
Made for influencer marketers, agencies and brands who have a list of creators and need to know who is worth paying.

No login, no cookies, no scraping: it only does the maths on data you already have.

### Quick start (3 copy-paste examples)

**1. See it work (empty input):** run with `{}`. You get a labelled demo list of 12 synthetic creators (free).

**2. Grade the output of a scraper:** run `apify/instagram-scraper` (profile details) or `clockworks/tiktok-scraper`, then pick its dataset in the "Creator dataset" field. In JSON:

```json
{ "datasetId": "YOUR_DATASET_ID", "platform": "auto" }
```

**3. Paste your own numbers (CSV or JSON):**

```json
{ "rows": "username,followers,likes,comments\n@alpha,12000,540,22\n@alpha,12000,610,30\nbeta,250000,2100,15", "includeCampaignReport": true }
```

Rows of the same username are combined, so one row per post works as well as one row per creator.

### Use it with (pipelines)

- `apify/instagram-scraper` (profiles, with latest posts) -> this Actor. It reads `username`, `followersCount`, `followsCount` and the `latestPosts[]` list (`likesCount`, `commentsCount`, `videoViewCount`).
- `clockworks/tiktok-scraper` (profile or hashtag videos) -> this Actor. It reads `authorMeta.name`, `authorMeta.fans` and each video's `diggCount`, `commentCount`, `shareCount`, `playCount`. Flattened column names such as `authorMeta.fans` work too.
- Any CSV export from a creator database: name the columns `username`, `followers`, `likes`, `comments`.

Instagram post-only datasets (for example the Instagram Post Scraper) usually have no follower count. Add a `followers` column or run the profile scraper as well; creators without followers come back as a `type: "error"` row and are not charged.

### Input guide

| Field | What it does |
|---|---|
| Creator dataset | The dataset of the scraper run (picker). |
| Or paste rows | JSON array, JSON lines or CSV/TSV. Ignored when a dataset is picked. |
| Platform | `auto` detects Instagram or TikTok per row. |
| Add a campaign report row | One summary row for the whole list (separately priced). |
| Your own benchmarks | Override the default median rates, e.g. `{"instagram":{"micro":2.5}}`. |
| Maximum creators | Safety cap, default 1000. |

### How the grade is calculated (transparent formula)

1. **Interactions per post** = likes + comments (+ shares on TikTok). Instagram posts with hidden likes (`-1`) are left out of the average.
2. **Engagement rate** = average interactions per post / followers x 100. The median post rate and, when views exist, the rate by views are shown next to it.
3. **Tier** by followers: nano under 10k, micro 10k-100k, mid 100k-500k, macro 500k-1M, mega over 1M.
4. **Benchmark** = a rule-of-thumb median rate for that platform and tier (Instagram 3.0 / 2.0 / 1.3 / 1.0 / 0.7 percent, TikTok 10 / 7 / 5 / 3.5 / 2.5 percent). `vsBenchmark` is your creator's rate divided by it.
5. **Benchmark score (0-100)** from that ratio: 0.5x = 30, 1x = 60, 1.5x = 78, 2x = 88, 3x = 96, 4x or more = 100.
6. **Percentile in list** = the share of other creators in your list with a lower ratio (needs 3 or more creators).
7. **Grade** = 75% benchmark score + 25% list percentile (100% benchmark score when the list has fewer than 3 creators). Letters: A 85+, B 70+, C 55+, D 40+, F below.

The benchmarks are rule-of-thumb medians in the range of public industry reports, not numbers measured by this Actor. Replace them with your own in the "benchmarks" field if you have better ones.

### Output

| Field | Meaning |
|---|---|
| `creator`, `platform`, `profileUrl` | Who and where. |
| `followers`, `following` | From the data. |
| `postsAnalyzed`, `postsHiddenLikes`, `confidence` | Sample size (high at 10+ posts, medium at 5-9, low below 5 or when only totals exist). |
| `avgLikes`, `avgComments`, `avgShares`, `avgViews` | Averages over the analysed posts. |
| `engagementRatePct`, `medianPostErPct`, `engagementByViewsPct` | The rates. |
| `tier`, `benchmarkPct`, `vsBenchmark` | The comparison. |
| `percentileInList`, `grade`, `letter`, `scoreParts` | The 0-100 grade and how it was made. |
| `estPostPriceUsdLow` / `High` | Very rough price range for one sponsored post (a rule of thumb scaled by size and engagement, not a quote). |
| `fakeEngagementHints` | Plain-text warnings, only for signals the data can show (see limits). |
| `basis` | `recent-posts`, `aggregate-fields` (avg columns) or `lifetime-average` (profile totals only, low confidence). |

The last row (`type: "campaign-report"`) holds the median rate, grade distribution, top and weakest creators and a total cost range.

Sample row:

```json
{ "type": "creator", "creator": "demo_fitness_anna", "platform": "instagram", "followers": 8200, "postsAnalyzed": 12,
  "avgLikes": 402, "avgComments": 26.9, "engagementRatePct": 5.23, "tier": "nano", "benchmarkPct": 3, "vsBenchmark": 1.74,
  "percentileInList": 91, "grade": 85, "letter": "A", "estPostPriceUsdLow": 150, "estPostPriceUsdHigh": 300,
  "fakeEngagementHints": [], "basis": "recent-posts", "confidence": "high" }
```

### Price

Pay per event: **$0.002 per creator graded** and **$0.01 for the optional campaign report**. Creators without enough data and the free demo are never charged.
Example: grading 500 creators with the campaign report = 500 x $0.002 + $0.01 = **$1.01**.

### FAQ

**Does it scrape Instagram or TikTok?** No. It only reads a dataset you already have, so there is no login, proxy or ban risk.

**Which fields does it understand?** Instagram scraper profile and post output, TikTok scraper video output, and generic columns (`username`, `followers`, `likes`, `comments`, `views`, `shares`). Field names are matched by name; if your scraper uses other names, rename the columns or paste a CSV.

**Is a high rate always good?** Not always. A rate far above the tier benchmark is shown as a hint to check for giveaways or engagement pods.

### Honest limits

- Fake-engagement hints are heuristics, not proof. They appear only when the data has the needed fields (comments vs likes, spread of likes over 6+ posts, following vs followers, rate far above or below the benchmark).
- The scraper's "latest posts" are a small sample (often 12). One viral post can move a small creator's average; `viralOutlierPosts` flags this.
- Benchmarks and price ranges are rules of thumb. Instagram saves and reach, and TikTok views-based rates, are not part of the grade.
- Tested here against generated data in the documented scraper shapes and pasted CSV; not yet run against a live scraper export.

# Actor input Schema

## `datasetId` (type: `string`):

Pick the dataset of an Instagram or TikTok scraper run, for example apify/instagram-scraper (profiles) or clockworks/tiktok-scraper (videos). Each creator is graded from the recent posts in the data. Leave empty to use pasted rows below, or to see the built-in demo.

## `rows` (type: `string`):

Paste a JSON array, JSON lines or CSV with one row per creator or per post. Useful columns: username, followers, likes, comments (optionally views, shares, platform). Rows of the same username are combined. Ignored when a dataset is picked above.

## `platform` (type: `string`):

Which platform the data comes from. 'auto' detects Instagram or TikTok per row from the field names. Choose one when your own columns do not reveal it.

## `includeCampaignReport` (type: `boolean`):

Add one summary row at the end: median engagement, grade distribution, top and weakest creators and a total estimated cost range for the whole list. This is a separately priced event.

## `benchmarks` (type: `object`):

Override the built-in median engagement rates (percent of followers) per platform and tier, for example {"instagram": {"micro": 2.5}}. Tiers: nano (under 10k), micro (10k-100k), mid (100k-500k), macro (500k-1M), mega (over 1M). Leave empty to use the defaults.

## `maxCreators` (type: `integer`):

Safety cap on how many creators are graded in one run.

## Actor input object example

```json
{
  "rows": "",
  "platform": "auto",
  "includeCampaignReport": true,
  "benchmarks": {},
  "maxCreators": 1000
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `downloadCsv` (type: `string`):

No description

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

No description

## `count` (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 = {
    "rows": "",
    "platform": "auto",
    "includeCampaignReport": true,
    "benchmarks": {},
    "maxCreators": 1000
};

// Run the Actor and wait for it to finish
const run = await client.actor("that_red_bird/creator-engagement-grader").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 = {
    "rows": "",
    "platform": "auto",
    "includeCampaignReport": True,
    "benchmarks": {},
    "maxCreators": 1000,
}

# Run the Actor and wait for it to finish
run = client.actor("that_red_bird/creator-engagement-grader").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 '{
  "rows": "",
  "platform": "auto",
  "includeCampaignReport": true,
  "benchmarks": {},
  "maxCreators": 1000
}' |
apify call that_red_bird/creator-engagement-grader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,that_red_bird/creator-engagement-grader"
        }
    }
}
```

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/T2hkVCRUilFza1fyg/builds/SkWNqTKc9qemjZ0oZ/openapi.json