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,
Ad funding entity,
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

Parameter	Description
`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

Error	Description
100	Invalid parameter
1009	Failed to pass parameter validation.
200	Permissions 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.