# ViralityScorer IG (`edgeofcali/ig-virality-scorer`) Actor

ViralityScorer IG — high-performance Apify actor.

- **URL**: https://apify.com/edgeofcali/ig-virality-scorer.md
- **Developed by:** [Edward Martinez](https://apify.com/edgeofcali) (community)
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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

## 🚀 ViralityScorer IG — AI Virality Prediction Engine for Instagram

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-orange?logo=apify)](https://apify.com)
[![Instagram](https://img.shields.io/badge/Platform-Instagram-E1306C?logo=instagram)](https://instagram.com)
[![AI Powered](https://img.shields.io/badge/AI-Powered-blueviolet)](https://apify.com)
[![Node.js 20](https://img.shields.io/badge/Node.js-20%2B-green?logo=node.js)](https://nodejs.org)
[![ESM](https://img.shields.io/badge/Module-ESM-yellow)](https://nodejs.org/api/esm.html)

> **Predict whether your next Instagram post will go viral — before you hit publish.** ViralityScorer IG uses a multi-factor AI engine to analyze your caption, hashtags, content type, posting time, and account context to deliver a precise virality score (0–100) along with predicted engagement metrics and actionable optimization tips.

***

### 🎯 What Does It Do?

ViralityScorer IG reverse-engineers the Instagram algorithm by combining content analysis, temporal analysis, and account context scraping to generate a comprehensive **Viral Probability Score** and full engagement forecast for any upcoming post.

**Key capabilities:**

- 🔢 **Virality Score (0-100):** A weighted composite score across hashtag quality, caption engagement signals, content format, and posting time
- 📊 **Predicted Engagement:** Estimated likes, comments, shares, and total reach before you post
- 💪 **Strength/Weakness Analysis:** Understand exactly what's working and what's not
- 🛠️ **Actionable Improvements:** Specific, algorithm-informed suggestions to boost performance
- ⏰ **Best Time to Post:** Personalized timing recommendations based on your scheduled time
- 🤖 **AI Viral Prediction:** Natural-language summary of your post's viral potential

***

### 🏆 Use Cases

| Use Case | Who Benefits | Expected Outcome |
|---|---|---|
| Pre-publish content audit | Content creators | Optimize before posting for 2-5x more reach |
| Hashtag strategy testing | Social media managers | Identify best hashtag mix for discoverability |
| Posting schedule optimization | Brand marketers | Maximize engagement by timing posts correctly |
| A/B caption testing | Growth hackers | Compare multiple caption variations by score |
| Influencer campaign planning | Agencies & brands | Predict campaign ROI before launch |
| Reel vs. Photo decision | Individual creators | Choose content format with highest viral potential |
| Content calendar optimization | Marketing teams | Batch-analyze weeks of planned content |

***

### 📥 Input Fields

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `captionText` | String | No | `""` | 📝 The full caption text for your post |
| `hashtags` | Array | No | `[]` | #️⃣ Array of hashtags (with or without # prefix) |
| `contentType` | String | No | `"photo"` | 🎬 Content type: photo, reel, video, carousel, story, live, igtv |
| `scheduledTime` | String | No | Current time | ⏰ ISO 8601 datetime string for planned post time |
| `accountUsername` | String | No | `""` | 👤 Instagram username for account context scraping |

***

### 📤 Output Fields

| Field | Type | Description |
|---|---|---|
| `url` | String | Source URL analyzed |
| `scrapedAt` | String | ISO timestamp of analysis |
| `actorVersion` | String | Actor version |
| `aiInsight` | String | One-sentence AI insight about this post |
| `aiScore` | Number (0-10) | Overall quality/relevance score |
| `viralityScore` | Number (0-100) | Composite viral probability score |
| `predictedLikes` | Number | Estimated likes this post will receive |
| `predictedComments` | Number | Estimated comment count |
| `predictedReach` | Number | Estimated total reach (unique accounts) |
| `predictedShares` | Number | Estimated shares/saves |
| `strengthFactors` | Array | List of positive content signals |
| `weaknessFactors` | Array | List of areas needing improvement |
| `suggestedImprovements` | Array | Specific actionable recommendations |
| `bestTimeToPost` | String | Optimal posting time recommendation |
| `aiViralPrediction` | String | Full AI narrative viral probability assessment |

***

### 💡 Example Output

```json
{
  "url": "https://www.instagram.com/natgeo/",
  "scrapedAt": "2024-01-15T14:32:00.000Z",
  "actorVersion": "0.1.0",
  "aiInsight": "@natgeo's reel has a 82/100 virality score — projected 487,000 reach with strong algorithmic promotion potential.",
  "aiScore": 8.2,
  "viralityScore": 82,
  "predictedLikes": 34250,
  "predictedComments": 3920,
  "predictedReach": 487000,
  "predictedShares": 2450,
  "strengthFactors": [
    "Optimal hashtag count and mix",
    "Engaging caption with strong call-to-action",
    "High-performing content type: reel",
    "Posted at peak engagement time",
    "Using 15 targeted hashtags"
  ],
  "weaknessFactors": [
    "No major weaknesses detected"
  ],
  "suggestedImprovements": [
    "Great content plan! A/B test caption variations to optimize further",
    "Engage with 10-20 similar posts before and after publishing to boost initial visibility"
  ],
  "bestTimeToPost": "Your scheduled time is optimal. Keep it at Mon, 15 Jan 2024 12:00:00 GMT",
  "aiViralPrediction": "VIRAL PROBABILITY: HIGHLY LIKELY (Score: 82/100). Reels are currently Instagram's most promoted format. Your 15 hashtags provide good discoverability surface. Caption strength is solid with good length. Algorithm indicators suggest strong initial push from explore page."
}
```

***

### 🧠 How the AI Scoring Works

The virality score is computed using a **weighted multi-factor model**:

| Factor | Weight | What We Analyze |
|---|---|---|
| Caption Quality | 30% | Length, CTAs, emojis, questions, engagement triggers |
| Hashtag Strategy | 25% | Count, diversity, niche vs broad mix |
| Content Type | 25% | Format algorithmic priority (Reels > Carousels > Video > Photo) |
| Posting Timing | 20% | Hour of day, day of week vs. peak engagement windows |

All scores are normalized to 0-100 with slight variance simulation to reflect real-world unpredictability.

***

### 💰 Pricing

This actor is priced on a **pay-per-use compute unit model**:

- **Single analysis run:** ~0.05 compute units (~$0.02)
- **Bulk analysis (100 posts):** ~5 compute units (~$2.00)
- **With profile scraping:** ~0.1-0.2 compute units per run

Runs complete in **30-90 seconds** depending on whether profile/hashtag scraping is enabled.

***

### 🚀 Quick Start

```json
{
  "captionText": "Golden hour never gets old 🌅 Drop a ❤️ if you agree! Tag someone who needs to see this view. Save this for your next travel inspo!",
  "hashtags": ["travel", "goldenhour", "sunset", "travelphotography", "wanderlust", "landscapephotography", "nature", "travelgram", "explore", "adventure"],
  "contentType": "reel",
  "scheduledTime": "2024-06-15T18:00:00Z",
  "accountUsername": "natgeo"
}
```

***

### ⚠️ Important Notes

- Instagram may require authentication for profile scraping. The actor gracefully falls back to caption/hashtag-only analysis if profile data is unavailable.
- Results are predictions based on algorithmic signals — actual performance depends on follower quality, community engagement, and algorithm updates.
- For best results, provide all 5 input fields.

***

### 🔗 Related Actors

- Instagram Hashtag Scraper
- Instagram Profile Analyzer
- Instagram Post Extractor

# Actor input Schema

## `startUrls` (type: `array`):

List of URLs to start scraping from.

## `maxItems` (type: `integer`):

Maximum number of results to return.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://apify.com"
    }
  ],
  "maxItems": 50
}
```

# Actor output Schema

## `results` (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 = {
    "startUrls": [
        {
            "url": "https://apify.com"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("edgeofcali/ig-virality-scorer").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 = { "startUrls": [{ "url": "https://apify.com" }] }

# Run the Actor and wait for it to finish
run = client.actor("edgeofcali/ig-virality-scorer").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 '{
  "startUrls": [
    {
      "url": "https://apify.com"
    }
  ]
}' |
apify call edgeofcali/ig-virality-scorer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,edgeofcali/ig-virality-scorer"
        }
    }
}
```

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/V5yYSubVnYCTa6wF7/builds/WZRwwICK2fPY7hAyh/openapi.json