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:
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.
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.
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.
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.
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"
Parameter | Description |
---|---|
ad_active_status enum {ACTIVE, ALL, INACTIVE} | Search for ads based on the status. Defaults to |
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 |
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 |
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 |
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 |
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 |
search_type enum {KEYWORD_UNORDERED, KEYWORD_EXACT_PHRASE} | The type of search to use for |
Reading from this edge will return a JSON formatted result:
{ "
data
": [], "paging
": {} }
data
paging
Error | Description |
---|---|
100 | Invalid parameter |
1009 | Failed to pass parameter validation. |
200 | Permissions error |