Graph API Version

Ads Archive

Reading

Returns archived ads for the search


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.

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. 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.

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/<API_VERSION>/ads_archive"

Parameters

ParameterDescription
ad_active_status
enum {ALL, ACTIVE, INACTIVE}

Search for ads based on the status: ACTIVE for are ads that are running, INACTIVE for ads not currently running, 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. Either all ads labeled as political or issue ads, or 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 only support POLITICAL_AND_ISSUE_ADS now.

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.