# Search Ads Library Searches the public Facebook Ads Library by advertiser or keyword, filtered by country and active or inactive status. - Platform: [Facebook](https://docs.upscrape.com/docs/platforms/facebook) - Capability ID: `facebook.ads-library.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": { "query": "Meta AI" }, "capability": "facebook.ads-library.search" }' ``` ## Input | Field | Type | Required | Description | | --- | --- | --- | --- | | `active_status` | `string` | No | Only active ads (default), only inactive ads, or both Allowed values: `active`, `inactive`, `all`. Default: `active`. | | `country` | `string` | No | Two-letter country code where the ads ran, or ALL Default: `ALL`. | | `limit` | `integer` | No | Maximum number of ads to return From 1 to 100. Default: `20`. | | `query` | `string` | Yes | Advertiser name or keyword to search in the Facebook Ads Library Default: `Meta AI`. | ### Example input ```json { "query": "Meta AI" } ``` ## 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": "1433408628182273", "ad_id": null, "categories": [ "UNKNOWN" ], "collation_count": 1, "collation_id": "2628619724001492", "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": "222086361593149", "page_is_deleted": false, "page_name": "InfinitePay", "publisher_platform": [ "FACEBOOK", "INSTAGRAM", "MESSENGER" ], "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": "Fazer R$500 em 2 horas vendendo na rua? :moneybag: Vem acompanhar um dia de vendas do Jair Brazza!\nQuem vende na rua sabe: tempo é dinheiro. E perder venda porque o cliente não tem troco? Esquece! Com o Tap da InfinitePay, dá pra aceitar cartão direto no celular e receber via Pix grátis.\n\n✅ Compatível em celulares com NFC, Android10+ ou a partir do iPhone XS.\n\n#promo #InfinitePay #influ #publi" }, "branded_content": null, "brazil_tax_id": "[redacted:brazil_tax_id]", "byline": "", "caption": "www.infinitepay.io", "cards": [], "country_iso_code": null, "cta_text": "Learn more", "cta_type": "LEARN_MORE", "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": "https://www.infinitepay.io/tap", "page_categories": [ "Product/service" ], "page_id": "222086361593149", "page_is_deleted": false, "page_like_count": 185907, "page_name": "InfinitePay", "page_profile_picture_url": "https://scontent-sof1-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=103&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ZdfSCv86j6wQ7kNvwFwmO1E&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-2.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A73B7C0", "page_profile_uri": "https://www.facebook.com/infinitepay/", "root_reshared_post": null, "title": null, "videos": [ { "video_hd_url": "https://video-sof1-2.xx.fbcdn.net/o1/v/t2/f2/m366/[redacted:token].mp4?_nc_cat=107&_nc_sid=b66105&_nc_ht=video-sof1-2.xx.fbcdn.net&_nc_ohc=YItVIDYibuoQ7kNvwFx1RCt&efg=[redacted:token]&ccb=17-1&vs=40321a442a4203d9&_nc_vs=[redacted:token]&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&_nc_zt=28&oh=[redacted:token]&oe=6A73AB99", "video_preview_image_url": "https://scontent-sof1-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=108&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=tGK-M3ulx2YQ7kNvwEPCdVP&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-2.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A738D45", "video_sd_url": "https://video-sof1-1.xx.fbcdn.net/o1/v/t2/f2/m69/[redacted:token].mp4?strext=1&_nc_cat=106&_nc_sid=ef5aa3&_nc_ht=video-sof1-1.xx.fbcdn.net&_nc_ohc=Cjc28mbrt30Q7kNvwF3SlEG&efg=[redacted:token]%3D&ccb=17-1&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&_nc_zt=28&oh=[redacted:token]&oe=6A73AA48", "watermarked_video_hd_url": "", "watermarked_video_sd_url": "" } ] }, "spend": null, "start_date": 1771488000, "state_media_run_label": null, "targeted_or_reached_countries": [], "total_active_time": null }, { "ad_archive_id": "2148393745715005", "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": "108824017345866", "page_is_deleted": false, "page_name": "Meta", "publisher_platform": [ "FACEBOOK", "INSTAGRAM", "MESSENGER" ], "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": "From grocery runs to training for your next marathon, there’s a pair of AI glasses designed for you. Shop the collection now." }, "branded_content": null, "brazil_tax_id": "[redacted:brazil_tax_id]", "byline": null, "caption": "meta.com/ai-glasses/", "cards": [ { "body": "From grocery runs to training for your next marathon, there’s a pair of AI glasses designed for you. Shop the collection now.", "caption": "meta.com", "cta_text": "Shop Now", "cta_type": "SHOP_NOW", "image_crops": [], "link_description": "$247", "link_url": "https://www.meta.com/ai-glasses/wayfarer-matte-black-graphite-polar-gradient", "original_image_url": "https://scontent-sof1-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ctQcsFIyovcQ7kNvwGDV6IE&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A738EFA", "resized_image_url": "https://scontent-sof1-1.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=ctQcsFIyovcQ7kNvwGDV6IE&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A738EFA", "title": "Wayfarer - Large - Matte Black - Gradient Graphite", "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": "From grocery runs to training for your next marathon, there’s a pair of AI glasses designed for you. Shop the collection now.", "caption": "meta.com", "cta_text": "Shop Now", "cta_type": "SHOP_NOW", "image_crops": [], "link_description": "$247", "link_url": "https://www.meta.com/ai-glasses/wayfarer-matte-black-graphite-polar-gradient", "original_image_url": "https://scontent-sof1-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=GfsFa7p-VCEQ7kNvwGHgpRe&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A739899", "resized_image_url": "https://scontent-sof1-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=GfsFa7p-VCEQ7kNvwGHgpRe&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A739899", "title": "Wayfarer - Matte Black - Gradient Graphite", "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": "From grocery runs to training for your next marathon, there’s a pair of AI glasses designed for you. Shop the collection now.", "caption": "meta.com", "cta_text": "Shop Now", "cta_type": "SHOP_NOW", "image_crops": [], "link_description": "$224", "link_url": "https://www.meta.com/ai-glasses/wayfarer-shiny-black-plano-g15-green", "original_image_url": "https://scontent-sof1-2.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=103&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=I8qDQ1jTeXYQ7kNvwE5x5ji&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-2.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A73B226", "resized_image_url": "https://scontent-sof1-2.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=I8qDQ1jTeXYQ7kNvwE5x5ji&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-2.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A73B226", "title": "Wayfarer - Large - Shiny Black - Green", "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://www.meta.com/ai-glasses/shop-all/", "page_categories": [ "Company" ], "page_id": "108824017345866", "page_is_deleted": false, "page_like_count": 106635276, "page_name": "Meta", "page_profile_picture_url": "https://scontent-sof1-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=m5zaGHbWFxwQ7kNvwFeaph1&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A73A069", "page_profile_uri": "https://www.facebook.com/Meta/", "root_reshared_post": null, "title": "{{product.name}}", "videos": [] }, "spend": null, "start_date": 1781679600, "state_media_run_label": null, "targeted_or_reached_countries": [], "total_active_time": null }, { "ad_archive_id": "1576835113754964", "ad_id": null, "categories": [ "UNKNOWN" ], "collation_count": 2, "collation_id": "1626456112064707", "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": true, "is_active": true, "menu_items": [], "page_id": "359717073888008", "page_is_deleted": false, "page_name": "WhatChimp", "publisher_platform": [ "FACEBOOK", "INSTAGRAM", "THREADS" ], "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": "{{product.brand}}" }, "branded_content": null, "brazil_tax_id": "[redacted:brazil_tax_id]", "byline": "", "caption": "whatchimp.com", "cards": [ { "body": "Looking to send personalised bulk messages on WhatsApp without getting banned?\n\nUse the official WhatsApp API with WhatChimp, the 🏆 #1 Official WhatsApp Marketing Platform and a Verified Meta Business Partner.\n\nTrusted by thousands of businesses in 90+ countries, WhatChimp is built for everyone from small startups to large enterprises.\n\n🚨 Lock in Early Bird Pricing for Life starting at just $12/mo…", "caption": "whatchimp.com", "cta_text": "Sign Up", "cta_type": "SIGN_UP", "image_crops": [], "link_description": "🚨 Get (50% OFF) Early-Bird Offer", "link_url": "https://whatchimp.com/special-offer/", "original_image_url": "https://scontent-sof1-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=OR6Cd0vS2SUQ7kNvwG0bzp0&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A73B5B1", "resized_image_url": "https://scontent-sof1-2.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=LOb_QU5lq1QQ7kNvwHhqIJP&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-2.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A739C33", "title": "0% Markup Fees on API", "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": "¿Quieres enviar mensajes personalizados en masa por WhatsApp sin correr el riesgo de que te bloqueen?\n\nUsa la API oficial de WhatsApp con WhatChimp, 🏆 la plataforma oficial número 1 de marketing por WhatsApp y socio verificado de Meta.\n\nCon la confianza de miles de empresas en más de 90 países, WhatChimp está diseñada para todos, desde pequeños negocios hasta grandes empresas.\n\n🚨 Asegura el precio…", "caption": "whatchimp.com", "cta_text": "Sign Up", "cta_type": "SIGN_UP", "image_crops": [], "link_description": "🚨 Consigue un 50% de descuento con la oferta Early-Bird", "link_url": "https://whatchimp.com/special-offer-es/", "original_image_url": "https://scontent-sof1-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=SrbSZIrKUxoQ7kNvwGapHQO&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A73921C", "resized_image_url": "https://scontent-sof1-1.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=DXAf3C1XroUQ7kNvwFL52vE&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A73AE59", "title": "0% de comisión en la API", "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": "Quer enviar mensagens personalizadas em massa no WhatsApp sem correr o risco de ser bloqueado?\n\n\nUse a API oficial do WhatsApp com WhatChimp, 🏆 a plataforma oficial número 1 de marketing no WhatsApp e parceiro verificado da Meta.\n\nConfiada por milhares de empresas em mais de 90 países, a WhatChimp foi criada para todos, desde pequenos negócios até grandes empresas.\n\n🚨 Garanta o preço promocional E…", "caption": "whatchimp.com", "cta_text": "Sign Up", "cta_type": "SIGN_UP", "image_crops": [], "link_description": "🚨 Aproveite 50% OFF na Oferta Antecipada", "link_url": "https://whatchimp.com/special-offer-pt/", "original_image_url": "https://scontent-sof1-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=rjJYb8l13BMQ7kNvwEFYkY4&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A738A3B", "resized_image_url": "https://scontent-sof1-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=3IFqoeJrfbAQ7kNvwGTLrdA&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A7385D4", "title": "0% de Taxa de Markup na API", "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": "Sign up", "cta_type": "SIGN_UP", "disclaimer_label": null, "display_format": "DCO", "ec_certificates": [], "event": null, "extra_images": [], "extra_links": [], "extra_texts": [], "extra_videos": [], "images": [], "is_reshared": false, "link_description": "{{product.description}}", "link_url": "https://whatchimp.com/special-offer-fr/", "page_categories": [ "Business" ], "page_id": "359717073888008", "page_is_deleted": false, "page_like_count": 11938, "page_name": "WhatChimp", "page_profile_picture_url": "https://scontent-sof1-1.xx.fbcdn.net/v/t39.35426-6/[redacted:token].jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=FGunEWBgAuUQ7kNvwHhbsdW&_nc_oc=[redacted:token]&_nc_zt=14&_nc_ht=scontent-sof1-1.xx&_nc_gid=KMbTGHnkuMq-sHasmnvYgg&_nc_ss=7820f&oh=[redacted:token]&oe=6A738CB6", "page_profile_uri": "https://www.facebook.com/whatchimp/", "root_reshared_post": null, "title": "{{product.name}}", "videos": [] }, "spend": null, "start_date": 1762934400, "state_media_run_label": null, "targeted_or_reached_countries": [], "total_active_time": null } ], "summary": { "total_items": 20 } } ``` ### 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 | | `summary` | `object` | 1 fields | | `summary.total_items` | `integer` | 20 | ## 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)