# Search ads Searches the public Facebook Ad Library by keyword and returns raw creative and transparency metadata. Supports validated country, language, publisher-platform, media, status, date, and sort filters. - Platform: [Facebook Ad Library](https://docs.upscrape.com/docs/platforms/fb-adlibrary) - Capability ID: `fb-adlibrary.ad.search` - Cost: 1 credit per request - Maximum runtime: 120 seconds - Execute endpoint: `POST https://data.upscrape.com/execute` ## Request Use the exact public capability ID in the shared execute envelope. ```bash curl --request POST \ --url https://data.upscrape.com/execute \ --header "Authorization: Bearer $UPSCRAPE_API_KEY" \ --header "Content-Type: application/json" \ --header "Prefer: wait=30" \ --data '{ "input": { "country": "US", "limit": 5, "query": "nike" }, "capability": "fb-adlibrary.ad.search" }' ``` ## Input | Field | Type | Required | Description | | --- | --- | --- | --- | | `active` | `string` | No | Filter by delivery status Allowed values: `all`, `active`, `inactive`. Default: `all`. | | `country` | `string` | No | Two-letter uppercase ISO country code or ALL for worldwide Default: `US`. | | `cursor` | `string` | No | Opaque scoped continuation token returned as next_cursor; restart from the beginning if the source changed | | `end_date` | `string` | No | Optional latest impression date (YYYY-MM-DD) | | `languages` | `array` | No | Optional JSON array of content-language codes, for example ["en","es"] | | `limit` | `integer` | No | Maximum number of ads to return From 1 to 100. Default: `50`. | | `media_type` | `string` | No | Filter by creative media type Allowed values: `all`, `image`, `video`, `meme`, `none`. Default: `all`. | | `platforms` | `array` | No | Optional JSON array of publisher platforms Allowed values: `facebook`, `instagram`, `messenger`, `audience_network`, `threads`, `whatsapp`. | | `query` | `string` | Yes | Non-empty search keyword or phrase (maximum 200 characters) | | `sort_by` | `string` | No | Sort the returned creatives Allowed values: `impressions`, `relevance`, `date`. Default: `impressions`. | | `start_date` | `string` | No | Optional earliest impression date (YYYY-MM-DD) | ### Example input ```json { "country": "US", "limit": 5, "query": "nike" } ``` ## Response Successful output is returned in `results[0].data`. Raw platform output is intentionally open-ended and may evolve with the upstream source. ### Illustrative sample output This example shows one response. Values and optional fields vary with the data available. ```json { "items": [ { "ad_archive_id": "1046730950862281", "ad_id": null, "categories": [ "UNKNOWN" ], "collation_count": 1, "collation_id": "3472161186254279", "contains_digital_created_media": false, "contains_sensitive_content": false, "currency": "", "end_date": 1763712000, "fev_info": null, "gated_type": "ELIGIBLE", "has_user_reported": false, "hide_data_status": "NONE", "impressions_with_index": { "impressions_index": -1, "impressions_text": null }, "is_aaa_eligible": false, "is_active": false, "menu_items": [], "page_id": "146705838515566", "page_is_deleted": false, "page_name": "Sukeban World", "publisher_platform": [ "INSTAGRAM" ], "reach_estimate": null, "regional_regulation_data": { "finserv": { "is_deemed_finserv": false, "is_limited_delivery": false }, "tw_anti_scam": { "is_limited_delivery": false } }, "report_count": null, "snapshot": { "additional_info": null, "body": { "text": "SUKEBAN at @animeexpo \n07/05/25 Los Angeles \n\n🎬 @complicasian \nMC @kunichi_nomura \nMusic / yoyo @okamotoreiji @ecec_fc @haroodiy \nCostumes @olympialetan @softskinlatex @dawnamatrix\nSneakers @nike \nHats @stephenjonesmillinery \nMakeup @kalikennedy \nHair @dennisvlanni\nNails @nailsbymei \nProduction @exposureny \n#thisissukeban #sukebanxanimeexpo" }, "branded_content": null, "brazil_tax_id": "[redacted:brazil_tax_id]", "byline": null, "caption": "instagram.com", "cards": [], "country_iso_code": null, "cta_text": "Visit Instagram profile", "cta_type": "VIEW_INSTAGRAM_PROFILE", "disclaimer_label": null, "display_format": "VIDEO", "ec_certificates": [], "event": null, "extra_images": [], "extra_links": [], "extra_texts": [], "extra_videos": [], "images": [], "is_reshared": false, "link_description": null, "link_url": "http://instagram.com/sukeban_world", "page_categories": [ "Sports league" ], "page_id": "146705838515566", "page_is_deleted": false, "page_like_count": 429, "page_name": "Sukeban World", "page_profile_picture_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=oUYRQYYOixcQ7kNvwGS9K-S&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A739463", "page_profile_uri": "https://www.facebook.com/61551864263186/", "root_reshared_post": null, "title": null, "videos": [ { "video_hd_url": "https://video-lga3-3.xx.fbcdn.net/o1/v/t2/f2/m86/[redacted:token].mp4?_nc_cat=104&_nc_sid=b66105&_nc_ht=video-lga3-3.xx.fbcdn.net&_nc_ohc=-XVUAjhSIXAQ7kNvwHS4mzy&efg=[redacted:token]&ccb=17-1&vs=6a7726380c03e491&_nc_vs=[redacted:token]&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&_nc_zt=28&oh=[redacted:token]&oe=6A6F98BD", "video_preview_image_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=110&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=QrN3gjny3EgQ7kNvwFeLpe0&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73AB6C", "video_sd_url": "https://video-lga3-3.xx.fbcdn.net/o1/v/t2/f2/m86/[redacted:token].mp4?_nc_cat=104&_nc_sid=b66105&_nc_ht=video-lga3-3.xx.fbcdn.net&_nc_ohc=BY_Lq-X7d5kQ7kNvwG-ly05&efg=[redacted:token]%3D&ccb=17-1&vs=c95c77148100653c&_nc_vs=[redacted:token]&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&_nc_zt=28&oh=[redacted:token]&oe=6A6FACA5", "watermarked_video_hd_url": "", "watermarked_video_sd_url": "" } ] }, "spend": null, "start_date": 1752044400, "state_media_run_label": null, "targeted_or_reached_countries": [], "total_active_time": null }, { "ad_archive_id": "1869276447125570", "ad_id": null, "categories": [ "UNKNOWN" ], "collation_count": null, "collation_id": null, "contains_digital_created_media": false, "contains_sensitive_content": false, "currency": "", "end_date": 1785567600, "fev_info": null, "gated_type": "ELIGIBLE", "has_user_reported": false, "hide_data_status": "NONE", "impressions_with_index": { "impressions_index": -1, "impressions_text": null }, "is_aaa_eligible": false, "is_active": true, "menu_items": [], "page_id": "15087023444", "page_is_deleted": false, "page_name": "Nike", "publisher_platform": [ "FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK" ], "reach_estimate": null, "regional_regulation_data": { "finserv": { "is_deemed_finserv": false, "is_limited_delivery": false }, "tw_anti_scam": { "is_limited_delivery": false } }, "report_count": null, "snapshot": { "additional_info": null, "body": { "text": "Celebra tu cumpleaños con Nike y obtén acceso a productos exclusivos, MSI, envío y devoluciones gratis el resto del año." }, "branded_content": null, "brazil_tax_id": "[redacted:brazil_tax_id]", "byline": null, "caption": "itunes.apple.com", "cards": [ { "body": "Celebra tu cumpleaños con Nike y obtén acceso a productos exclusivos, MSI, envío y devoluciones gratis el resto del año.", "caption": "itunes.apple.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "Download Nike: Shoes, Apparel, Stories by Nike, Inc on the App Store. See screenshots, ratings and reviews, user tips, and more apps like Nike: Shoes, Apparel,…", "original_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=107&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ttLZDV5dN64Q7kNvwFo1RxH&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73B003", "resized_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=107&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ttLZDV5dN64Q7kNvwFo1RxH&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73B003", "title": "Nike", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Celebra tu cumpleaños con Nike y obtén acceso a productos exclusivos, MSI, envío y devoluciones gratis el resto del año.", "caption": "itunes.apple.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "Download Nike: Shoes, Apparel, Stories by Nike, Inc on the App Store. See screenshots, ratings and reviews, user tips, and more apps like Nike: Shoes, Apparel,…", "original_image_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=FYoZDGOs1iYQ7kNvwHDwrFQ&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73AC2F", "resized_image_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=FYoZDGOs1iYQ7kNvwHDwrFQ&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73AC2F", "title": "Nike", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Celebra tu cumpleaños con Nike y obtén acceso a productos exclusivos, MSI, envío y devoluciones gratis el resto del año.", "caption": "itunes.apple.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "Download Nike: Shoes, Apparel, Stories by Nike, Inc on the App Store. See screenshots, ratings and reviews, user tips, and more apps like Nike: Shoes, Apparel,…", "original_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=7rfWHLvuJUAQ7kNvwE2YaFM&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73B7A0", "resized_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=7rfWHLvuJUAQ7kNvwE2YaFM&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73B7A0", "title": "Nike", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null } ], "country_iso_code": null, "cta_text": "Install now", "cta_type": "INSTALL_MOBILE_APP", "disclaimer_label": null, "display_format": "DPA", "ec_certificates": [], "event": null, "extra_images": [], "extra_links": [], "extra_texts": [], "extra_videos": [], "images": [], "is_reshared": false, "link_description": null, "link_url": "http://itunes.apple.com/app/id1095459556", "page_categories": [ "Sportswear" ], "page_id": "15087023444", "page_is_deleted": false, "page_like_count": 39577479, "page_name": "Nike", "page_profile_picture_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=drdbCFFung0Q7kNvwFF51VC&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-3.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A7393D6", "page_profile_uri": "https://www.facebook.com/nike/", "root_reshared_post": null, "title": "Nike: Shoes, Apparel, Stories", "videos": [] }, "spend": null, "start_date": 1773730800, "state_media_run_label": null, "targeted_or_reached_countries": [], "total_active_time": null }, { "ad_archive_id": "161966936869658", "ad_id": null, "categories": [ "UNKNOWN" ], "collation_count": null, "collation_id": null, "contains_digital_created_media": false, "contains_sensitive_content": false, "currency": "", "end_date": 1774854000, "fev_info": null, "gated_type": "ELIGIBLE", "has_user_reported": false, "hide_data_status": "NONE", "impressions_with_index": { "impressions_index": -1, "impressions_text": null }, "is_aaa_eligible": true, "is_active": false, "menu_items": [], "page_id": "15087023444", "page_is_deleted": false, "page_name": "Nike", "publisher_platform": [ "FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK" ], "reach_estimate": null, "regional_regulation_data": { "finserv": { "is_deemed_finserv": false, "is_limited_delivery": false }, "tw_anti_scam": { "is_limited_delivery": false } }, "report_count": null, "snapshot": { "additional_info": null, "body": { "text": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis." }, "branded_content": null, "brazil_tax_id": "[redacted:brazil_tax_id]", "byline": null, "caption": "nike.com/mx", "cards": [ { "body": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis.", "caption": "ad.doubleclick.net", "cta_text": "Shop Now", "cta_type": "SHOP_NOW", "image_crops": [], "link_description": "", "link_url": "https://www.nike.com/mx/t/calzado-de-golf-tiger-woods-13-ChGrTt?cp=77438547234_soc_", "original_image_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=103&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=LPYhebtLjEoQ7kNvwG1znt_&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73B69F", "resized_image_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=103&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=LPYhebtLjEoQ7kNvwG1znt_&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73B69F", "title": "Calzado de golf para hombre Tiger Woods '13 - Negro", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis.", "caption": "ad.doubleclick.net", "cta_text": "Shop Now", "cta_type": "SHOP_NOW", "image_crops": [], "link_description": "", "link_url": "https://www.nike.com/mx/t/shorts-de-tejido-woven-jordan-essentials-sPBbsb?cp=77438547234_soc_", "original_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=qvSnQLxbtZUQ7kNvwGdC7dq&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A738A61", "resized_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=qvSnQLxbtZUQ7kNvwGdC7dq&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A738A61", "title": "Shorts de tejido Woven para hombre Jordan Essentials - Negro", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Entra a Nike.com y encuentra actualizaciones semanales de producto con envío gratis.", "caption": "ad.doubleclick.net", "cta_text": "Shop Now", "cta_type": "SHOP_NOW", "image_crops": [], "link_description": "", "link_url": "https://www.nike.com/mx/t/[redacted:token]?cp=77438547234_soc_", "original_image_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=108&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=rqZpzBJfjNIQ7kNvwE0K4JY&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-3.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73A3EC", "resized_image_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=108&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=rqZpzBJfjNIQ7kNvwE0K4JY&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-3.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73A3EC", "title": "Calzado de entrenamiento para hombre Nike Metcon 8 - Gris", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null } ], "country_iso_code": null, "cta_text": "Shop now", "cta_type": "SHOP_NOW", "disclaimer_label": null, "display_format": "DPA", "ec_certificates": [], "event": null, "extra_images": [], "extra_links": [], "extra_texts": [], "extra_videos": [], "images": [], "is_reshared": false, "link_description": null, "link_url": "https://ad.doubleclick.net/ddm/trackclk/N8893.2410306FACEBOOKADS/B30448992.373431644;dc_trk_aid=564542764;dc_trk_cid=196659869;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=;ltd=;dc_tdv=1", "page_categories": [ "Sportswear", "Product/service" ], "page_id": "15087023444", "page_is_deleted": false, "page_like_count": 39577479, "page_name": "Nike", "page_profile_picture_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=104&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=08Vi-ht-T5IQ7kNvwHz9Bqj&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-lga3-3.xx&_nc_gid=XX3uZGZPxkWb3ZseFb25cg&_nc_ss=7b289&oh=[redacted:token]&oe=6A73A4E8", "page_profile_uri": "https://www.facebook.com/nike/", "root_reshared_post": null, "title": "{{product.name}}", "videos": [] }, "spend": null, "start_date": 1692082800, "state_media_run_label": null, "targeted_or_reached_countries": [], "total_active_time": null } ], "next_cursor": "[redacted:token]", "total_items": 5 } ``` ### Illustrative output fields Derived from the sample above for orientation only. These fields are not a fixed response schema. | Path | Observed type | Example | | --- | --- | --- | | `items` | `array` | 3 items | | `items` | `array` | 3 items | | `next_cursor` | `string` | [redacted:token] | | `total_items` | `integer` | 5 | ## Execution behavior A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job. ## Related documentation - [Authentication](https://docs.upscrape.com/docs/api/authentication) - [Jobs and results](https://docs.upscrape.com/docs/api/jobs) - [Errors and retries](https://docs.upscrape.com/docs/api/errors) - [Idempotency](https://docs.upscrape.com/docs/api/idempotency)