Graph API Version

Ad Library API

Reading

Returns archived ads based on your search. By default we only return all ads that are eligible for delivery and that have the ACTIVE status.


Search all ads stored in the Ads Library. The ads objects in this library are also known as Archived Ads. You can perform keyword searches or search by Page ID associated with ads in the library. Search data for all active and inactive ads related to politics or issues of importance. See Facebook Ads Help Center, About ads related to politics or issues of national importance and Facebook Ad Archive to see the tool built on this API.

The API has the following data fields you can use to query:

  • Date and time someone created the ad,
  • Start and end date when the ad ran,
  • Ad copy,
  • Ad creative, which you can view at a given URL,
  • Currency used to pay for the ad,
  • Facebook Page ID for the Page that ran the ad, and
  • Ad performance data including total amount spent, as a range, total impressions ad received, as a range, demographic distribution, such as age, gender and location of people reached, as a percentage of total audience reached.

Reading with the API returns archived ads based keyword searches on text, image, audio from video and from the call-to-action button. Note that we do not translate your keyword searches, therefore you should provide it in the language the ads are in. For example, if you search Spanish language ads you should provide your search string in Spanish.

End of Results

We return ad object in data. If you paginate through results and reach a point where data contains no values, this means you reached the end of the result set.

Search by Page

The API also returns archived ads for a given Facebook Page ID using the the following search parameter: search_page_ids=, where you can enter up to ten page IDs.

Filters

You can use these filters in your search query to filter results. This makes it easier for you to find certain types of ads. See bylines, impression_condition and publisher_platforms below.

Examples

To get archived ads related to politics or issues of national importance that contain the word 'california' and reached audience in the US:

curl -G \
-d "search_terms='california'" \
-d "ad_type=POLITICAL_AND_ISSUE_ADS" \
-d "ad_reached_countries=['US']" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/ads_archive"

Parameters

ParameterDescription
ad_active_status
enum {ALL, ACTIVE, INACTIVE}

Search for ads based on the status. Defaults to ACTIVE for all ads that are eligible for delivery. Set INACTIVE for ads ineligible for delivery, and ALL for both types.

ad_reached_countries
array<enum {BR, GB, US}>

Facebook delivered the ads in these countries. Provided as ISO country codes.

Required
ad_type
enum {ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, NEWS_ADS, UNCATEGORIZED_ADS}
Default value: "POLITICAL_AND_ISSUE_ADS"

The type of ad. We label either all returned ads as political or issue ads, or label ads for news related to politics or issues of political importance. See Facebook Ads Help Center, About ads related to politics or issues of national importance. We currently only support POLITICAL_AND_ISSUE_ADS.

bylines
array<string>

Filter results for ads with a paid for by disclaimer byline, such as political ads that reference “immigration” paid for by “ACLU”. Provide a JSON array to search for a byline without a comma or one with a comma. For instance ?bylines=["byline, with a comma,","byline without a comma"] returns results with either text variation.

impression_condition
enum {HAS_IMPRESSIONS_LIFETIME, HAS_IMPRESSIONS_YESTERDAY, HAS_IMPRESSIONS_LAST_7_DAYS, HAS_IMPRESSIONS_LAST_30_DAYS, HAS_IMPRESSIONS_LAST_90_DAYS}

Search for ads based on when the ad most recently appeared. HAS_IMPRESSIONS_LIFETIME returns ads that we displayed at least once. HAS_IMPRESSIONS_YESTERDAY returns ads that appeared at least one time yesterday. HAS_IMPRESSION_LAST_<N>_DAYS returns ads that we displayed at least one time in the past N days.

For example, find ads displayed by Facebook in the last 1 or 7 days that mention "census".

publisher_platforms
array<enum {FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, WHATSAPP}>

Search for ads based on whether they appear on a particular platform such as Instagram or Facebook. You can provide one platform or a comma separated list of platforms.

search_page_ids
array<int64>

Search for archived ads based on specific Facebook Page IDs. You can provide up to ten IDs, separated by commas.

search_terms
string
Default value: ""

The terms to search for in your query. We treat a blank space as a logical AND and search for both terms and no other operators. The limit of your string is 100 characters or less.

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {} }

data

A list of ArchivedAd nodes.

paging

For more details about pagination, see the Graph API guide.

Validation Rules

ErrorDescription
100Invalid parameter
1009Failed to pass parameter validation.

Creating

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.