# Social Content Change & Opportunity Monitor (`theendfear/factory-social-content-change-opportunity-monitor-f6d26932`) Actor

Compare provided structured social/content snapshots and emit deterministic change and opportunity rows.

- **URL**: https://apify.com/theendfear/factory-social-content-change-opportunity-monitor-f6d26932.md
- **Developed by:** [Marco S.](https://apify.com/theendfear) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 analysis record emitteds

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

## Social Content Change & Opportunity Monitor

Compare provided structured snapshots and emit deterministic change and opportunity rows. This Actor performs no autonomous scraping and does not acquire data from websites by itself; it only processes records supplied by the user or by an authorized upstream dataset.

### What It Does

It joins current and prior snapshots by configurable identity fields, classifies added, removed, changed, unchanged, and stale entities, computes metric deltas, and emits explainable rows for items that should be reviewed.

### Who It Is For

Analysts, marketing operators, agencies, and data teams that already have structured public-data exports and need repeatable change detection instead of manual spreadsheet comparison.

### Input

Provide `currentRecords` and optional `priorRecords`. Configure `idFields`, `metricFields`, `timestampField`, `growthAlertPct`, and `staleDays` to match your data. If `priorRecords` is empty, the run emits first-snapshot rows without pretending a trend exists.

### Output

Each dataset row includes entity identity, change type, deterministic score, metric deltas, changed fields, timestamps, source indexes, and `ScoreExplanation`.

### Example

```json
{
  "priorRecords": [
    { "url": "https://example.test/a", "likes": 100, "capturedAt": "2026-09-01T00:00:00Z" }
  ],
  "currentRecords": [
    { "url": "https://example.test/a", "likes": 150, "capturedAt": "2026-09-10T00:00:00Z" }
  ],
  "idFields": ["url"],
  "metricFields": ["likes"],
  "growthAlertPct": 25
}
```

### How It Works

The algorithm normalizes identity values, removes duplicates by entity key, compares current and previous records, computes absolute and relative metric deltas, applies user-configurable thresholds, and ranks rows by score. Added and removed entities receive explicit classifications. Stale rows are based on timestamp age relative to the newest current timestamp in the run.

Priority and recommended action are derived from explicit score thresholds: score 70 or higher is treated as a high-priority review action, score 40-69 is a medium-priority review action, and lower scores are monitor-only unless the row is needed for added, removed, or stale reporting. Every score factor, action threshold, and rule trigger is included in `ScoreExplanation`.

### Pricing

PAY\_PER\_EVENT event `change_record_emitted` is charged once per emitted change row. Invalid rows, duplicates, empty comparisons, and rows skipped by charge limits are not billable.

### Limitations

This is a comparison and analysis Actor, not a data acquisition Actor. It does not verify whether an upstream dataset was collected correctly. Thresholds are configurable because useful alert sensitivity depends on the buyer workflow and dataset scale.

### Integration

Run it directly with JSON input, from an Apify task, or downstream from another Actor that already produces structured records. Results are written to the default dataset and the run summary is written to the `OUTPUT` key-value store record.

### Methodology

The executable spec generated by Agentic Implementation Planner V1 is stored with the Actor as `.actor/executable_product_spec.json`. The implementation follows that spec with deterministic tests for added, removed, changed, stale, duplicate, and malformed records.

# Actor input Schema

## `currentRecords` (type: `array`):

Current structured snapshot records supplied by the user or an authorized upstream dataset.

## `priorRecords` (type: `array`):

Previous structured snapshot records for comparison.

## `records` (type: `array`):

Fallback single-snapshot records; treated as current records when currentRecords is absent.

## `idFields` (type: `array`):

Ordered fields used to identify the same entity across snapshots.

## `metricFields` (type: `array`):

Numeric fields compared between snapshots.

## `timestampField` (type: `string`):

Record field containing the capture timestamp used for stale row detection.

## `staleDays` (type: `integer`):

Number of days after which a current record is marked as stale.

## `growthAlertPct` (type: `number`):

Relative metric change percentage that raises an opportunity alert.

## `maxRecords` (type: `integer`):

Maximum number of records to process from each snapshot.

## `emitUnchanged` (type: `boolean`):

Include unchanged entities in the dataset output.

## Actor input object example

```json
{
  "idFields": [
    "canonicalUrl",
    "url",
    "sourceUrl",
    "id",
    "handle",
    "title"
  ],
  "metricFields": [
    "likes",
    "comments",
    "shares",
    "views",
    "engagement",
    "followers"
  ],
  "timestampField": "capturedAt",
  "staleDays": 30,
  "growthAlertPct": 25,
  "maxRecords": 5000,
  "emitUnchanged": false
}
```

# Actor output Schema

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

Change and opportunity rows in the default dataset.

# 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("theendfear/factory-social-content-change-opportunity-monitor-f6d26932").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("theendfear/factory-social-content-change-opportunity-monitor-f6d26932").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 theendfear/factory-social-content-change-opportunity-monitor-f6d26932 --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,theendfear/factory-social-content-change-opportunity-monitor-f6d26932"
        }
    }
}

```

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/xW2QiGSGNYTBaUubB/builds/ggAeiXpeqArw2wKAS/openapi.json