Ad Library List API

API Information

• API Name: Ad Library List Query
• Request Method: POST
• API Address: /open-api/v1/data
• API Path: /v3/api/open/lib-ads/list
• API Description: Retrieve ad library list data with multi-dimensional filtering and pagination support, suitable for ad analysis, competitor research, creative mining, and other scenarios
• Pricing: 1 credit per data record retrieved

Request Headers:

• Content-Type: application/json
• Accept: application/json

Request Parameters

Request Structure

Request Body Parameters (params object)

Basic Parameters

Ad Basic Filters

Ad Time Filters

Ad Duration Filters

Ad Data Filters

Advertiser Filters

Button Filters

Media Creative Filters

Audience Filters

Landing Page Filters

E-commerce Platform Filters

Product Filters

Store Filters

App Filters

Keyword Search

Exclusion Filters

Advanced Options

Request Example

curl -X POST "https://www.pipispy.com/open-api/v1/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/open/lib-ads/list",
    "params": {
      "page": 1,
      "per_page": 20,
      "ad_platform": "FACEBOOK",
      "ad_status": "1",
      "country": "US",
      "ad_cost_start": 100,
      "ad_cost_end": 1000,
      "extend_keywords": [
        {
          "field": "ad_content",
          "value": "sale",
          "logic_operator": "and"
        }
      ],
      "order_by": "ad_started_at",
      "direction": "desc",
      "with_ad_status_group": "true"
    }
  }'

Response Parameters

Response Body Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "ad_started_at_group": {},
    "ad_status_group": {},
    "current_page": 1,
    "data": [],
    "first_page_url": "",
    "from": 1,
    "last_page": 10,
    "last_page_url": "",
    "next_page_url": "",
    "path": "",
    "per_page": 20,
    "prev_page_url": "",
    "to": 20,
    "total": 200,
    "search_after": [],
    "has_more": false,
    "is_manual_search": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Response Field Description

Pagination Information Fields

First Ad Date Statistics Fields (ad_started_at_group)

When with_ad_started_at_group is set in the request, this field will be included in the response:

Ad Status Statistics Fields (ad_status_group)

When with_ad_status_group is set in the request, this field will be included in the response:

Ad Information Fields (data)

Ad Audience Information Fields (ad_audience)

Audience Age Range Fields (age_audience)

Audience Country Details Fields (details)

Age Gender Breakdown Fields (age_gender_breakdowns)

Advertiser Information Fields (advertiser)

Carousel Information Fields (cards)

Image Information Fields (images)

Video Information Fields (videos)

Product Information Fields (products)

