Returns archived ads based on your search.
Reading with the API returns archived ads from the Meta Ad Library based on keyword searches of text, images, audio from video, and the call-to-action button. Note that we do not translate your keyword searches, therefore you should write them in the language of the ads you are searching. For example, if you are searching Spanish language ads you should write your search string in Spanish.
Learn more about the Ad Library API.
The ad objects are returned in data
. If you paginate through results and reach a point where data
contains no values, this means you have reached the end of the result set.
You can request archived ads for up to 10 Facebook Page IDs at once by using the search parameter search_page_ids
.
You can use filters in your search query to return only certain types of ads. See bylines
and publisher_platforms
below.
To return archived ads related to social issues, elections and politics that contain the word 'california' and reached an 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 {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 |
ad_type enum {ALL, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, HOUSING_ADS, POLITICAL_AND_ISSUE_ADS} | Default value: "ALL" 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. |
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 were based or located when an ad was displayed to 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. Leave empty for no maximum boundary. Available only for POLITICAL_AND_ISSUE_ADS |
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. Leave empty for no minimum boundary. Available only for POLITICAL_AND_ISSUE_ADS |
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, 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_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} | Default value: |
unmask_removed_content boolean | Default value: false Specify whether you would like your results to reveal content that was removed for violating our standards. |
Reading from this edge will return a JSON formatted result:
{ "
data
": [], "paging
": {} }
data
paging
Error | Description |
---|---|
100 | Invalid parameter |
613 | Calls to this api have exceeded the rate limit. |
190 | Invalid OAuth 2.0 Access Token |
2500 | Error parsing graph query |
1009 | Failed to pass parameter validation. |