Facebook API Capability

Search Ads Library

Searches the public Facebook Ads Library for active ads by advertiser or keyword.

Capability ID facebook.ads-library.search

Cost 1 credit per request

Maximum runtime 120 seconds

# Search Ads Library

Searches the public Facebook Ads Library for active ads by advertiser or keyword.

- 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 YOUR_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 |
| --- | --- | --- | --- |
| `limit` | `integer` | No | Maximum number of ads to return |
| `query` | `string` | Yes | Advertiser name or keyword to search in the Facebook Ads Library |

### 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 redacted fixture is an example, not a fixed response schema.

```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)

POST /execute Shared execution endpoint

Input parameters

limit integer optional

Maximum number of ads to return

Example 20

query string required

Advertiser name or keyword to search in the Facebook Ads Library

Example 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 The full redacted fixture is shown in the response panel.

Illustrative output fields

Derived from the sample above for orientation only. These observed 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.

curl --request POST \ --url https://data.upscrape.com/execute \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --header "Prefer: wait=30" \ --data '{ "input": { "query": "Meta AI" }, "capability": "facebook.ads-library.search" }'

import json import requests payload = json.loads(r'''{ "input": { "query": "Meta AI" }, "capability": "facebook.ads-library.search" }''') response = requests.post( "https://data.upscrape.com/execute", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", "Prefer": "wait=30", }, json=payload, ) response.raise_for_status() print(json.dumps(response.json(), indent=2))

{ "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 } }