# Creator Campaign Score & Audience Signal API (`8tp/creator-campaign-suitability-score-api`) Actor

Score supplied creator metrics for campaign shortlists with transparent reach, engagement, views, consistency, data quality, cohort ranks, and anomaly signals.

- **URL**: https://apify.com/8tp/creator-campaign-suitability-score-api.md
- **Developed by:** [Hunter M.](https://apify.com/8tp) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 creator row scoreds

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

![Creator Campaign Suitability & Audience Signal Score API](assets/actor-art.png)

Turn **supplied creator or influencer aggregate metrics** into transparent 0–100 campaign-shortlist scores, component scores, cohort ranks, percentiles, and anomaly screening signals. This Apify Actor is designed for influencer marketing, creator discovery, campaign planning, UGC shortlists, and agency workflows that already have authorized metrics.

It performs **no scraping**, makes no social-platform API request, uses no proxy or browser, and needs no login. It accepts no bio, caption, comment text, audience-member data, or arbitrary source object.

### What it answers

- How do supplied creators compare within this campaign cohort?
- Which rows have stronger reach, engagement, view, consistency, or data-quality evidence?
- Which metric combinations cross transparent anomaly thresholds and deserve human review?
- Which records are incomplete or based on very small samples?

The score describes only the supplied aggregate metrics. It is not a judgment of a person's worth, proof of audience authenticity, a fake-follower detector, a brand-safety decision, or a prediction of reach, conversion, revenue, or ROI.

### Input

Use inline `creators`, or select an Apify Dataset with `creator_dataset_id` (READ only). Each row uses this closed contract:

```json
{
  "creator_id": "campaign-row-17",
  "platform": "instagram",
  "followers": 42000,
  "average_likes": 1680,
  "average_comments": 84,
  "average_views": 31000,
  "posts_sampled": 24,
  "interaction_cv": 0.42,
  "view_cv": 0.55
}
```

`interaction_cv` and `view_cv` mean standard deviation divided by mean across the represented posts. Use one consistent collection scope and measurement method per cohort. The Actor does not authenticate caller-declared metrics or provenance.

`creator_id` is converted to a stable 24-character SHA-256 pseudonym using your private `id_namespace`. Raw creator IDs are hidden unless `include_creator_ids` is explicitly enabled. Use a campaign- or workspace-specific namespace to prevent easy cross-project joins.

### Output

Each `creator_score` row contains:

- `campaign_suitability_score` from 0 to 100;
- reach, engagement, view, consistency, and data-quality component scores;
- the observed engagement rate and view-to-follower ratio;
- deterministic cohort rank and percentile;
- a closed list of anomaly signals and data warnings;
- a stable privacy-minimized row ID.

A final free `cohort_summary` records analyzed, planned, delivered, omitted, and charged row counts; spending-limit status; mean score; source truncation; signal count; fixed weights; and mandatory limitations. The default Dataset starts with the exact billable creator-row prefix, followed by the summary.

### Exact scoring model

The Actor uses no ML model or hidden training data.

- **Reach (15%)**: log-scaled supplied followers; one million reaches the component ceiling.
- **Engagement (30%)**: saturating function of `(average_likes + average_comments) / followers`.
- **Views (20%)**: saturating function of `average_views / followers`.
- **Consistency (15%)**: inverse bounded mean of supplied interaction and view coefficients of variation.
- **Data quality (20%)**: documented-field completeness plus a sample-size component that reaches its ceiling at 20 posts.

When an optional component cannot be computed, its weight is redistributed across the available components. The output always exposes every component used. Cohort order is score-descending with the pseudonymous row ID as the deterministic tie-breaker; percentile is relative only to rows in the current run.

### Anomaly signals are not proof

The Actor emits a screening signal when supplied aggregates show:

- engagement rate at or above 20%;
- view-to-follower ratio at or above 5;
- at least 20 average comments and a comment-to-like ratio at or above 1;
- zero supplied views alongside positive supplied interactions.

These thresholds identify combinations worth checking. They do **not** establish manipulation, fake followers, fraud, or authenticity. `small_sample_warning` (fewer than five represented posts) and `incomplete_metrics_warning` are not counted as anomaly signals.

### Pricing

Pay per event: **$0.003 per `creator-row-scored`** plus Apify's **$0.00005 Actor start** event at the default 512 MB memory. The live Monetization panel says **User pays platform usage costs: No**, so normal run platform usage is included in these event prices; post-run Dataset access can still incur normal storage-operation charges under Apify's Store billing rules. Apify may scale start-event count when a caller increases memory. One successfully delivered `creator_score` Dataset row equals one paid unit. The free cohort summary is never a creator-row event. A spending limit produces an exact paid leading prefix and reports planned, delivered, omitted, and charged counts.

At the default 512 MB: 25 creators cost $0.07505; 100 cost $0.30005; 1,000 cost $3.00005, before any taxes or plan-specific charges shown by Apify.

### Good agent requests

- “Rank these supplied creator metrics for a campaign and explain each component.”
- “Score the creator rows in this Dataset without exposing raw creator IDs.”
- “Find extreme engagement or view-ratio signals in my authorized influencer shortlist.”
- “Compare this cohort using deterministic creator campaign scores.”

Do not choose this Actor when you need Instagram, TikTok, or YouTube scraping; comments or profile text; audience demographics; contact enrichment; authenticity certification; or automated decisions about people.

### Privacy and security

The Actor has limited permissions, reads only an explicitly selected Dataset, writes its run Dataset and KVS, and has no network collector. Source rows are bounded by row, per-row byte, and total-byte limits. Unknown row and input fields fail closed. No supplied metric or identifier is logged by application code.

Use only data you are authorized to process. Keep raw IDs hidden unless an operational join requires them. Share only synthetic, redacted reproductions in support requests.

### Benchmark and reproducibility

The repository includes an original CC0 synthetic 40-case benchmark with injected normal and anomaly conditions. Release checks require deterministic output, exact schemas, exact event accounting, anomaly-signal recall of at least 0.90, and no raw identifier leakage. Synthetic recall measures only the documented injected thresholds—not real-world follower authenticity.

# Actor input Schema

## `creator_dataset_id` (type: `string`):

Optional selected Apify Dataset containing rows in the documented aggregate-metrics contract. It takes precedence over inline creators.

## `creators` (type: `array`):

Aggregate metrics only; do not supply bios, captions, comments, audience-member data, contact data, or source objects.

## `id_namespace` (type: `string`):

Owner-chosen namespace mixed into stable pseudonymous row IDs. Use a campaign or workspace-specific value; it is never emitted.

## `include_creator_ids` (type: `boolean`):

Off by default for data minimization. Enable only when authorized workflows need the supplied identifier in output.

## `max_creator_rows` (type: `integer`):

Hard cap on selected Dataset rows read and scored. The 10,000-row ceiling keeps paid-event reconciliation bounded.

## `max_source_bytes` (type: `integer`):

Maximum compact-JSON bytes retained from the selected source before scoring stops.

## `max_source_row_bytes` (type: `integer`):

Reject a single oversized source row instead of partially interpreting it.

## `as_of` (type: `string`):

Optional timezone-aware ISO 8601 semantic timestamp. Omit for deterministic null output.

## Actor input object example

```json
{
  "creators": [
    {
      "creator_id": "sample-alpha",
      "platform": "instagram",
      "followers": 42000,
      "average_likes": 1680,
      "average_comments": 84,
      "average_views": 31000,
      "posts_sampled": 24,
      "interaction_cv": 0.42,
      "view_cv": 0.55
    },
    {
      "creator_id": "sample-bravo",
      "platform": "tiktok",
      "followers": 180000,
      "average_likes": 7200,
      "average_comments": 310,
      "average_views": 265000,
      "posts_sampled": 30,
      "interaction_cv": 0.78,
      "view_cv": 0.91
    },
    {
      "creator_id": "sample-charlie",
      "platform": "youtube",
      "followers": 85000,
      "average_likes": 3100,
      "average_comments": 240,
      "average_views": 52000,
      "posts_sampled": 18,
      "interaction_cv": 0.36,
      "view_cv": 0.48
    },
    {
      "creator_id": "sample-delta",
      "platform": "generic",
      "followers": 12000,
      "average_likes": 460,
      "average_comments": 22,
      "average_views": 8200,
      "posts_sampled": 12,
      "interaction_cv": 0.61,
      "view_cv": 0.74
    }
  ],
  "id_namespace": "private-campaign",
  "include_creator_ids": false,
  "max_creator_rows": 10000,
  "max_source_bytes": 16000000,
  "max_source_row_bytes": 100000
}
```

# Actor output Schema

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

Transparent campaign suitability subscores, cohort ranks and percentiles, data-quality evidence, and bounded anomaly signals.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("8tp/creator-campaign-suitability-score-api").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("8tp/creator-campaign-suitability-score-api").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 '{}' |
apify call 8tp/creator-campaign-suitability-score-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,8tp/creator-campaign-suitability-score-api"
        }
    }
}

```

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/OwNWjFS4RLwALoI1V/builds/ULglm5gywEgsD3wYT/openapi.json