# Meta Brand Finder — Resolve Brand Names to Page IDs (`scrapeify/facebook-page-id-finder`) Actor

Convert any brand name into deduplicated Meta advertiser Page ID candidates with category, followers, avatar, and page alias. Outputs map directly to the pageId input of Meta, Instagram, and WhatsApp Ad Library scrapers. First step in any Meta Ad Library automation pipeline.

- **URL**: https://apify.com/scrapeify/facebook-page-id-finder.md
- **Developed by:** [Scrapeify](https://apify.com/scrapeify) (community)
- **Categories:** Social media, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $25.00 / 1,000 results

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/platform/actors/running/actors-in-store#pay-per-event

## 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 Ad Library Brand Finder — Resolve Brand Names to Facebook Page IDs

Convert any **brand name string** into a **curated list of Meta advertiser page candidates** — complete with numeric Page IDs, categories, follower counts, avatar URLs, and page aliases — without touching the Meta Ad Library UI. The Scrapeify Brand Finder issues an automated `keyword_unordered` Ad Library search, fetches up to 150 source ads using a collated strategy, projects each result into a clean suggestion row, merges duplicates by preferring non-null fields, and outputs structured Dataset items plus `SUMMARY` and `RESULTS` key-value records.

Use it as the first step in any Meta Ad Library automation pipeline to resolve brand strings into the numeric `page_id` values required by the [Meta](https://apify.com/scrapeify/meta-ad-library-scraper), [Instagram](https://apify.com/scrapeify/instagram-ad-library-scraper), and [WhatsApp](https://apify.com/scrapeify/whatsapp-ad-scraper) Ad Library scrapers.

---

### Features

| Capability | Detail |
|---|---|
| **Single-string input** | Just pass `brand_name` — minimal configuration surface |
| **Automated dedup + merge** | Stable keys on `page_id`; merges duplicate candidates preferring non-null fields |
| **Rich suggestion rows** | `adlibrary_url` (Page ID), `brand_name`, `category`, `avatar_url`, `likes`, `page_alias`, `timestamp` |
| **Operational metrics** | `source_ads_count`, `suggestions_count`, `pages_scraped`, `execution_time_seconds` in every summary |
| **Chain-ready output** | `adlibrary_url` maps directly to `pageId` in all downstream Scrapeify Ad Library actors |
| **Fail-fast monitoring** | Hard errors trigger `Actor.fail` for PagerDuty/email alerts |
| **Collated strategy** | `collated_strategy="all"` widens fetch for broader page candidate recall |
| **Timestamp metadata** | Each suggestion row carries ISO timestamp for drift detection on periodic re-runs |

---

### Use Cases

#### Page ID Discovery (Primary Use Case)
The most common use: find the numeric `page_id` for any Meta advertiser programmatically. Pass the result as `pageId` to the Meta, Instagram, or WhatsApp Ad Library scrapers for deep creative pulls — without manually hunting IDs in the browser UI.

#### Competitive Brand Mapping
Build a registry of competitor Page IDs keyed to your internal brand taxonomy. Automate quarterly refreshes to detect newly advertising pages, brand renames, or subsidiary accounts entering the paid social market.

#### Brand List Automation
Process a CSV of 100+ brand names through a fan-out orchestration. Each row gets a Brand Finder run, validated Page IDs, a subsequent creative pull, and dashboard ingestion — zero manual UI work at scale.

#### Disambiguation & Homonym Research
The same brand string can return multiple advertisers — regional entities, retailers, franchisees, licensees. Surface all candidates with `category`, `likes`, and `avatar_url` for human or LLM-assisted selection before triggering expensive creative pulls.

#### AI Agent Tool Registration
Register as an agent tool that converts natural-language brand mentions to structured `(page_id, name, category)` tuples. Downstream agents invoke Ad Library scrapers with exact Page IDs rather than keyword searches, improving result precision.

#### CRM Data Enrichment
Join marketing CRM brand strings to Meta social graph entities. Enrich contact and company records with `category`, `likes`, `page_alias`, and `avatar_url` for segmentation, lead scoring, or campaign targeting.

#### Market Landscape Research
Discover which advertiser entities are actively running ads for any brand or category keyword. Build a rapid competitive landscape map without manual browsing — output feeds directly into category analysis dashboards.

#### Periodic Monitoring
Run the finder on a schedule for your tracked brand list. Diff `adlibrary_url` sets between runs to detect new advertiser entrants, brands that stopped advertising, or renamed pages.

---

### Why Choose This Actor

- **Focused scope** — discovery only, not creative dumps; keeps individual runs cheap and fast
- **Schema alignment** — `adlibrary_url` maps directly to `pageId` across all Scrapeify Ad Library actors
- **Explicit recall metrics** — `source_ads_count` and `pages_scraped` on every run so you know when coverage is thin
- **Production failure handling** — `Actor.fail` with typed error KV keys surfaces to monitoring infrastructure

---

### Quick Start

1. Open the Scrapeify **Brand Finder** on Apify Console.
2. Enter a **`brand_name`** string (e.g. `Nike` or `Glossier`).
3. Click **Start** and wait for completion (typically 20–40 seconds).
4. Open the **Dataset** for deduplicated suggestion rows.
5. Check **`SUMMARY`** in the default KV store for counts and timing.
6. Pass the `adlibrary_url` value (numeric Page ID) as **`pageId`** in a downstream Ad Library scraper.

> **Tip:** Review `category`, `likes`, and `avatar_url` before passing a Page ID to a creative scraper — especially for common brand names with multiple candidate pages.

---

### Input Schema

```json
{
  "brand_name": "Nike"
}
````

| Field | Type | Required | Description |
|---|---|---|---|
| `brand_name` | string | Yes | Brand name or search string. Always pass explicitly — do not rely on internal actor defaults in production. |

***

### Output Schema

#### Dataset Row (one row per unique advertiser page candidate)

```json
{
  "adlibrary_url": "15087023444",
  "brand_name": "Nike Global",
  "category": "Sportswear",
  "avatar_url": "https://scontent.xx.fbcdn.net/v/t39.30808-1/...",
  "likes": 38000000,
  "verification": null,
  "page_alias": "nike",
  "ig_username": null,
  "ig_followers": null,
  "ig_verification": null,
  "search_brand_name": "Nike",
  "timestamp": "2026-05-07T12:34:56.789012"
}
```

| Field | Type | Description |
|---|---|---|
| `adlibrary_url` | string | **Numeric Page ID** — pass as `pageId` in downstream Ad Library scrapers |
| `brand_name` | string | Page display name from Meta |
| `category` | string | Meta page category (e.g. `Sportswear`, `Financial Services`, `Health & Beauty`) |
| `avatar_url` | string | Page profile image URL for visual verification |
| `likes` | integer | Page like count at time of scrape |
| `verification` | string/null | Verification badge status if available |
| `page_alias` | string | Vanity URL slug (e.g. `nike` → `facebook.com/nike`) |
| `ig_username` | string/null | Linked Instagram username (placeholder — not actively enriched) |
| `ig_followers` | integer/null | Instagram follower count (placeholder) |
| `ig_verification` | boolean/null | Instagram verification (placeholder) |
| `search_brand_name` | string | Input `brand_name` echoed for warehouse joins and audits |
| `timestamp` | string | ISO 8601 UTC timestamp of extraction |

> **Important:** `adlibrary_url` is a **stringified numeric Page ID**, not a URL. Pass it directly as the string value of `pageId`.

#### Key-Value Store: `SUMMARY`

```json
{
  "brand_name": "Nike",
  "total_results": 12,
  "suggestions_count": 12,
  "source_ads_count": 150,
  "pages_scraped": 11,
  "execution_time_seconds": 28.4,
  "timestamp": "2026-05-07T12:34:56.789012"
}
```

#### Key-Value Store: `RESULTS`

```json
{
  "suggestions": [
    {
      "adlibrary_url": "15087023444",
      "brand_name": "Nike Global",
      "category": "Sportswear",
      "avatar_url": "https://scontent.xx.fbcdn.net/...",
      "likes": 38000000,
      "verification": null,
      "page_alias": "nike"
    }
  ],
  "metadata": {
    "brand_name": "Nike",
    "total_results": 12,
    "source_ads_count": 150,
    "execution_time_seconds": 28.4,
    "timestamp": "2026-05-07T12:34:56.789012"
  }
}
```

| KV Key | Description |
|---|---|
| `SUMMARY` | Run counts, timing, and brand name — ideal for dashboards and zero-result alerts |
| `RESULTS` | Full suggestion array + metadata — download for pipeline ingestion |
| `ERROR` | On failure: `{ error, timestamp, brand_name }` — triggers `Actor.fail` |

***

### API Examples

#### cURL

```bash
curl "https://api.apify.com/v2/acts/scrapeify~facebook-ad-library-suggestions/runs?token=$APIFY_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"brand_name": "Allbirds"}'
```

#### Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])

run = client.actor("scrapeify/facebook-page-id-finder").call(
    run_input={"brand_name": "Allbirds"}
)

pages = client.dataset(run["defaultDatasetId"]).list_items().items
for page in pages:
    print(f"Page ID: {page['adlibrary_url']} | Name: {page['brand_name']} | Category: {page['category']}")
```

#### JavaScript / Node.js

```javascript
import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor("scrapeify/facebook-page-id-finder").call({
  brand_name: "Lululemon",
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Found ${items.length} advertiser candidates for Lululemon`);
```

#### Chain Example — Brand Finder → Meta Ad Scraper (JavaScript)

```javascript
// Step 1: Resolve brand name to Page ID candidates
const finderRun = await client.actor("scrapeify/facebook-page-id-finder").call({
  brand_name: "Glossier",
});
const { items } = await client.dataset(finderRun.defaultDatasetId).listItems();

// Step 2: Select best candidate (validate category/likes before automating)
const pageId = items[0]?.adlibrary_url;

// Step 3: Deep ad creative pull
const adsRun = await client.actor("scrapeify/meta-ad-library-scraper").call({
  pageId: String(pageId),
  maxResults: 400,
  sortBy: "total_impressions",
});
```

#### Chain Example — Brand Finder → Meta Ad Scraper (Python)

```python
finder_run = client.actor("scrapeify/facebook-page-id-finder").call(
    run_input={"brand_name": "Glossier"}
)
items = client.dataset(finder_run["defaultDatasetId"]).list_items().items
page_id = str(items[0]["adlibrary_url"])

ads_run = client.actor("scrapeify/meta-ad-library-scraper").call(
    run_input={"pageId": page_id, "maxResults": 400, "sortBy": "total_impressions"}
)
```

***

### Integration Examples

#### LangChain

```python
from langchain.tools import tool

@tool
def find_meta_page_id(brand_name: str) -> list:
    """Resolve a brand name to Meta advertiser Page ID candidates with category and likes."""
    run = client.actor("scrapeify/facebook-page-id-finder").call(
        run_input={"brand_name": brand_name}
    )
    return client.dataset(run["defaultDatasetId"]).list_items().items
```

Chain: `find_meta_page_id` → `get_meta_ads` → `analyze_creative_themes`

#### CrewAI

`BrandResearchAgent` resolves brand names with this tool. `AdStrategyAgent` receives validated Page IDs and pulls creative data. `BriefAgent` generates competitive reports — no manual URL hunting in the workflow.

#### AutoGen

```python
## UserProxyAgent: "Find Allbirds' Meta Page ID and pull their top 200 Instagram ads"
## AssistantAgent calls brand_finder → validates candidates → calls instagram_scraper
## AnalysisAgent clusters creative themes from structured JSON
```

#### Make.com / Zapier

Iterator over brand name list → HTTP POST to Brand Finder → collect Page ID per brand → batch-trigger Meta ad scraper → aggregate in Google Sheets competitive dashboard.

#### Claude / Gemini Tool Use

Feed multiple candidate rows as JSON context. Prompt the model: "Given these Meta page candidates for 'Nike', which best matches a global sportswear brand selling running shoes?" Ground final selection on numeric ID, not name alone.

#### n8n Workflow

1. Cron trigger → Brand Finder run per brand
2. Read `SUMMARY.suggestions_count`
3. If 0 → Slack alert "No pages found for {brand\_name}"
4. If >0 → pass top `adlibrary_url` to Meta Ad Scraper → update Notion database

#### Vector Database

Embed `brand_name + " " + category` as semantic vector. Store `adlibrary_url`, `likes`, `page_alias` as metadata. Build a brand-to-page mapping retrieval system for disambiguation at scale.

***

### Frequently Asked Questions

**1. What exactly is `adlibrary_url`?**
A **stringified numeric Meta Page ID** — despite the field name, it is not a URL. Pass it directly as the string value of `pageId` in downstream scrapers.

**2. Why is the internal fetch capped at 150 source ads?**
Balances cost, speed, and coverage. The collated strategy maximizes page candidate diversity within this window. Fork to increase the cap if wider recall is required.

**3. How do I handle multiple candidates for one brand?**
Review `category`, `likes`, and `avatar_url` for each row. Use a disambiguation heuristic or an LLM prompt to select the correct entity before triggering expensive creative pulls.

**4. Why are `ig_username` and `ig_followers` null?**
These are placeholder fields. Instagram graph enrichment is not performed by this actor. Enrich externally using `page_alias`.

**5. What does `search_brand_name` contain?**
Your exact input `brand_name` echoed on every row. Preserves audit trail when processing lists of brands in batch pipelines.

**6. What happens if no results are returned?**
`SUMMARY.total_results = 0` — a clean completion, not an error. The brand may not have active ads in the Ad Library.

**7. Does this verify business ownership or registration?**
No — outputs are derived from public Meta Ad Library data only. Association between brand string and page is probabilistic.

**8. Can I run this for 500 brands simultaneously?**
Use a fan-out orchestrator with controlled concurrency. Avoid thousands of simultaneous identical queries from a single IP — add request jitter.

**9. What triggers `Actor.fail`?**
Unhandled exceptions during the scrape. A typed `ERROR` key is written to the KV store with `{ error, timestamp, brand_name }` for debugging.

**10. Can I filter results by country or language?**
Base search uses `country=ALL`. Country-specific filtering requires a downstream Ad Library scraper with geo-filtered URL parameters.

**11. How long does a typical run take?**
20–40 seconds for common brand names. Niche strings with few matching ads may complete faster.

**12. Are re-runs idempotent?**
Results reflect the Ad Library state at execution time. Re-runs may return slightly different candidates as advertisers enter or exit the platform.

**13. Is `category` always accurate?**
Category comes from Meta's public page data. It may be null, generic (`Brand`, `Company`), or miscategorized by the page owner.

**14. Can I find Instagram-only advertisers with this?**
This finder discovers Meta page candidates globally. Use the resulting Page ID with the [Instagram Ad Scraper](https://apify.com/scrapeify/instagram-ad-library-scraper) for Instagram-specific data.

**15. What is `collated_strategy="all"` internally?**
Instructs the underlying fetch to aggregate all available ad format types — still bounded by Meta's API responses. More comprehensive than a single-pass approach.

**16. Are timestamps in UTC?**
Yes — ISO 8601 format in UTC across all timestamp fields.

**17. How do I set up zero-result alerts?**
After each run, compare `SUMMARY.suggestions_count` to 0. If zero, route to a Slack or email alert in your orchestrator.

**18. What encoding are brand name and page name fields in?**
UTF-8. Non-Latin brand names (Arabic, Chinese, Korean, etc.) pass through unchanged.

**19. Is this suitable for political advertiser research?**
Political pages appear in the Ad Library. Apply appropriate data governance and privacy obligations to this use case.

**20. What does a "collided" brand name mean?**
Multiple distinct advertisers bidding on the same search term. Expect multiple rows; do not auto-select the first result for high-stakes automation.

**21. Can I get a page's website URL from this actor?**
Website URL is not a primary output field. Use `page_alias` to construct the Facebook URL, or enrich via downstream scraper fields.

**22. How should I handle brand names with special characters?**
Pass UTF-8 strings as users would type them. The actor passes the string to Meta's search API without sanitization issues for standard UTF-8 input.

**23. What is `verification` in the output?**
Meta's page verification badge status, when available. `null` for most non-verified pages.

**24. Can I use this to monitor a competitor's advertising presence?**
Yes — schedule periodic runs and diff `adlibrary_url` sets to detect new advertiser entities entering a category.

**25. What does a run with `source_ads_count = 0` indicate?**
No ads were fetched from the Ad Library for the brand string. Usually means the brand has no active or archived Meta ads, or the string matches nothing in the index.

***

### Best Practices

- **Always validate candidates** before passing Page IDs to creative scrapers — use `category` + `likes` as signal
- **Store `search_brand_name` in your warehouse** for audit trails when brand naming conventions evolve
- **Version your orchestration** when internal actor constants change in forks
- **Use exponential backoff** at scheduler level for transient Meta errors
- **Tag Apify runs** with `{ brand_name, source_list, run_date }` metadata for traceability in batch jobs
- **Test with niche brands first** — validates pipeline before processing large brand registries
- **Archive `SUMMARY` with each run** for week-over-week coverage trend monitoring

***

### Performance & Scalability

| Factor | Guidance |
|---|---|
| **Single-run scope** | ≤150 internal ads; typically 20–40 seconds |
| **Fan-out capacity** | 500+ brands/hour at moderate concurrency with orchestrator |
| **Memory** | Lightweight HTTP — no browser required |
| **Dedup efficiency** | Stable key merging prevents duplicate rows across collated results |

***

### AI & Automation Workflows

**LLM disambiguation:** Pass all candidate rows to Claude or GPT. Include CRM context fields (industry, country, known products). Ask for the best match. Ground the decision on the numeric `adlibrary_url`, not brand name.

**Brand registry pipeline:** Product team exports brand spreadsheet → fan-out Brand Finder → store Page ID mappings → weekly ad creative refresh → competitive intelligence digest in Slack.

**Entity graph construction:** Join brand strings from [Google News Scraper](https://apify.com/scrapeify/google-news-scraper) press mentions with Meta page candidates from this actor. Build a linked-entity graph enriched with advertising presence signals for market intelligence platforms.

***

### Error Handling

| Scenario | Behavior |
|---|---|
| Missing `brand_name` | Actor runs with internal default — always pass explicitly in production |
| Unhandled exception | Error row in Dataset + `ERROR` KV key + `Actor.fail` for monitoring |
| Meta API error | Typed error propagation; partial Dataset results may still be present |
| Zero results | Clean completion — `SUMMARY.total_results = 0`, not a failure state |
| Duplicate pages | Merged by stable `page_id` key — one row per unique page |

***

### Trust & Reliability

Scrapeify positions the Brand Finder as the **lightweight discovery gateway** to the broader Ad Library ecosystem. Explicit metrics on every run — `source_ads_count`, `pages_scraped`, `execution_time_seconds` — ensure teams know when coverage is thin and can adjust strategy before committing to expensive downstream creative pulls.

***

### Related Scrapeify Actors

Explore the full Scrapeify suite — chain these actors together for end-to-end automation pipelines:

| Actor | What it does |
|---|---|
| [Amazon Scraper](https://apify.com/scrapeify/amazon-scraper) | ASINs, prices, sponsored flags across 23 marketplaces |
| [Instagram Ad Library Scraper](https://apify.com/scrapeify/instagram-ad-library-scraper) | Instagram-only ads from Meta Ad Library |
| [Meta Ad Library Scraper](https://apify.com/scrapeify/meta-ad-library-scraper) | Facebook & Instagram ads with sort options |
| [WhatsApp Ad Scraper](https://apify.com/scrapeify/whatsapp-ad-scraper) | Click-to-WhatsApp ad creatives |
| [YouTube Video Downloader](https://apify.com/scrapeify/youtube-video-downloader) | Videos & audio to Apify Key-Value Store |
| [Google Maps Scraper](https://apify.com/scrapeify/google-maps-scraper) | Local business leads, reviews, emails, contacts |
| [Google News Scraper](https://apify.com/scrapeify/google-news-scraper) | Headlines, sources, article URLs (up to 2K) |

***

*Meta and Facebook are trademarks of Meta Platforms, Inc. This actor is not affiliated with or endorsed by Meta.*

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "SoftwareApplication",
      "name": "Scrapeify Meta Brand & Page ID Finder",
      "applicationCategory": "DeveloperApplication",
      "applicationSubCategory": "Discovery & Lookup API",
      "operatingSystem": "Cloud (Apify Platform)",
      "description": "Resolve any brand name to deduplicated Meta advertiser Page ID candidates with category, follower count, avatar, and page alias. Outputs map directly to pageId input of Meta, Instagram, and WhatsApp Ad Library scrapers.",
      "url": "https://apify.com/scrapeify/facebook-page-id-finder",
      "featureList": [
        "Single-string input — brand_name only",
        "Automatic deduplication and merging",
        "Numeric Page ID resolution",
        "Category, likes, avatar enrichment",
        "Chain-ready output for downstream scrapers",
        "Operational metrics for run health monitoring"
      ],
      "offers": {
        "@type": "Offer",
        "category": "SaaS"
      },
      "publisher": {
        "@type": "Organization",
        "name": "Scrapeify"
      }
    },
    {
      "@type": "FAQPage",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "What exactly is adlibrary_url in the output?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "A stringified numeric Meta Page ID — despite the field name, it is not a URL. Pass it directly as the string value of pageId in downstream Ad Library scrapers."
          }
        },
        {
          "@type": "Question",
          "name": "Why is the internal fetch capped at 150 source ads?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Balances cost, speed, and coverage. The collated strategy maximizes page candidate diversity within this window. Fork the actor to increase the cap if wider recall is required."
          }
        },
        {
          "@type": "Question",
          "name": "How do I handle multiple candidates for one brand name?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Review category, likes, and avatar_url for each row. Use a disambiguation heuristic or LLM prompt to select the correct entity before triggering creative pulls."
          }
        },
        {
          "@type": "Question",
          "name": "What happens if no results are returned?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "SUMMARY.total_results = 0 — a clean completion, not an error. The brand may not have active or archived ads in the Meta Ad Library."
          }
        },
        {
          "@type": "Question",
          "name": "Does this verify business ownership or registration?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "No. Outputs are derived from public Meta Ad Library data only. Association between brand string and Page ID is probabilistic."
          }
        },
        {
          "@type": "Question",
          "name": "How long does a typical run take?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "20–40 seconds for common brand names. Niche strings with few matching ads may complete faster."
          }
        }
      ]
    }
  ]
}
</script>

# Actor input Schema

## `brand_name` (type: `string`):

The brand name to search for in the Facebook Ad Library

## Actor input object example

```json
{
  "brand_name": "Nike"
}
```

# 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("scrapeify/facebook-page-id-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("scrapeify/facebook-page-id-finder").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 '{}' |
apify call scrapeify/facebook-page-id-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scrapeify/facebook-page-id-finder",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Meta Brand Finder — Resolve Brand Names to Page IDs",
        "description": "Convert any brand name into deduplicated Meta advertiser Page ID candidates with category, followers, avatar, and page alias. Outputs map directly to the pageId input of Meta, Instagram, and WhatsApp Ad Library scrapers. First step in any Meta Ad Library automation pipeline.",
        "version": "1.0",
        "x-build-id": "JaIMj7DzEX6flWxtf"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/scrapeify~facebook-page-id-finder/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-scrapeify-facebook-page-id-finder",
                "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/scrapeify~facebook-page-id-finder/runs": {
            "post": {
                "operationId": "runs-sync-scrapeify-facebook-page-id-finder",
                "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/scrapeify~facebook-page-id-finder/run-sync": {
            "post": {
                "operationId": "run-sync-scrapeify-facebook-page-id-finder",
                "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",
                "required": [
                    "brand_name"
                ],
                "properties": {
                    "brand_name": {
                        "title": "Brand Name",
                        "type": "string",
                        "description": "The brand name to search for in the Facebook Ad Library",
                        "default": "Nike"
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```