Instagram Ads Library API examples

Search public Meta Ad Library ads with Instagram placement, connect advertiser research to Python or JavaScript, and export a creative overview to CSV. Use the hosted Instagram Ads Library Scraper through Apify Console or its API.

Open Instagram Ads Library Scraper on Apify

What this repository helps you do

• Search a brand or product keyword in a selected country.
• Collect ads for advertiser Facebook Page IDs in sequential, bounded runs.
• Review ad text, formats, calls to action, landing URLs and reported placements.
• Save API results as JSON and export selected columns to a spreadsheet.

Instagram is the fixed placement filter. A source record may also list Facebook or Threads in publisher_platform. The Actor's Input tab describes its current interface.

Example result

Selected fields from a real public ad captured on 2026-10-04. This is a format reference, not a promise that the same ad remains available. Raw snapshots and temporary media URLs are omitted. See sample JSON and sample CSV.

{
  "ad_archive_id": "3675117995977459",
  "page_name": "IKEA",
  "is_active": true,
  "publisher_platform": [
    "FACEBOOK",
    "INSTAGRAM",
    "THREADS"
  ],
  "creative": {
    "format": "CAROUSEL",
    "title": "IKEA",
    "texts": [
      "Encuentra un nuevo dueño para tus muebles\nDescubre cómo",
      " "
    ],
    "ctaText": "See details",
    "ctaType": "SEE_DETAILS",
    "linkUrl": "https://secondhand.ikea.com/es/es/?utm_source=meta&utm_medium=paid-social&utm_campaign=es_secondhand"
  }
}

Run without code

1. Open the hosted Actor and select Input.
2. Enter a keyword such as ikea, or a Facebook Page ID as an alternative.
3. Start with Maximum ads = 1 and Maximum pages = 1.
4. Keep Enrich ad details off for the first test, then click Start.
5. Inspect the default Dataset and final run status; export JSON or CSV.

No-code guide explains alternatives and incomplete collection.

Try it with Apify's free plan

Apify's Free plan currently includes $5 in monthly prepaid usage and needs no credit card. Credits expire at the end of the billing cycle; this is a budget for small tests, not unlimited free scraping. Check Apify pricing for current conditions.

Quick start for developers

Python 3.10+ is sufficient; the examples use its standard library. Set a token from your Apify account's Integrations settings:

export APIFY_API_TOKEN="your-token"
python examples/python/search_instagram_ads.py

Windows PowerShell:

$env:APIFY_API_TOKEN = "your-token"
python examples/python/search_instagram_ads.py

This starts one run using sample input, prints its ID, checks completion, and saves instagram-ads.json. The example sets a $0.01 per-run event spending cap and a 300-second run timeout. Platform usage and storage operations may be charged separately. Adjust the cap deliberately for larger jobs. Tokens are sent in an authorization header.

Input example

{
  "query": "ikea",
  "country": "ES",
  "activeStatus": "ACTIVE",
  "maxAds": 1,
  "maxPages": 1,
  "includeDetails": false
}

query, pageId and pageUrl are alternative targets. pageUrl is a Facebook advertiser page or alias, not an Instagram profile. Omitting maxAds uses the API default of 100; this example requests one. See input reference.

Request examples

Workflow	Example
One keyword search	Python search
Sequential advertiser runs	Python batch
JSON or Dataset to CSV	Python export
API from a shell	cURL
Node.js 20+	JavaScript

Python and JavaScript check terminal status and RUN_SUMMARY.collectionComplete. Reconcile an uncertain run-start response in Console rather than blindly repeating it. Dataset reads can consume account credit.

Output fields

Field	Meaning
ad_archive_id	Stable Meta ad ID for deduplication
page_id, page_name	Advertiser Facebook page identity
is_active	Reported delivery status
publisher_platform	Reported placements
creative.texts, creative.format	Normalized copy and display format
creative.ctaText, creative.linkUrl	CTA and landing link when supplied
snapshot	Available raw source snapshot in full live results
details, enrichment	Optional advertiser information and its outcome
collection	Applied filters and page-delivery context

Output reference explains missing fields and final status.

Common use cases

• Build a small creative swipe file for a brand or product.
• Observe advertiser activity across separate runs.
• Compare copy and formats in a spreadsheet.

See use cases. Creative records do not establish conversions or return on ad spend.

Search Instagram ad creatives with Python

Edit a copy of the sample input, then run:

python examples/python/search_instagram_ads.py --input my-input.json --output brand-ads.json

Start with a small limit. Source availability and filters can produce fewer rows than requested, including a valid empty search.

Collect advertiser ads in sequential batches

python examples/python/batch_advertiser_ads.py 244033170035 --country ES --max-ads 10

Each unique Page ID starts a separate run. Outputs are saved per advertiser and run ID; later failure preserves earlier files. The $0.01 cap is per run, not a combined cap. Merge repeated observations by ad_archive_id.

Export Instagram ads to CSV

python examples/python/export_ads_csv.py --input-json data/sample-output.json --output instagram-ads.csv

Local export needs no API token and starts no run. Use --dataset-id to read an existing Dataset. The CSV joins placements with | and puts copy in one quoted cell.

FAQ

FAQ covers identifiers, unavailable fields, partial results and spending.

Limits and pricing

The Actor accepts 1-5,000 unique ads and a 1-500 page safety limit per run. Supported limits are not guaranteed delivery counts. Optional details have a separate limit. Date filters apply to the reported ad start date.

Pricing is pay per event: delivered ads create ad and creative_details; successfully returned optional details create advertiser_details. Tier prices and any separate platform usage are shown in the current Actor Pricing tab.

Hosted version

Run Instagram Ads Library Scraper for API access, stored output or a no-code run. This repository supplies examples and documentation for that hosted service.

Responsible use

Respect applicable terms and privacy obligations. Availability does not grant a license to republish advertiser images and videos. Keep tokens out of issues and commits.

Support

For example issues, open a GitHub issue with sanitized input and command. For execution issues, use the Actor Issues tab and include its run ID.

License

Examples and documentation are MIT licensed. Advertiser content remains subject to its owners' rights.