Facebook API Capability

Search Ads Library

Searches the public Facebook Ads Library by advertiser or keyword, filtered by country and active or inactive status.

Capability ID facebook.ads-library.search

Cost From $1.25 per 1,000 requests · 1 credit

Maximum runtime 120 seconds

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

POST /execute Shared execution endpoint

Input parameters

active_status string optional

Only active ads (default), only inactive ads, or both Allowed values: `active`, `inactive`, `all`. Default: `active`.

Example active

Available values activeinactiveall

country string optional

Two-letter country code where the ads ran, or ALL Default: `ALL`.

Example US

limit integer optional

Maximum number of ads to return From 1 to 100. Default: `20`.

Example 20

query string required

Advertiser name or keyword to search in the Facebook Ads Library Default: `Meta AI`.

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 example response is shown in the response panel.

Illustrative output fields

Values illustrate one response. Read the guidance above for missing values and limits; fields can vary with the requested operation and the data available.

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 $UPSCRAPE_API_KEY" \ --header "Content-Type: application/json" \ --header "Prefer: wait=30" \ --data '{ "input": { "query": "Meta AI" }, "capability": "facebook.ads-library.search" }'

import json import os 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": f"Bearer {os.environ['UPSCRAPE_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 } }