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 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 {ACTIVE, ALL, 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_delivery_date_max
string

Search for ads delivered before the date (inclusive) you provide. The date format should be YYYY-mm-dd.

ad_delivery_date_min
string

Search for ads delivered after the date (inclusive) you provide. The date format should be YYYY-mm-dd.

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

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

Required
ad_type
enum {POLITICAL_AND_ISSUE_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. You must list the complete byline. For example, 'Maria' would not return ads with the byline 'Maria C. Lee for America.'

delivery_by_region
array<string>

View ads by the region (such as state or province) where Accounts Center accounts live or were located when they saw them. You can provide a comma separated list of regions. For instance ?delivery_by_region=['California', 'New York'].

estimated_audience_size_max
int64

Search for ads with a maximum estimated audience size. Must be one of these range boundaries: 1000, 5000, 10000, 50000, 100000, 500000, 1000000, or leave empty for no maximum boundary.

estimated_audience_size_min
int64

Search for ads with a minimum estimated audience size. Must be one of these range boundaries: 100, 1000, 5000, 10000, 50000, 100000, 500000, 1000000.

languages
array<string>

Search for ads based on the language(s) contained in the ad. Language codes are based on the ISO 639-1 language codes and also includes ISO 639-3 language codes CMN and YUE.

For instance ?languages=['es', 'en'].

media_type
enum {ALL, IMAGE, MEME, VIDEO, NONE}

Search for ads based on whether they contain a specific type of media such as an image or video.

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

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. Use search_type to adjust the type of search to use.

search_type
enum {KEYWORD_UNORDERED, KEYWORD_EXACT_PHRASE}

The type of search to use for search_terms field. KEYWORD_EXACT_PHRASE will return results that contain an exact match for the search term. Multiple search terms separated by commas can be used to retrieve results that contain an exact match for each phrase. KEYWORD_UNORDERED will return results that contain the words in the search term in any order. By default this is set to KEYWORD_UNORDERED if search_terms is used.

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.

Error Codes

ErrorDescription
100Invalid parameter
1009Failed to pass parameter validation.
200Permissions error

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.