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"Name | Description |
|---|---|
ad_active_statusenum {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_maxstring | Search for ads delivered before the date (inclusive) you provide. The date format should be YYYY-mm-dd. |
ad_delivery_date_minstring | Search for ads delivered after the date (inclusive) you provide. The date format should be YYYY-mm-dd. |
ad_reached_countriesarray<enum {ALL, BR, IN, GB, US, CA, AR, AU, AT, BE, CL, CN, CO, HR, DK, DO, EG, FI, FR, DE, GR, HK, ID, IE, IL, IT, JP, JO, KW, LB, MY, MX, NL, NZ, NG, NO, PK, PA, PE, PH, PL, RU, SA, RS, SG, ZA, KR, ES, SE, CH, TW, TH, TR, AE, VE, PT, LU, BG, CZ, SI, IS, SK, LT, TT, BD, LK, KE, HU, MA, CY, JM, EC, RO, BO, GT, CR, QA, SV, HN, NI, PY, UY, PR, BA, PS, TN, BH, VN, GH, MU, UA, MT, BS, MV, OM, MK, LV, EE, IQ, DZ, AL, NP, MO, ME, SN, GE, BN, UG, GP, BB, AZ, TZ, LY, MQ, CM, BW, ET, KZ, NA, MG, NC, MD, FJ, BY, JE, GU, YE, ZM, IM, HT, KH, AW, PF, AF, BM, GY, AM, MW, AG, RW, GG, GM, FO, LC, KY, BJ, AD, GD, VI, BZ, VC, MN, MZ, ML, AO, GF, UZ, DJ, BF, MC, TG, GL, GA, GI, CD, KG, PG, BT, KN, SZ, LS, LA, LI, MP, SR, SC, VG, TC, DM, MR, AX, SM, SL, NE, CG, AI, YT, CV, GN, TM, BI, TJ, VU, SB, ER, WS, AS, FK, GQ, TO, KM, PW, FM, CF, SO, MH, VA, TD, KI, ST, TV, NR, RE, LR, ZW, CI, MM, AN, AQ, BQ, BV, IO, CX, CC, CK, CW, TF, GW, HM, XK, MS, NU, NF, PN, BL, SH, MF, PM, SX, GS, SS, SJ, TL, TK, UM, WF, EH}> | Search ALL or by ISO country code to return ads that reached specific countries or locations. Note: Ads that did not reach any location in the EU will only return if they are about social issues, elections or politics. Required This parameter is required. |
ad_typeenum {ALL, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, HOUSING_ADS, POLITICAL_AND_ISSUE_ADS} | Default value: Search by type of ad. You can use this to narrow your results to ads in special ad categories: FINANCIAL_PRODUCTS_AND_SERVICES_ADS returns ads related to financial products, services, or institutions. EMPLOYMENT_ADS returns ads related to job listings or employment opportunities. HOUSING_ADS returns housing or real estate ads. POLITICAL_AND_ISSUE_ADS returns ads about social issues, elections or politics. ALL returns ads on all topics.FINANCIAL_PRODUCTS_AND_SERVICES_ADS now replaces CREDIT_ADS. Continued usage of CREDIT_ADS will return FINANCIAL_PRODUCTS_AND_SERVICES_ADS data."ALL" |
bylinesarray<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.' Available only for POLITICAL_AND_ISSUE_ADS |
delivery_by_regionarray<string> | View ads by the region (such as state or province) where Accounts Center accounts were based or located when an ad was displayed to them. You can provide a comma-separated list of regions. For instance ?delivery_by_region=['California', 'New York']. Available only for POLITICAL_AND_ISSUE_ADS |
estimated_audience_size_maxint64 | Search for ads with a maximum estimated audience size. Must be one of these range boundaries: 1000, 5000, 10000, 50000, 100000, 500000, 1000000. Leave empty for no maximum boundary. Available only for POLITICAL_AND_ISSUE_ADS |
estimated_audience_size_minint64 | Search for ads with a minimum estimated audience size. Must be one of these range boundaries: 100, 1000, 5000, 10000, 50000, 100000, 500000, 1000000. Leave empty for no minimum boundary. Available only for POLITICAL_AND_ISSUE_ADS |
languagesarray<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_typeenum {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_platformsarray<enum {FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, WHATSAPP, OCULUS, THREADS}> | Search for ads based on whether they appear on a particular Meta technology, such as Instagram or Facebook. You can provide one technology or a comma-separated list of technologies. |
search_page_idsarray<int64> | Search for archived ads based on specific Facebook Page IDs. You can provide up to ten IDs, separated by commas. |
search_termsstring | 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_typeenum {KEYWORD_UNORDERED, KEYWORD_EXACT_PHRASE} | Default value: KEYWORD_UNORDERED
The type of search to use for the search_terms field.
KEYWORD_UNORDERED will treat each word in search_terms individually, and return results that contain these words in any order.
KEYWORD_EXACT_PHRASE will treat the words in search_terms as a single phrase, and only return results that match that exact phrase.
To search for multiple phrases at once, separate groups of words in search_terms by commas. This will retrieve results that contain an exact match for every phrase. |
unmask_removed_contentboolean | Default value: Specify whether you would like your results to reveal content that was removed for violating our standards.false |
Name | Description |
|---|---|
idnumeric string | The Library ID of the ad object. |
ad_creation_timestring | The UTC date and time when someone created the ad. This is not the same time as when the ad ran. Includes date and time separated by T. Example: 2019-01-24T19:02:04+0000, where +0000 is the UTC offset. |
ad_creative_bodieslist<string> | A list of the text which displays in each unique ad card of the ad. Some ads run with multiple ad versions or carousel cards each with their own unique text. See Reference, Ad Creative. |
ad_creative_link_captionslist<string> | A list of the captions which appear in the call to action section for each unique ad card of the ad. Some ads run with multiple ad versions or carousel cards each with their own unique text that appears in the link. |
ad_creative_link_descriptionslist<string> | A list of text descriptions which appear in the call to action section for each unique ad card of the ad. Some ads run with multiple ad versions or carousel cards each with their own unique text describing the link. |
ad_creative_link_titleslist<string> | A list of titles which appear in the call to action section for each unique ad card of the ad. Some ads run with multiple ad versions or carousel cards each with their own unique title text about the link. |
ad_delivery_start_timestring | Date and time when an advertiser wants to start delivering an ad. Provided in UTC as in ad_creation_time.Default This field is default. |
ad_delivery_stop_timestring | The time when an advertiser wants to stop delivery of their ad. If this is blank, the ad will run until the advertiser stops it or they spend their entire campaign budget. In UTC. Default This field is default. |
ad_snapshot_urlstring | String with URL link which displays the archived ad. This displays uncompressed images and videos from the ad. While you cannot currently download a batch of archived ads, you can download ad creative such as images and text for an individual ad. If you do so, it must be for analysis and you must comply with the data storage terms in our Terms of Service. Default This field is default. |
age_country_gender_reach_breakdown | The demographic distribution of Accounts Center accounts in the UK & EU reached by the ad. Available only for ads delivered to the UK & EU and POLITICAL_AND_ISSUE_ADS delivered to Brazil |
beneficiary_payers | The reported beneficiaries and payers for this ad. Available only for ads delivered to the EU |
br_total_reachint32 | The estimated ad reach for Brazil.
Available for POLITICAL_AND_ISSUE_ADS delivered to Brazil |
bylinesstring | A string containing the name of the person, company, or entity that provided funding for the ad. Provided by the purchaser of the ad. Available only for POLITICAL_AND_ISSUE_ADS |
currencystring | The currency used to pay for the ad, as an ISO currency code. Available only for POLITICAL_AND_ISSUE_ADS |
delivery_by_region | Regional distribution of Accounts Center accounts reached by the ad. Provided as a percentage and where regions are at a sub-country level. Available only for POLITICAL_AND_ISSUE_ADS |
demographic_distribution | The demographic distribution of Accounts Center accounts reached by the ad. Provided as age ranges and gender. Age ranges: Can be one of 18-24, 25-34, 35-44, 45-54, 55-64, 65+. Gender: Can be the following strings: "Male", "Female", "Unknown". Available only for POLITICAL_AND_ISSUE_ADS |
estimated_audience_size | Estimated Audience Size generally estimates how many Accounts Center accounts meet the targeting and ad placement criteria that advertisers select while creating an ad. Learn more. Available only for POLITICAL_AND_ISSUE_ADS |
eu_total_reachint32 | The estimated combined ad reach for all locations inside the European Union. Available only for ads delivered to the EU |
impressions | A string containing the number of times the ad created an impression. In ranges of: <1000, 1K-5K, 5K-10K, 10K-50K, 50K-100K, 100K-200K, 200K-500K, >1M. Available only for POLITICAL_AND_ISSUE_ADS |
languageslist<string> | The list of languages contained within the ad. These are displayed in ISO 639-1 language codes. |
page_idnumeric string | ID of the Facebook Page that ran the ad. Default This field is default. |
page_namestring | Name of the Facebook Page which ran the ad. |
publisher_platformslist<enum> | A list of Meta technologies where the archived ad appeared, such as Facebook or Instagram. |
spend | A string showing the amount of money spent running the ad, as specified in currency. This is reported in ranges: <100, 100-499, 500-999, 1K-5K, 5K-10K, 10K- 50K, 50K-100K, 100K-200K, 200K-500K, >1M. Available only for POLITICAL_AND_ISSUE_ADS |
target_ageslist<numeric string> | The age ranges selected for ad targeting in the UK & EU. The lowest age that can be returned is 13; the highest is 65+. Available only for ads delivered to the UK & EU and POLITICAL_AND_ISSUE_ADS delivered to Brazil |
target_genderenum | The genders selected for ad targeting in the UK & EU. Possible values: “Women”, “Men” or “All”. Available only for ads delivered to the UK & EU and POLITICAL_AND_ISSUE_ADS delivered to Brazil |
target_locations | The locations included or excluded for ad targeting in the UK & EU. Available only for ads delivered to the UK & EU and POLITICAL_AND_ISSUE_ADS delivered to Brazil |
total_reach_by_locationlist<KeyValue:string,int32> | The estimated combined ad reach broken down by location. Currently supported locations: EU, BR, and UK. |