# Instagram Ad Library Scraper — Ads by Keyword or Page (`scrapeify/instagram-ad-library-scraper`) Actor
Instagram Ad Library scraper for Meta Ad Library. Extract Instagram-only ads by keyword, brand name, Page ID, or URL. Get creatives, CTAs, spend and impression estimates. No cookies. Apify AI, MCP, and Cursor ready.
- **URL**: https://apify.com/scrapeify/instagram-ad-library-scraper.md
- **Developed by:** [Scrapeify](https://apify.com/scrapeify) (community)
- **Categories:** Social media, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $8.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/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
## Instagram Ad Library Scraper — Ads by Keyword or Page
**Instagram Ad Library scraper** for Meta Ad Library. Pull **Instagram-only ad creatives** with a hard `publisher_platforms[0]=instagram` filter — no manual post-filtering. Search by keyword, brand name, Facebook Page ID, or Ad Library URL. Get structured JSON with ad body, images, videos, CTAs, spend/impression estimates, timing, distribution, and status. No cookies or Meta API key required.
Built for creative strategy, competitive intelligence, and brand tracking that needs Instagram ads without cross-platform noise.
***
### Features
| Capability | Detail |
|---|---|
| **Instagram-only filter** | `publisher_platforms[0]=instagram` enforced at URL build time for keyword and Page ID paths |
| **Three seed modes** | `keyword` (unordered search), `pageId` (numeric page lookup), or full `url` passthrough |
| **Mutually exclusive inputs** | Validation ensures exactly one seed type is active per run |
| **Scrape timeout guard** | 300-second watchdog with cancellation semantics |
| **Input coercion** | `maxResults` accepts positive integers; string-digit coercion supported |
| **Nested ad schema** | `metadata`, `ad_content`, `timing`, `performance`, `distribution`, `status`, `additional_info` |
| **Run summary** | Aggregated impressions/spend proxies, unique platforms, duration, page count in `OUTPUT` |
| **URL validation** | `pageId` numeric check; `url` hostname validation against `facebook.com/ads/library` and `meta.com/ads/library` |
| **Dataset + KV exports** | One Dataset row per ad; `OUTPUT` key in default KV store for dashboards |
***
### Use Cases
#### Creative Intelligence & Ad Strategy
Pull all Instagram ad creatives for a brand or product category. Analyze creative formats (carousel, single image, video), CTA patterns, offer types, and messaging angles from competitors running paid Instagram campaigns.
#### E-Commerce & DTC Brand Research
Track direct-to-consumer brands' Instagram creative cadence, seasonal promotions, and offer testing patterns. Identify which product-led carousel formats and urgency CTAs dominate high-spend verticals.
#### Influencer-Style Funnel Analysis
Study how brands structure Instagram funnels — from awareness creatives to retargeting ads — by comparing creative content across start dates and impression ranges.
#### Competitive Intelligence
Monitor competitor spending patterns on Instagram. Identify brands with surging ad archive IDs, track creative refreshes, and benchmark your category's share of voice on the platform.
#### AI Creative Analysis
Feed structured ad `body` and `title` fields into LLM classifiers to cluster themes, detect prohibited claims, categorize offer types (discount, urgency, social proof), and generate creative briefs informed by what performs in the market.
#### Monitoring & Alerting
Schedule periodic runs on tracked Page IDs. Alert on spikes in new archive IDs indicating campaign launches, or drops indicating budget pauses.
#### RAG & Semantic Search
Store creative text with timestamps in vector databases. Enable temporal queries like "what messaging did Brand X use during Q4 promotions?" using embedding-based retrieval.
#### Market Research
Pass custom browser-address URLs with geographic parameters to study regional creative variations. Compare Instagram creative strategies across markets using the `url` input mode.
***
### Why Choose This Actor
- **Intent-specific** — purpose-built for Instagram inventory; eliminates post-filter logic from your codebase
- **Consistent schema** — identical nested structure as other Scrapeify Ad Library actors (Meta, WhatsApp) for unified warehousing
- **Production guardrails** — input validation before expensive pagination prevents wasted runs
- **Operational transparency** — `pagesScraped`, `executionTimeSeconds`, and platform universe in every `OUTPUT`
***
### Quick Start
1. Open the Scrapeify **Instagram Ad Scraper** on Apify Console.
2. Choose your seed: enter a **`keyword`** (e.g. `skincare serum`), a numeric **`pageId`**, or paste a full **`url`** from your browser's Ad Library address bar.
3. Set **`maxResults`** — start with 50–200 for validation runs.
4. After completion: read **`OUTPUT.summary`** for aggregates, then export the **Dataset** as JSONL.
> **Tip:** To find a brand's numeric Page ID, use the [Scrapeify Brand Finder](https://apify.com/scrapeify/facebook-page-id-finder) actor first.
***
### Input Schema
```json
{
"keyword": "skincare serum",
"maxResults": 200
}
```
| Field | Type | Required | Description |
|---|---|---|---|
| `keyword` | string | One-of | Free-text search term. Instagram filter applied automatically. |
| `pageId` | string | One-of | Numeric Facebook/Meta Page ID (not a vanity URL). |
| `url` | string | One-of | Full Ad Library URL from your browser. Must contain `facebook.com/ads/library` or `meta.com/ads/library`. |
| `maxResults` | integer | Yes | Number of Instagram ads to collect. Must be positive. |
**Exactly one** of `keyword`, `pageId`, or `url` should be provided per run.
***
### Output Schema
#### Dataset Row (one row per Instagram ad)
```json
{
"metadata": {
"scraped_at": "2026-05-07T04:00:00.000Z",
"ad_archive_id": "123456789012345",
"page_id": "9876543210",
"page_name": "GlowLab Skincare",
"page_like_count": 84500,
"page_profile_uri": "https://www.facebook.com/glowlab",
"page_categories": ["Beauty", "Cosmetics"]
},
"ad_content": {
"body": "Vitamin C serum — 48-hour flash sale. Shop now for 30% off.",
"title": "Brighter skin, guaranteed.",
"link_url": "https://glowlab.com/vitamin-c",
"cta_text": "Shop Now",
"images": ["https://scontent.cdninstagram.com/v/t51.29350-15/..."],
"videos": [],
"cards": []
},
"timing": {
"start_date": "2026-04-28",
"end_date": null,
"total_active_time": null
},
"performance": {
"impressions": 1200000,
"spend": 21000,
"currency": "USD"
},
"distribution": {
"publisher_platform": ["INSTAGRAM"],
"targeted_or_reached_countries": ["US", "CA", "GB"]
},
"status": {
"is_active": true,
"is_aaa_eligible": false,
"contains_sensitive_content": false
},
"additional_info": {
"categories": [],
"collation_count": 1
}
}
```
#### Run Summary (`OUTPUT` key in default KV store)
```json
{
"summary": {
"totalAds": 200,
"searchType": "keyword_unordered",
"identifier": "skincare serum",
"searchUrl": "https://www.facebook.com/ads/library/?publisher_platforms[0]=instagram&country=ALL&q=skincare%20serum&search_type=keyword_unordered",
"keyword": "skincare serum",
"pageId": null,
"url": null,
"urlParams": {
"publisher_platforms": ["instagram"],
"country": "ALL"
},
"totalSpend": 85000.25,
"totalImpressions": 4500000,
"uniquePlatforms": ["INSTAGRAM"],
"scrapedAt": "2026-05-07T04:00:00.000Z",
"pagesScraped": 22,
"executionTimeSeconds": 58.7,
"status": "SUCCESS",
"error": null
},
"data": {
"ads": ["...array of full ad objects..."],
"schema": {
"metadata": ["scraped_at", "ad_archive_id", "page_id", "page_name", "page_like_count", "page_profile_uri", "page_categories"],
"ad_content": ["body", "title", "link_url", "cta_text", "cards", "images", "videos"],
"timing": ["start_date", "end_date", "total_active_time"],
"performance": ["spend", "currency", "impressions", "reach_estimate"],
"distribution": ["publisher_platform", "targeted_or_reached_countries"],
"status": ["is_active", "is_aaa_eligible", "contains_sensitive_content"],
"additional_info": ["categories", "archive_types", "collation_count"]
}
}
}
```
| Field | Type | Description |
|---|---|---|
| `summary.totalAds` | integer | Total Instagram ads collected |
| `summary.searchUrl` | string | Constructed Ad Library URL with Instagram platform filter |
| `summary.uniquePlatforms` | array | Should be `["INSTAGRAM"]` when filter applied correctly |
| `summary.pagesScraped` | integer | API pagination pages fetched |
| `summary.executionTimeSeconds` | number | Total scrape duration |
| `summary.status` | string | `SUCCESS`, `ERROR`, `NO_RESULTS`, or `TIMEOUT` |
| `summary.error` | object/null | Typed error: `type`, `message`, `details`, `suggestion` |
| `data.schema` | object | Field group documentation for downstream codegen |
***
### API Examples
#### cURL
```bash
curl "https://api.apify.com/v2/acts/scrapeify~instagram-scraper-premium/runs?token=$APIFY_TOKEN" \
-X POST \
-H "Content-Type: application/json" \
-d '{
"keyword": "luxury watches",
"maxResults": 150
}'
```
#### Python
```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
## Search by keyword
run = client.actor("scrapeify/instagram-ad-library-scraper").call(
run_input={"keyword": "luxury watches", "maxResults": 150}
)
## Or search by Page ID
run = client.actor("scrapeify/instagram-ad-library-scraper").call(
run_input={"pageId": "15087023444", "maxResults": 400}
)
for ad in client.dataset(run["defaultDatasetId"]).iterate_items():
print(ad["ad_content"]["body"], ad["performance"]["impressions"])
```
#### JavaScript / Node.js
```javascript
import { ApifyClient } from "apify-client";
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
// Search by pasted URL (e.g. with country/date filters from browser)
const run = await client.actor("scrapeify/instagram-ad-library-scraper").call({
url: "https://www.facebook.com/ads/library/?country=US&publisher_platforms[0]=instagram&q=fitness+app",
maxResults: 100,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Collected ${items.length} Instagram ads`);
```
***
### Integration Examples
#### ChatGPT / Custom GPT
Expose the run endpoint as a Custom GPT action. Return structured ad JSON so the model can summarize creative themes, identify top CTAs, or compare brands' Instagram messaging strategies.
#### Claude Tool Use
Register an `instagram_ads_search` tool. Pass structured ad rows — body, title, images, performance — into long-context prompts for thematic analysis, compliance checking, or brief generation.
#### Gemini
Feed large batches of ad `body` + `title` pairs into Gemini's long-context window for category classification, sentiment analysis, or creative benchmarking.
#### LangChain
```python
from langchain.tools import tool
@tool
def search_instagram_ads(keyword: str, max_results: int = 100) -> list:
"""Retrieve Instagram ad creatives from Meta Ad Library by keyword."""
run = client.actor("scrapeify/instagram-ad-library-scraper").call(
run_input={"keyword": keyword, "maxResults": max_results}
)
return client.dataset(run["defaultDatasetId"]).list_items().items
```
#### CrewAI
Assign a `CreativeResearchAgent` that calls this tool. A downstream `StrategyAgent` can then generate ad briefs informed by competitive Instagram creative data without manual browsing.
#### AutoGen
Multi-agent workflow: `UserProxyAgent` triggers an Instagram ads lookup; `AssistantAgent` analyzes creative patterns and recommends campaign angles.
#### n8n / Make.com / Zapier
HTTP node → Apify run → poll completion → iterate Dataset items → push to Notion, Airtable, or a Slack digest with top creative previews.
#### RAG Systems
Chunk `ad_content.body` with parent metadata (`page_name`, `start_date`, `impressions`). Store in Pinecone, Weaviate, or Qdrant. Retrieve relevant Instagram ad examples for brief generation or compliance checks.
#### Vector Databases
Embed `body` + `title` as semantic vectors. Filter on `distribution.publisher_platform = INSTAGRAM` and `status.is_active = true` for live creative analysis.
***
### Frequently Asked Questions
**1. Will Facebook or other placements appear in results?**
The Instagram filter targets Instagram inventory. Validate `publisher_platform` arrays occasionally — some ad objects may reflect cross-platform eligible creatives.
**2. How is this different from the Meta Ad Library Scraper?**
Same underlying engine; this actor enforces an Instagram platform constraint at URL construction. The Meta scraper covers all Meta platforms (Facebook, Instagram, Messenger, etc.) without a default platform filter.
**3. How do I find a brand's numeric Page ID?**
Use the [Scrapeify Brand Finder](https://apify.com/scrapeify/facebook-page-id-finder) actor — enter the brand name and get deduplicated Page ID candidates.
**4. Can I filter by country or date range?**
Yes — paste a browser-address Ad Library URL with your geo and date parameters as the `url` input. Country filtering is encoded in the URL.
**5. What is `NO_RESULTS` status?**
The Ad Library returned no matching ads for the given filter combination. Not a credential failure. Try broadening keyword, country scope, or removing active-status filters.
**6. How do I handle TIMEOUT errors?**
Reduce `maxResults` and rerun. Very deep pagination (thousands of ads) may hit the 300-second scrape watchdog.
**7. Are impression and spend figures accurate?**
These are Meta's publicly disclosed transparency **estimates** — not audited financial figures. Treat as directional signals.
**8. What do `cards` and `extra_links` contain?**
Carousel slides and additional link objects within multi-asset ad units. Inspect nested arrays in full Dataset payloads.
**9. Can I download ad media (images, videos)?**
Media URLs are provided. Fetching and storing them is your responsibility — subject to CDN terms and IP rules.
**10. How do I deduplicate results across runs?**
Hash or key on `metadata.ad_archive_id` — the stable unique identifier for each ad in the Meta Ad Library.
**11. Are archived (inactive) ads included?**
Depends on the URL filter. Pass `active_status=all` in a custom URL to include both active and archived creatives.
**12. Is there regional availability variation?**
Some countries restrict Ad Library visibility for certain categories. Trial URL parameters for your target geography.
**13. Do carousel ads appear as one row or multiple?**
One Dataset row per ad. Carousel cards are nested in `ad_content.cards[]`.
**14. Can I run this for multiple brands simultaneously?**
Yes — launch parallel Apify actor instances per `pageId`. Stagger to avoid request hotspots.
**15. What encoding are text fields in?**
UTF-8. Creatives pass through unchanged — multilingual ad copy is preserved as-is.
**16. How large can `maxResults` be?**
No hard cap in the validator, but large values increase pagination time and timeout risk. Test with 200–500 first.
**17. Is `ig_username` available in results?**
Instagram-specific handle is not guaranteed in every row. Enrich externally using `page_alias` or `page_profile_uri`.
**18. Why does `executionTimeSeconds` vary significantly?**
Run time depends on `maxResults`, Meta server response latency, and pagination depth. Monitor `pagesScraped` for tuning.
**19. Can I use this for regulated category research (finance, health)?**
Coverage may be partial for policy-constrained categories. Meta withholds some ad payloads in regulated verticals.
**20. How should I handle currency mixing in spend aggregates?**
`performance.currency` is included per ad. Do not sum spend across heterogeneous currencies without FX normalization.
**21. What proxy setup is recommended?**
Use Apify RESIDENTIAL proxy groups if corporate IP egress yields sparse or blocked pages.
**22. Is there a webhook for run completion?**
Yes — Apify triggers webhooks on `RUN.SUCCEEDED`. Point your endpoint to pull the Dataset automatically.
**23. What does `is_aaa_eligible` mean?**
Indicates eligibility for Meta's "About This Ad" advertiser transparency. Not directly actionable for most use cases.
**24. Can I combine with the WhatsApp scraper output?**
Yes — all Scrapeify Ad Library actors share the same nested schema. Join on `metadata.page_id` for cross-platform creative comparisons.
**25. Are creative rights transferable from the output?**
No. Media URLs and ad content are subject to Meta's and creators' intellectual property rights. This actor provides data visibility, not usage rights.
***
### Best Practices
- **Freeze representative URLs** in version control when audits must reproduce exact results
- **Key on `ad_archive_id`** for idempotent warehousing — prevents duplicate rows across overlapping runs
- **Use residential proxies** if corporate egress yields sparse pagination pages
- **Pilot with small counts** — validate filters and schema alignment before scaling to thousands
- **Archive `searchUrl`** from `OUTPUT.summary` with each analytical snapshot for reproducibility
- **Monitor `executionTimeSeconds`** — creeping runtimes suggest maxResults is too high for one run; shard horizontally
***
### Performance & Scalability
| Factor | Guidance |
|---|---|
| **Throughput** | Pagination-bound; heavy `maxResults` increases step count linearly |
| **Timeout risk** | Runs over several thousand ads may hit 300s guard — shard by keyword or date range |
| **Horizontal scaling** | Run parallel actors per brand shard or geographic segment |
| **Monitoring** | Track `executionTimeSeconds` trend across scheduled runs for anomaly detection |
***
### AI & Automation Workflows
**Creative clustering:** Feed `body` + `title` pairs into an embedding model → cluster by cosine similarity → label themes (discount, social proof, urgency, education) without manual tagging.
**CTA analysis:** Extract `cta_text` across all collected ads → frequency rank → identify dominant action verbs in your vertical.
**Compliance screening:** Pass ad copy through a policy-rule LLM classifier → flag potential prohibited claims → queue for human review.
**Trend monitoring:** Schedule weekly runs → diff new `ad_archive_id` values → alert on brand campaign launches.
***
### Error Handling
| Scenario | Behavior |
|---|---|
| Multiple seeds provided | Validation error before any network requests |
| Non-numeric `pageId` | Validation error with descriptive message |
| Invalid `url` hostname | Validation error — must contain Ad Library domain |
| `TIMEOUT` | Summary status `TIMEOUT`; reduce `maxResults` |
| `NO_RESULTS` | Summary status `NO_RESULTS`; not a failure — Ad Library returned empty for filter |
| `SCRAPING_ERROR` | Typed error object with `details` and `suggestion` fields |
***
### Trust & Reliability
Scrapeify publishes platform-specific Ad Library wrappers so engineering teams don't silently fork URL-parameter logic or miss filter drift. Each run exposes explicit operational metrics — `pagesScraped`, `executionTimeSeconds`, `uniquePlatforms` — for SLA monitoring and pipeline health dashboards.
***
### 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 |
| [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 |
| [Meta Brand & Page ID Finder](https://apify.com/scrapeify/facebook-page-id-finder) | Resolve brand names to numeric Page IDs |
| [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) |
***
*Instagram is a trademark of Meta Platforms, Inc. This actor is not affiliated with or endorsed by Meta.*
***
Built by **[Scrapeify](https://apify.com/scrapeify)** on Apify.
Powered by **[AdScrape](https://www.adscrape.in/)**.
# Actor input Schema
## `keyword` (type: `string`):
Search term or brand (e.g. nike, adidas). Use this OR pageId OR url — only one needed.
## `pageId` (type: `string`):
Numeric Facebook/Meta Page ID (brand ID). Use this OR keyword OR url.
## `url` (type: `string`):
Full Meta Ad Library URL with search parameters. Use this OR keyword OR pageId.
## `maxResults` (type: `integer`):
How many Instagram ads to collect. Paginates until this count or no more results. All rows are Instagram platform.
## Actor input object example
```json
{
"keyword": "nike",
"maxResults": 50
}
```
# Actor output Schema
## `ads` (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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {};
// Run the Actor and wait for it to finish
const run = await client.actor("scrapeify/instagram-ad-library-scraper").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 = {}
# Run the Actor and wait for it to finish
run = client.actor("scrapeify/instagram-ad-library-scraper").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 scrapeify/instagram-ad-library-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapeify/instagram-ad-library-scraper"
}
}
}
```
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 ` 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/sZIk9io3TW68isLVL/builds/9pJq77DZNUYcXpvkz/openapi.json