# Winning Ads Finder: Facebook Ad Library Longevity Scorer (`nerolabs/winning-ads-finder`) Actor

Scores Facebook and Instagram Ad Library ads (or Google Ads Transparency rows, a CSV or Sheet) by days running, copies and live status, and ranks the proven winners first. No scraping or login. Charged per ad scored. Agent-ready: MCP, x402.

- **URL**: https://apify.com/nerolabs/winning-ads-finder.md
- **Developed by:** [Adam Pearce](https://apify.com/nerolabs) (community)
- **Categories:** Marketing, E-commerce, Automation
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 ad 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?

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

## Winning Ads Finder: Facebook Ad Library Longevity Scorer

**Which of these ads actually work?** Give this actor the ad rows your Facebook Ad Library scraper already returned (a dataset, CSV or Google Sheet) and it scores **every ad by how long it has run, how many copies the advertiser made of it and whether it is still live**, then ranks the proven winners first.

Advertisers switch off ads that lose money within days. An ad that is still running after 60 days, copied into five versions, is the best public proof there is that it pays. The Ad Library shows you thousands of ads; this tells you which ones to study.

No scraping, no login, no AI fees: it is maths on rows you already have, so it runs in seconds for a fraction of a cent per ad.

### Who uses it

- **Dropshippers and ecommerce sellers**: scrape a keyword ("protein powder", "posture corrector"), see which products and landing pages have ads running for months, not days.
- **Media buyers and agencies**: scrape a client's rivals, hand over a ranked swipe file of their proven winners with links, text and landing pages.
- **Creative strategists**: see which formats (video, carousel, catalogue) and calls to action last longest for each advertiser.
- **AI agents and n8n or Make flows**: run the Ad Library scraper, then ask "which of these are winners?" in one call.

### How it works (plain words)

1. Each ad gets its **days running**: from its start date to its end date, or to the day the rows were scraped if it is still live.
2. It counts **copies**: how many versions of the same creative the advertiser is running (Meta's own collation count, or rows sharing a creative ID). Duplicating an ad is what advertisers do when it is working.
3. It compares each ad with **the same advertiser's other ads**: 3x their usual run length stands out even for a big brand.
4. A **winner score from 0 to 100** weighs days running most, then still live, then copies, placements and the advertiser comparison. Each ad also gets a plain-words **tier** and **reason**.

The same ad appearing twice in your rows (two scrapes, two search terms) is merged and charged once.

### Tiers

| Tier | Rule | What it means |
|---|---|---|
| `proven_winner` | Live 30+ days, or ran 90+ days | The advertiser keeps paying for it |
| `scaling` | Live, 3+ copies | New, but already being duplicated |
| `promising` | Live 14+ days | Passed the first test |
| `testing` | Live under 14 days | Still being tested |
| `stopped_early` | Switched off within 14 days | Most likely a losing test |
| `ran_a_while` | Ran 14 to 89 days, then stopped | Worked for a while |

### What you get for each ad

| Field | What it means |
|---|---|
| `winnerScore` | 0 to 100, higher is a stronger winner |
| `tier`, `reason` | The tier, and one sentence on why |
| `daysRunning`, `stillLive`, `startDate`, `endDate` | How long it has run, and whether it is live |
| `copies` | Versions of the same creative the advertiser runs |
| `advertiserMedianDays`, `vsAdvertiserMedian` | The advertiser's usual run length, and this ad against it |
| `adText`, `headline`, `cta`, `format`, `platforms` | The creative itself |
| `landingUrl`, `landingDomain` | Where the ad sends people (the product or offer) |
| `adUrl`, `imageUrl`, `videoUrl` | Ad Library link and media |
| `rank`, `rankInAdvertiser` | Position overall and within its advertiser |

Plus **one free summary row per advertiser** (`type: advertiser_summary`): ads, live ads, proven winners, median and longest days running, new ads in the last 7 and 30 days (how fast they test), share stopped early, their top ad, and their top landing domains by winners.

### Example output (a "protein powder" Ad Library search, 51 rows)

```json
{
  "type": "ad",
  "rank": 1,
  "advertiser": "ProDough Shop",
  "winnerScore": 88,
  "tier": "proven_winner",
  "daysRunning": 167,
  "stillLive": true,
  "copies": 3,
  "startDate": "2026-05-18",
  "reason": "Still live after 167 days, 3 copies of this creative, on 5 placements. The advertiser keeps paying for it: treat it as a proven winner.",
  "format": "VIDEO",
  "landingDomain": "prodoughshop.com",
  "adUrl": "https://www.facebook.com/ads/library/?id=..."
}
```

### Which scrapers it reads

Field names are matched automatically (snake_case, camelCase and nested `snapshot` fields), so rows go in exactly as the scraper wrote them:

- **curious_coder/facebook-ads-library-scraper** (Facebook Ad Library Scraper)
- **apify/facebook-ads-scraper** (Facebook Ads Scraper)
- **memo23/facebook-ads-library-scraper-ppe**, **whoareyouanas/meta-ad-scraper** and other Meta Ad Library scrapers with start and end dates
- **Google Ads Transparency** scrapers with first shown and last shown dates
- **Your own sheet**: any table with an advertiser column and a start date column. End date, active, copies and landing page are used when present.

To run it automatically after every scrape, open the scraper's **Integrations** tab, add this actor and set **Datasets** to `{{resource.defaultDatasetId}}`.

### Input

| Field | What it does |
|---|---|
| Datasets | One or more scraper datasets |
| File or Google Sheet URL | A CSV, Excel or JSON file, or a shared Google Sheet |
| Ad rows | Rows as JSON, for a quick run or an AI agent call |
| Only ads running at least (days) | Keep only ads at or over this many days (others are free) |
| Only ads still live | Keep only live ads |
| Only these tiers | e.g. only `proven_winner` and `scaling` |
| Top ads per advertiser | Keep each advertiser's best N |
| Add a summary row per advertiser | Free summary rows (on by default) |
| Scrape date | The day the rows were scraped; worked out from the rows when empty |
| Also save as a file | CSV or Excel copy |
| Also append to a named dataset | Track a rival's ads week by week |

Run it with no input and it scores a public example file, so you can see the output first.

### Pricing

Pay per event, no subscription:

- **$0.002 per unique ad scored** (1,000 ads = $2). Ads you filter out, duplicates and rows without a date are free.
- **$0.01 per CSV or Excel file**, only if you ask for one.
- Advertiser summary rows are free.

Scoring costs far less than the scrape itself, so it is worth adding to every Ad Library run.

### Agent-ready

Pay per event, limited permissions and plain JSON in and out, so AI agents can call it through the Apify MCP server or pay per call with x402 at the Nero Labs Agent Tools shop (`POST /winning-ads`).

### FAQ

**Does a long run always mean an ad makes money?** No tool can see sales from the Ad Library. But advertisers stop losing ads fast, so days running plus copies is the strongest public signal there is, and it is what media buyers check by hand.

**My live ads show 0 days?** The scraper's rows give the start date; a live ad counts to the scrape date. If your sheet has no end dates and no active column, set **Scrape date**.

**Does it scrape Facebook?** No. It only reads rows you already have, so it never logs in or touches Facebook.

**Can I score Google or TikTok ads?** Yes, any rows with an advertiser and a start date (first shown) work. Copies are only known for Meta rows.

If it found you a winner, a review on the Apify Store helps a lot.

# Actor input Schema

## `datasetIds` (type: `array`):

One or more ad scraper datasets: Facebook and Instagram Ad Library scrapers (curious_coder/facebook-ads-library-scraper, apify/facebook-ads-scraper, memo23, whoareyouanas and look-alikes) or Google Ads Transparency scrapers. A rival's page, a keyword search or a whole niche. In a scraper's Integrations tab, set this to {{resource.defaultDatasetId}}.

## `fileUrl` (type: `string`):

A public link to a CSV, Excel, JSON or JSON Lines file: Ad Library scraper rows, or your own sheet with an advertiser and an ad start date column (plus end date, active, copies and landing page if you have them). Google Sheets share links work (set 'Anyone with the link can view').

## `fileFormat` (type: `string`):

Leave on 'Detect automatically' unless the link has no file extension.

## `sheetName` (type: `string`):

Which sheet to read from an Excel workbook. Defaults to the first sheet.

## `data` (type: `array`):

Rows as JSON objects, for a quick run or an AI agent call, e.g. \[{"advertiser": "Acme", "adId": "123", "startDate": "2026-06-01", "isActive": true, "copies": 4, "landingUrl": "https://acme.com/offer"}]. Ad Library scraper rows can be passed as they are.

## `minDaysRunning` (type: `integer`):

Leave out ads that ran fewer days than this (not charged). 0 = keep every ad. 30 is a common 'winning ad' line.

## `onlyLive` (type: `boolean`):

Keep only ads that are still running on the day the rows were scraped (not charged for the rest).

## `tiers` (type: `array`):

Keep only ads in these tiers (empty = all). Proven winner: live 30+ days or ran 90+. Scaling: live with 3+ copies. Promising: live 14+ days. Testing: live under 14 days. Stopped early: off within 14 days. Ran a while: ran 14 to 89 days, then stopped.

## `topPerAdvertiser` (type: `integer`):

Keep only each advertiser's best N ads by winner score (0 = all). Handy for a niche scan with many advertisers.

## `includeAdvertiserSummary` (type: `boolean`):

Free extra rows (type 'advertiser_summary'): ads, live ads, proven winners, median days running, new ads in the last 7 and 30 days (how fast they test), share stopped early, top ad and top landing domains.

## `asOfDate` (type: `string`):

The date the rows were scraped, e.g. 2026-11-01, used to count days for live ads. Leave empty to work it out from the rows (the newest end date on a live ad).

## `exportFormats` (type: `array`):

Also save the results as CSV or Excel in the run's key-value store (charged once per file).

## `outputDatasetName` (type: `string`):

Name of a dataset to append the results to, to track a rival's ads week by week.

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

Stop reading after this many input rows.

## Actor input object example

```json
{
  "fileUrl": "https://nerolabs-samples.nerolabs.workers.dev/sample-meta-ads.json",
  "fileFormat": "auto",
  "minDaysRunning": 0,
  "onlyLive": false,
  "topPerAdvertiser": 0,
  "includeAdvertiserSummary": true,
  "maxItems": 200000
}
```

# Actor output Schema

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

One row per ad, best winner score first: days running, copies, still live, tier, reason, ad text, landing page, Ad Library link; then a free row per advertiser.

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

Ads scored, tier counts, top 20 ads, advertiser summaries, settings, export links and warnings.

# 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 = {
    "fileUrl": "https://nerolabs-samples.nerolabs.workers.dev/sample-meta-ads.json"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nerolabs/winning-ads-finder").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 = { "fileUrl": "https://nerolabs-samples.nerolabs.workers.dev/sample-meta-ads.json" }

# Run the Actor and wait for it to finish
run = client.actor("nerolabs/winning-ads-finder").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 '{
  "fileUrl": "https://nerolabs-samples.nerolabs.workers.dev/sample-meta-ads.json"
}' |
apify call nerolabs/winning-ads-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nerolabs/winning-ads-finder"
        }
    }
}
```

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/BBIAYjfN9YbTj5g8o/builds/PoI99Dpq8DfX8FOgs/openapi.json
