# Meta Ads Intelligence Analyzer (`karneboros_sed/meta-ads-intelligence-analyzer`) Actor Analyze supplied Meta/Facebook Ads Library-style ad records into buyer-ready competitor intelligence without scraping Meta directly. - **URL**: https://apify.com/karneboros\_sed/meta-ads-intelligence-analyzer.md - **Developed by:** [Ac Co](https://apify.com/karneboros_sed) (community) - **Categories:** Social media, Lead generation, Automation - **Stats:** 2 total users, 1 monthly users, 100.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/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## Meta Ads Intelligence Analyzer Turn supplied Meta/Facebook Ads Library-style records into buyer-ready competitor intelligence for agencies, e-commerce teams, and local-business marketers. This Apify Actor does **not** scrape Meta directly in v1. Instead, it analyzes ad records you already have from compliant exports, datasets, or internal workflows and returns structured insights on hooks, offer angles, CTAs, competitor positioning, and practical recommendations. ### Why buyers use it Marketing teams do not just need raw ad rows. They need to know what competitors are saying, what offers are repeated, what CTAs dominate, and where there is whitespace for a stronger campaign. Use this Actor to: - Audit competitor ad messaging before launching a campaign. - Build client-ready creative intelligence reports. - Extract offer angles, hooks, CTAs, pain points, value props, and positioning. - Compare advertisers inside a market or local service category. - Create repeatable weekly competitor watch reports without using private cookies or brittle scraping. ### Input The Actor accepts inline ad records or a local JSON file. ```json { "ads": [ { "id": "ad-1001", "pageName": "Peak Protein Co.", "primaryText": "Tired of expensive protein that tastes chalky? Save 20% on our bestselling whey bundles today only.", "headline": "20% off protein bundles", "cta": "SHOP_NOW", "linkUrl": "https://example.com/protein-bundle", "publisherPlatforms": ["facebook", "instagram"] } ], "inputFile": "", "brandName": "FitFuel Competitor Set", "industry": "E-commerce supplements", "reportMode": "both", "includeRecommendations": true } ```` Supported top-level fields: - `ads`: Array of Meta/Facebook Ads Library-style records. - `inputFile`: Local JSON path containing either an array of ads or an object with `ads`. - `brandName`: Brand, market, or competitor set name for the report. - `industry`: Industry context used for deterministic recommendations. - `reportMode`: `summary`, `per_ad`, or `both`. - `includeRecommendations`: Include practical recommendations when `true`. Ad records can use flexible field names such as `text`, `body`, `primaryText`, `headline`, `title`, `pageName`, `advertiserName`, `cta`, `callToAction`, `linkUrl`, `landingPageUrl`, `publisherPlatform`, `impressions`, `spend`, and common `snapshot` fields. ### Output Each run emits one JSON report to the default dataset path or the requested local `--output` path. The output always includes: - `analyzedAds` - `summary` - `topHooks` - `offerAngles` - `ctaPatterns` - `competitorPositioning` - `recommendations` - `monetizationNotes` See [samples/sample-output.json](samples/sample-output.json) for a full example. ### Local development ```bash npm install npm run build npm test npm run sample ``` The sample command runs without an Apify token and writes `samples/sample-run-output.json`. You can also run directly: ```bash npm run build node dist/src/index.js --input samples/sample-input.json --output /tmp/meta-ads-report.json ``` If no input is provided, the Actor falls back to `samples/sample-input.json` for local development. ### Apify behavior The repository follows Apify Actor conventions: - `.actor/actor.json` - `.actor/input_schema.json` - `Dockerfile` - dataset-style JSON output In Apify-style local storage, the Actor checks: ```text storage/key_value_stores/default/INPUT.json ``` and writes: ```text storage/datasets/default/000000001.json ``` No API keys, private cookies, or Meta credentials are used. ### Analysis approach The MVP uses deterministic local analysis rather than an LLM. This keeps it fast, explainable, cheap to run, and safe for a paid Store MVP. Current extraction/classification includes: - Hook patterns: discount, urgency, social proof, local relevance, convenience, lead magnets, premium aspiration, and more. - Offer angles: percentage discount, bundle, free shipping, financing, trial, guarantee, quote, limited-time offer, outcome promise, launch. - CTA patterns: shop, learn more, book, sign up, quote, download, message, call, apply. - Positioning: price-led value, premium quality, speed/convenience, trust/proof, local specialist, outcome-led performance. - Per-ad recommendations and aggregate market recommendations. ### Store positioning **Meta Ads Intelligence Analyzer** is positioned as a lightweight paid intelligence Actor, not a commodity scraper. Buyers bring ad records; the Actor turns them into monetizable strategy artifacts they can use in client reports, campaign planning, and competitor monitoring. # Actor input Schema ## `ads` (type: `array`): Inline Meta/Facebook Ads Library-style records. Each record can include text/body/headline/title, pageName/advertiserName, CTA, URL, spend, impressions, dates, and platform fields. ## `inputFile` (type: `string`): Optional local JSON file path containing either an array of ads or an object with an ads array. Useful for local runs and Apify file-based workflows. ## `brandName` (type: `string`): The brand, market, or competitor set being analyzed. ## `industry` (type: `string`): Industry context used to tune deterministic recommendations. ## `reportMode` (type: `string`): Choose whether to return per-ad analysis, summary intelligence, or both. ## `includeRecommendations` (type: `boolean`): Include practical media, creative, and offer recommendations. ## Actor input object example ```json { "ads": [], "brandName": "Competitor Set", "industry": "E-commerce", "reportMode": "both", "includeRecommendations": true } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "ads": [], "inputFile": "", "brandName": "Competitor Set", "industry": "E-commerce" }; // Run the Actor and wait for it to finish const run = await client.actor("karneboros_sed/meta-ads-intelligence-analyzer").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "ads": [], "inputFile": "", "brandName": "Competitor Set", "industry": "E-commerce", } # Run the Actor and wait for it to finish run = client.actor("karneboros_sed/meta-ads-intelligence-analyzer").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "ads": [], "inputFile": "", "brandName": "Competitor Set", "industry": "E-commerce" }' | apify call karneboros_sed/meta-ads-intelligence-analyzer --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=karneboros_sed/meta-ads-intelligence-analyzer", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Meta Ads Intelligence Analyzer", "description": "Analyze supplied Meta/Facebook Ads Library-style ad records into buyer-ready competitor intelligence without scraping Meta directly.", "version": "0.1", "x-build-id": "2QEmB0n31VfA1j2XN" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/karneboros_sed~meta-ads-intelligence-analyzer/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-karneboros_sed-meta-ads-intelligence-analyzer", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/karneboros_sed~meta-ads-intelligence-analyzer/runs": { "post": { "operationId": "runs-sync-karneboros_sed-meta-ads-intelligence-analyzer", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/karneboros_sed~meta-ads-intelligence-analyzer/run-sync": { "post": { "operationId": "run-sync-karneboros_sed-meta-ads-intelligence-analyzer", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "ads": { "title": "Ad records", "type": "array", "description": "Inline Meta/Facebook Ads Library-style records. Each record can include text/body/headline/title, pageName/advertiserName, CTA, URL, spend, impressions, dates, and platform fields." }, "inputFile": { "title": "Local input file", "type": "string", "description": "Optional local JSON file path containing either an array of ads or an object with an ads array. Useful for local runs and Apify file-based workflows." }, "brandName": { "title": "Brand or competitor set name", "type": "string", "description": "The brand, market, or competitor set being analyzed." }, "industry": { "title": "Industry", "type": "string", "description": "Industry context used to tune deterministic recommendations." }, "reportMode": { "title": "Report mode", "enum": [ "summary", "per_ad", "both" ], "type": "string", "description": "Choose whether to return per-ad analysis, summary intelligence, or both.", "default": "both" }, "includeRecommendations": { "title": "Include recommendations", "type": "boolean", "description": "Include practical media, creative, and offer recommendations.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```