POST /meta_ads_library_scraper_sync • Credits: 1 credit per returned ad

Meta Ads Library Scraper returns the Facebook and Instagram ads that a brand runs, from one Meta Ad Library search URL. The response is a JSON array of ads with the ad text, the publisher platforms, the start date and the landing domain. Each returned ad costs 1 credit, or $0.02.

What does Meta Ads Library Scraper do?

Meta publishes every active ad on Facebook and Instagram in a public archive called the Meta Ad Library. The archive holds the creative text, the platforms, the run dates and the advertiser page for each ad. The public archive has no official API, and the web interface loads results one screen at a time. Meta Ads Library Scraper reads that archive for you and returns the ads as structured JSON. Marketing teams use it to track competitor campaigns, to record the messages that a rival tests, and to find the landing pages behind each ad. The data source is the Meta Ad Library.

Which endpoint does Meta Ads Library Scraper use?

Method: POST
URL: https://api.richapi.ai/api/v1/meta_ads_library_scraper_sync
Authentication: x-api-key header
Request format: JSON request body
Response: Synchronous JSON array
Credits: 1 credit per returned ad

Meta Ads Library Scraper accepts the POST method only. If you send GET, the API returns 405.

How to build the Meta Ad Library URL

The meta_ad_url parameter takes one Meta Ad Library search URL. Build the URL in the Meta Ad Library web interface, then copy it from the address bar.

Open https://www.facebook.com/ads/library/.
Select the country and the ad category.
Type the brand name or the keyword in the search box.
Copy the full URL from the address bar of the browser.
Send that URL as the value of meta_ad_url.

These query parameters appear in the example URL:

URL query parameter	Meaning	Example value
`active_status`	Limits the search to ads with this run state.	`active`
`ad_type`	Limits the search to this ad category.	`all`
`country`	Limits the search to ads delivered in this country.	`US`
`q`	The brand name or the keyword to search for.	`clay`

A complete example URL:

https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=clay

How to send a Meta Ads Library Scraper request

Copy your API key from the RichAPI dashboard.
Build the Meta Ad Library search URL for the brand that you want to track.
Set meta_ad_url to that URL.
Set limit to the largest number of ads that you want to pay for.
Send a POST request to https://api.richapi.ai/api/v1/meta_ads_library_scraper_sync.
Send the API key in the x-api-key header.
Read the ads from the JSON array in the response.

CAUTION: Set limit on every Meta Ads Library Scraper request. Each returned ad costs 1 credit. A run that returns 200 ads costs 200 credits, or $4.00.

cURL

curl -X POST https://api.richapi.ai/api/v1/meta_ads_library_scraper_sync   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "meta_ad_url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=clay",
    "limit": 25
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/meta_ads_library_scraper_sync",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "meta_ad_url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=clay",
        "limit": 25,
    },
    timeout=180,
)
response.raise_for_status()
ads = response.json()
print(len(ads), "ads returned")
for ad in ads:
    print(ad["pageName"], ad["adStatus"], ad["ctaDomain"])

Node.js

const response = await fetch(
  "https://api.richapi.ai/api/v1/meta_ads_library_scraper_sync",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      meta_ad_url:
        "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=clay",
      limit: 25,
    }),
  },
);

const ads = await response.json();
console.log(`${ads.length} ads returned`);

Which parameters does Meta Ads Library Scraper accept?

Parameter	Type	Required	Default	Description
`meta_ad_url`	string	Yes	`""`	One Meta Ad Library search URL, for example `https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=clay`.
`limit`	integer	Yes	None	The largest number of ads to return, 1 or more. This parameter caps the cost of the run, because each returned ad costs 1 credit. A request without `limit`, or with `limit` set to `0`, returns `400` with the message `limit must be at least 1.` and costs no credit.

Meta Ads Library Scraper accepts these two parameters only. If you send any other field in the request body, the API returns 400 with the message Unknown input field(s).

What does every Meta Ads Library Scraper run include?

Every run returns the full ad records, with the ad text, the creative fields and the advertiser page fields. You cannot ask for a count only.

What does Meta Ads Library Scraper return?

Meta Ads Library Scraper returns a JSON array. Each item in the array is one ad. The example below shows two ads for a competitor search.

[
  {
    "adArchiveID": "1046398733721145",
    "pageName": "Clay",
    "pageCategory": "Software Company",
    "pageCountry": "US",
    "pageLikes": 18420,
    "pageVerified": true,
    "pageInstagramUser": "clay.earth",
    "adStatus": "ACTIVE",
    "adText": "Stop paying for eight data vendors. Clay finds the contact data your team keeps missing.",
    "publisherPlatforms": ["FACEBOOK", "INSTAGRAM"],
    "languages": ["en"],
    "startDate": "2026-07-14",
    "endDate": null,
    "ctaDomain": "clay.com",
    "ctaHeadline": "Start for free",
    "adLibraryURL": "https://www.facebook.com/ads/library/?id=1046398733721145"
  },
  {
    "adArchiveID": "8123094771265530",
    "pageName": "Clay",
    "pageCategory": "Software Company",
    "pageCountry": "US",
    "pageLikes": 18420,
    "pageVerified": true,
    "pageInstagramUser": "clay.earth",
    "adStatus": "ACTIVE",
    "adText": "See how 20,000 revenue teams build lists in minutes. Book a live walkthrough.",
    "publisherPlatforms": ["FACEBOOK"],
    "languages": ["en", "de"],
    "startDate": "2026-06-02",
    "endDate": "2026-08-01",
    "ctaDomain": "clay.com",
    "ctaHeadline": "Book a demo",
    "adLibraryURL": "https://www.facebook.com/ads/library/?id=8123094771265530"
  }
]