Store Information Fields (store)

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "ad_started_at_group": {
      "today": 10,
      "yesterday": 25,
      "last_7_days": 150,
      "last_30_days": 500,
      "last_90_days": 1200,
      "total": 41166
    },
    "ad_status_group": {
      "ad_status_1": 15000,
      "ad_status_2": 20000,
      "ad_status_3": 6166,
      "ad_status_all": 41166
    },
    "current_page": 1,
    "data": [
      {
        "id": "428822805b9d1826ae0486cb66311288",
        "active_days": 1,
        "ad_audience": {
          "details": [
            {
              "country": "BE",
              "age_gender_breakdowns": [
                {
                  "female": 0,
                  "male": 1,
                  "unknown": 0,
                  "age_range": "25-34"
                }
              ],
              "total_reach": 2
            }
          ],
          "age_audience": {
            "max": 65,
            "min": 25
          },
          "gender_audience": "All",
          "total_reach": 0
        },
        "ad_audience_reach": 0,
        "ad_content": "No knife skills, no stress — just load, press, and boom, you've got sushi 🍱🙌",
        "ad_cost": 1.37,
        "ad_forecast": 1,
        "ad_platform": [
          "FACEBOOK",
          "INSTAGRAM",
          "AUDIENCE_NETWORK",
          "MESSENGER",
          "THREADS"
        ],
        "ad_started_at": 1752130800,
        "ad_status": 2,
        "adset_count": 1,
        "advertiser": {
          "id": "c979c0120e4b6d5dae0486cb66311288",
          "name": "Stumpf Alston Nicholas",
          "ad_count": 643,
          "ad_country": [
            "SE",
            "ES",
            "BE",
            "AT",
            "DE",
            "FR",
            "IT",
            "IE",
            "PT",
            "NL"
          ],
          "ads_library_link": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=127604557091989",
          "adset_count": 1381,
          "e_commerce_platform": "shopify",
          "like_count": 7,
          "profile_picture_url": "https://fb-cdn.pipispy.com/images/af109907042f563cd317a8a64ddce21e.png",
          "source_advertiser_id": "127604557091989",
          "source_advertiser_link": "https://facebook.com/61550723637932",
          "user_blocked": 2
        },
        "button_text": "Shop now",
        "button_type": "SHOP_NOW",
        "cards": [],
        "country": [
          "BE",
          "DE",
          "GB",
          "DK",
          "FI",
          "PT",
          "SE",
          "IE",
          "IT",
          "ES",
          "AT"
        ],
        "first_discovered_at": 1752188451,
        "images": [],
        "landing_page_type": 1,
        "landing_pages": [
          "https://counitty.com/products/ultimate-sushi-making-kit"
        ],
        "language": "en",
        "last_discovered_at": 1752188451,
        "latest_actived_at": 1752130800,
        "media_format": 1,
        "products": [
          {
            "id": "b71e0551cfbb314175c4dac1b4cf2dfc",
            "name": "🍣 Ultimate Sushi Making Kit | Fun for All Ages · Easy to Use · Dishwasher Safe 🎉",
            "ad_count": 7,
            "ad_cost": 15.52,
            "ad_cost_ratio": 0.0883,
            "ad_ended_at": 1752130800,
            "ad_started_at": 1752130800,
            "category_id": "62739b6038365b2f72048ec1",
            "category_name": "Home & Garden",
            "creation_time": 1752134135,
            "currency": "GBP",
            "image_url": "https://fb-cdn.pipispy.com/images/pimg_8372835ac9512990130d7.png",
            "price": 17.0,
            "price_usd": 23.1,
            "source_product_link": "https://counitty.com/products/ultimate-sushi-making-kit"
          }
        ],
        "source_ad_id": "1489834018843759",
        "store": {
          "id": "7458071d08bd6c3c75c4dac1b4cf2dfc",
          "name": "Community Nail Care CenterLTD",
          "ad_count": 421,
          "e_commerce_platform": "shopify",
          "e_commerce_types": [1, 2],
          "logo_url": "https://fb-cdn.pipispy.com/images/store_logo.png",
          "source_store_link": "https://counitty.com",
          "pipiads_biz_id": "biz_123456"
        },
        "user_collected": 2,
        "videos": [
          {
            "duration": 21,
            "height": 1280,
            "url": "https://fb-cdn.pipispy.com/videos/63a2820717c43d00f1481d20af5d0b6d.mp4",
            "width": 720,
            "cover_url": "https://fb-cdn.pipispy.com/images/d38b7ac2a4d956e541d338d84b3d10ae.png"
          }
        ],
        "related_roots": [
          "counitty.com"
        ],
        "favorite_time": 0,
        "group_name": null,
        "store_id": "biz_123456",
        "root_path_id": "root_123",
        "shop_id": null,
        "app_id": null
      }
    ],
    "first_page_url": "http://app.ppspy.com/v1/lib-ads/list?page=1",
    "from": 1,
    "last_page": 2059,
    "last_page_url": "http://app.ppspy.com/v1/lib-ads/list?page=2059",
    "next_page_url": "http://app.ppspy.com/v1/lib-ads/list?page=2",
    "path": "http://app.ppspy.com/v1/lib-ads/list",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 41166,
    "search_after": null,
    "has_more": false,
    "is_manual_search": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Error Code Description

Important Notes

1. Pagination Limits: Recommended page size is 20-100; larger page sizes may affect response time
2. Time Format: All time fields use Unix timestamp (seconds); please convert accordingly
3. Array Parameters: When using array-type filter conditions, results will match any value in the array (OR logic)
4. Range Filters: When using paired start and end parameters, ensure start ≤ end
5. Keyword Search: extend_keywords and exclude_keywords can be used together; inclusion filters are applied first, then exclusion filters
6. Sort Optimization: Recommend specifying order_by and direction parameters; otherwise default sorting (ad_started_at descending) will be used
7. Deep Pagination: For large datasets, recommend using search_after parameter for better performance
8. Statistics Fields: with_ad_status_group and with_ad_started_at_group only affect statistics in the response, not the data list content
9. Data Updates: Ad data is updated regularly; recommend periodic re-querying for latest data
10. Multi-value Parameters: Some fields support multiple comma-separated values, such as country, ad_platform, etc.
11. Keyword Fields: extend_keywords and exclude_keywords support field values including all, ad_content, landing_pages, advertiser_name, product_name, product, store, app_name, app_developer_name, advertiser, material, etc.
12. E-commerce Platforms: e_commerce_platform supports platforms including shopify, woocommerce, magento, prestashop, opencart, bigcommerce, ecwid, shopline, shoplazza, wix, squarespace, etc.