RichAPI returns the Meta Ad Library records without a change of shape. A field that the ad does not carry is null.

Which fields does the Meta Ads Library Scraper response hold?

Field	Type	Description
`adArchiveID`	string	The Meta archive identifier of the ad.
`pageName`	string	The name of the Facebook page that runs the ad.
`pageCategory`	string	The category of the advertiser page, for example `Software Company`.
`pageCountry`	string or null	The country of the advertiser page.
`pageLikes`	number or null	The like count of the advertiser page.
`pageVerified`	boolean	`true` when Meta verifies the advertiser page.
`pageInstagramUser`	string or null	The Instagram account name that is linked to the advertiser page.
`adStatus`	string	The run state of the ad, for example `ACTIVE`.
`adText`	string	The body copy of the ad creative.
`publisherPlatforms`	array of strings	The Meta platforms that deliver the ad, for example `FACEBOOK` and `INSTAGRAM`.
`languages`	array of strings	The languages of the ad creative.
`startDate`	string	The date when the ad started to run.
`endDate`	string or null	The date when the ad stopped. The value is `null` for an ad that still runs.
`ctaDomain`	string or null	The domain of the landing page behind the call to action.
`ctaHeadline`	string or null	The call to action text on the ad.
`adLibraryURL`	string	The Meta Ad Library page for this single ad.

How much does Meta Ads Library Scraper cost?

Meta Ads Library Scraper costs 1 credit for each ad in the response. One credit costs $0.02 on the 1,000 and 5,000 credit packs, and less on larger packs. The tables use $0.02. RichAPI counts the items in the returned JSON array and charges one credit per item. A run that returns 50 ads costs 50 credits. That is 50 x $0.02 = $1.00.

Cost of one run, by the number of ads in the response:

Ads returned	Credits	Cost
0	0	$0.00
1	1	$0.02
10	10	$0.20
25	25	$0.50
50	50	$1.00
100	100	$2.00
200	200	$4.00

Cost of a weekly competitor tracker, at 50 ads per run:

Runs	Credits	Cost
1	50	$1.00
4	200	$4.00
52	2,600	$52.00

How to control the cost of a Meta Ads Library Scraper run

The limit parameter is the cost control. The run stops at that number of ads.

Set limit to the number of ads that your report needs.
Multiply limit by 1 credit to find the largest cost of the run.
Multiply that credit total by the price per credit of your pack to find the cost in dollars.
Send limit with a value of 1 first, to check the search URL for the price of one credit.
Raise limit after the one ad result confirms the search URL.

CAUTION: Do not send a broad search URL without a limit value. A broad brand search returns hundreds of ads, and each ad costs 1 credit.

Which errors does Meta Ads Library Scraper return?

Status	Meaning	What to do
`400`	The request body failed validation.	Correct the parameter that the message names. Send `meta_ad_url` and `limit` only.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	The organization has no credits left, or the team reached its monthly spend limit.	Buy credits in the dashboard.
`403`	This API key has no access to this endpoint (`Endpoint not available on your plan`).	Call `GET /api/v1/my-endpoints` to see the endpoints that this key can use. Contact support for access.
`405`	The request used a method other than `POST`.	Send the request again with `POST`.
`429`	The request rate is over the limit.	Wait for the seconds in the `Retry-After` header, then send the request again.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.

A response outside the 200 range costs no credits. RichAPI refunds the credit reservation for every failure.

Frequently asked questions

How do I cap the cost of a Meta Ads Library Scraper run?

Set limit to the largest number of ads that you want to pay for. Meta Ads Library Scraper costs 1 credit per returned ad, so a limit of 25 caps the run at 25 credits, or $0.50.

Does a Meta Ads Library Scraper call that returns zero ads cost credits?

No. RichAPI counts the items in the returned array, and an empty array is zero items. A search URL that matches no ads therefore costs 0 credits.

Can Meta Ads Library Scraper return only the total ad count?

No. Every request returns full ad records. To size a search cheaply, send the same URL with limit set to 1 for a cost of 1 credit.

Can I send more than one Meta Ad Library URL in one request?

No. Meta Ads Library Scraper accepts one URL in meta_ad_url per request. Send one request per brand, and combine the JSON arrays in your own code.

Does Meta Ads Library Scraper return Instagram ads as well as Facebook ads?

Yes. The publisherPlatforms array names every Meta platform that delivers the ad. A value of INSTAGRAM in that array means that the ad runs on Instagram.

How do I find the landing page behind a competitor ad?

Read the ctaDomain field of the ad. It holds the domain of the landing page behind the call to action, and ctaHeadline holds the call to action text.

Does a failed Meta Ads Library Scraper request cost credits?

No. RichAPI refunds the credit reservation for every response outside the 200 range. A 400, 429 or 500 response costs no credits.

Meta Ads Library Scraper API