Ads Library · Advertisement List API

Request headers

AUTHORIZATIONAuthorization: {API Key}

CONTENT-TYPEapplication/json

ACCEPTapplication/json

Request example

cURL

curl --location --request POST 'https://api.ppspy.com/open-api/v1/advertisements/search' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}' \
--data-raw '{
    "per_page": 2,
    "with_ad_status_group": "",
    "search_after": ""
}'

Request parameters 59 fields

Pass each parameter in its specified location.

Parameter	Type	Description
body body · optional	object	\|
» extend_keywords body · optional	[object]	Keyword Search \|
»» field body · required	string	Search Field \| Options: `all`, `ad_content`, `landing_pages`, `advertiser_name`, `product_name`
»» value body · required	string	Search Value \|
»» logic_operator body · required	string	Logic Operator \| Options: `and`, `or`
» exclude_keywords body · optional	[object]	Exclude Keywords \|
»» field body · required	string	Search Field \| Options: `all`, `ad_content`, `landing_pages`, `advertiser_name`, `product_name`
»» value body · required	string	Search Value \|
»» logic_operator body · required	string	Logic Operator \| Options: `and`, `or`
» source_ad_id body · optional	[string]	Ad Creative ID \|
» source_advertiser_id body · optional	string	Advertiser Page ID \|
» advertiser_id body · optional	string	Advertiser ID \|
» first_discovered_at_start body · optional	integer	First Discovery Time (Start) \| Unix timestamp (seconds)
» first_discovered_at_end body · optional	integer	First Discovery Time (End) \| Unix timestamp (seconds)
» last_discovered_at_start body · optional	integer	Last Updated Time (Start) \| Unix timestamp (seconds)
» last_discovered_at_end body · optional	integer	Last Updated Time (End) \| Unix timestamp (seconds)
» country body · optional	[string]	Region \|
» language body · optional	[string]	Language \|
» ad_audience_reach_start body · optional	integer	Audience Reach (Start) \|
» ad_audience_reach_end body · optional	integer	Audience Reach (End) \|
» ad_cost_start body · optional	number	Ad Spend (Start) \| In USD
» ad_cost_end body · optional	number	Ad Spend (End) \| In USD
» adset_count_start body · optional	integer	Ad Sets Count (Start) \|
» adset_count_end body · optional	integer	Ad Sets Count (End) \|
» ad_forecast body · optional	[integer]	AI Score \| Options: `1`-Testing, `2`-Growth, `3`-Profitable
» media_format body · optional	[integer]	Media Format \| Options: `1`-Video, `2`-Image, `3`-Carousel
» video_duration_start body · optional	integer	Video Duration (Start) \| In seconds
» video_duration_end body · optional	integer	Video Duration (End) \| In seconds
» e_commerce_platform body · optional	[string]	E-commerce Platform \|
» ad_started_at_start body · optional	integer	Ad Start Time (Start) \| Unix timestamp (seconds)
» ad_started_at_end body · optional	integer	Ad Start Time (End) \| Unix timestamp (seconds)
» latest_actived_at_start body · optional	integer	Last Active Time (Start) \| Unix timestamp (seconds)
» latest_actived_at_end body · optional	integer	Last Active Time (End) \| Unix timestamp (seconds)
» active_days_start body · optional	integer	Active Days (Start) \|
» active_days_end body · optional	integer	Active Days (End) \|
» button_type body · optional	string	Button Type \|
» button_text body · optional	[string]	Button Text \|
» ad_status body · optional	[integer]	Ad Status \| Options: `1`-Running, `2`-Stopped, `3`-Removed
» ad_platform body · optional	[string]	Ad Platform \|
» landing_page_type body · optional	[integer]	Landing Page Type \| Options: `1`-Product, `2`-Collection, `3`-Other
» related_product_ids body · optional	[string]	Product IDs \|
» product_category_id body · optional	[string]	Product Category \|
» product_price_usd_start body · optional	number	Product Price (Start) \| In USD
» product_price_usd_end body · optional	number	Product Price (End) \| In USD
» product_creation_time_start body · optional	integer	Product Creation Time (Start) \| Unix timestamp (seconds)
» product_creation_time_end body · optional	integer	Product Creation Time (End) \| Unix timestamp (seconds)
» product_ad_count_start body · optional	integer	Product Ad Count (Start) \|
» product_ad_count_end body · optional	integer	Product Ad Count (End) \|
» related_store_ids body · optional	[string]	Store IDs \|
» store_ad_count_start body · optional	integer	Store Ad Count (Start) \|
» store_ad_count_end body · optional	integer	Store Ad Count (End) \|
» advertiser_ad_count_start body · optional	integer	Advertiser Ad Count (Start) \|
» advertiser_ad_count_end body · optional	integer	Advertiser Ad Count (End) \|
» order_by body · optional	string	Sort Field \| Options: `ad_started_at`, `adset_count`, `ad_audience_reach`, `last_discovered_at`, `ad_cost`, `advertiser_ad_count`, `product_price_usd`, `product_ad_count`, `product_creation_time`, `active_days`
» direction body · optional	string	Sort Direction \| Options: `desc`, `asc`
» page body · optional	integer	Page Number \| Min: `1`
» per_page body · optional	integer	Page Size \| Range: `1-100`
» with_ad_status_group body · optional	string	Include Ad Status Stats \|
» search_after body · optional	string	Deep Pagination Cursor \| Required for deep pagination (pass empty string `""` for first page)

Response example

Response · JSON

{
    "code": 200,
    "message": "success",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": "00f5f0c2b0ce40761647d7a5d7e75513",
                "advertiser_id": "3090fedf58920c291647d7a5d7e75513",
                "source_ad_id": "1105227591029056",
                "ad_source": 1,
                "ad_content": "🔥 Enjoy 30% OFF! 🔥 Elevate the kitchen experience with the 360° Touch Sensor Faucet – where sleek design meets unmatched convenience. Tap 'Shop Now' to grab it before the offer ends!",
                "ad_link": "https://www.facebook.com/ads/library/?id=1105227591029056",
                "first_discovered_at": 1731337040,
                "last_discovered_at": 1731337040,
                "country": [
                    "other"
                ],
                "language": "en",
                "adset_count": 2,
                "ad_forecast": 1,
                "media_format": 1,
                "images": [],
                "videos": [
                    {
                        "url": "https://fb-cdn.pipiads.com/videos/37a439989b2f6519b00b84a662776863.mp4",
                        "width": 720,
                        "height": 1280,
                        "duration": 22,
                        "cover_url": "https://fb-cdn.pipiads.com/images/c41d740f3cf32a0845e37d178f25da8c.png"
                    }
                ],
                "cards": [],
                "e_commerce_platform": "shopify",
                "ad_started_at": 1730880000,
                "ad_ended_at": 1730880000,
                "latest_actived_at": 1730880000,
                "active_days": 1,
                "button_type": "SHOP_NOW",
                "ad_status": 1,
                "ad_platform": [
                    "FACEBOOK",
                    "INSTAGRAM",
                    "AUDIENCE_NETWORK",
                    "MESSENGER"
                ],
                "landing_page_type": 3,
                "landing_pages": [
                    "https://thetrendygenie.com/products/aquaflex-3-in-1-touch-360-waterfall-kitchen-faucet?_pos=2&_sid=4ae83932e&_ss=r"
                ],
                "related_product_ids": null,
                "e_commerce_types": null,
                "related_store_ids": null,
                "store_adset_count": null,
                "ad_audience": null,
                "ad_audience_reach": null,
                "ad_cost": null,
                "button_text": "Shop now",
                "ad_title": "⭐⭐⭐⭐⭐4.8/5",
                "advertiser": {
                    "id": "3090fedf58920c291647d7a5d7e75513",
                    "source_advertiser_id": "341566439037032",
                    "name": "The Trendy Genie",
                    "like_count": 4248,
                    "ad_count": 5,
                    "profile_picture_url": "https://fb-cdn.pipiads.com/images/35f750aa7026188e51f447e6572e9c07.png",
                    "source_advertiser_link": "https://facebook.com/61559353875301",
                    "adset_count": 7,
                    "e_commerce_platform": "shopify",
                    "ad_country": [
                        "other"
                    ],
                    "user_blocked": 2,
                    "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=341566439037032"
                },
                "store": null,
                "products": [],
                "user_collected": 2
            },
            {
                "id": "06791ffeb1266589614c026fc1b67094",
                "advertiser_id": "6963d214a28ad4e5614c026fc1b67094",
                "source_ad_id": "449661834809540",
                "ad_source": 1,
                "ad_content": "You’re a shining star!💫 Get yourself something special using code SINGLES for an extra 11% off hair care, styling tools, and Value Sets. The Singles Day Sale ends 11/12/24.",
                "ad_link": "https://www.facebook.com/ads/library/?id=449661834809540",
                "first_discovered_at": 1731337037,
                "last_discovered_at": 1731337037,
                "country": [
                    "other"
                ],
                "language": "en",
                "adset_count": 1,
                "ad_forecast": 1,
                "media_format": 2,
                "images": [
                    {
                        "url": "https://fb-cdn.pipiads.com/images/c0a551aac5a6e65a8956d77be7b3740c.png",
                        "width": 1080,
                        "height": 1350
                    }
                ],
                "videos": [],
                "cards": [],
                "e_commerce_platform": "shopify",
                "ad_started_at": 1730880000,
                "ad_ended_at": 1730880000,
                "latest_actived_at": 1730880000,
                "active_days": 1,
                "button_type": "SHOP_NOW",
                "ad_status": 1,
                "ad_platform": [
                    "FACEBOOK",
                    "INSTAGRAM",
                    "AUDIENCE_NETWORK",
                    "MESSENGER"
                ],
                "landing_page_type": 3,
                "landing_pages": [
                    "http://t.langehair.com/SHJME"
                ],
                "related_product_ids": null,
                "e_commerce_types": null,
                "related_store_ids": null,
                "store_adset_count": null,
                "ad_audience": null,
                "ad_audience_reach": null,
                "ad_cost": null,
                "button_text": "Shop now",
                "ad_title": "The Singles Day Sale!💫",
                "advertiser": {
                    "id": "6963d214a28ad4e5614c026fc1b67094",
                    "source_advertiser_id": "588069391390106",
                    "name": "L'ange",
                    "like_count": 1174217,
                    "ad_count": 7,
                    "profile_picture_url": "https://fb-cdn.pipiads.com/images/c40e505f672b7377d1e5dd03207fa80d.png",
                    "source_advertiser_link": "https://facebook.com/getlange",
                    "adset_count": 14,
                    "e_commerce_platform": "shopify",
                    "ad_country": [
                        "other",
                        "US",
                        "FR"
                    ],
                    "user_blocked": 2,
                    "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=588069391390106"
                },
                "store": null,
                "products": [],
                "user_collected": 2
            }
        ],
        "last_page": 8096,
        "per_page": 2,
        "to": 2,
        "total": 16191,
        "ad_status_group": {
            "ad_status_all": 16191,
            "ad_status_1": 15993,
            "ad_status_2": 11,
            "ad_status_3": 187
        },
        "search_after": [
            1730880000,
            "06791ffeb1266589614c026fc1b67094"
        ],
        "has_more": true
    },
    "credits": {
        "remaining_credits": 745,
        "consumed_credits": 0,
        "total_credits": 745
    }
}

Example data from the existing documentation

Response structure

Name	Type	Required	Constraints	Display Name	Description
» code	integer	true	none	Business status code
» message	string	true	none	Message
» data	object	true	none	Response Data
»» current_page	integer	true	none	Current Page
»» data	[object]	true	none	Data List
»»» id	string	true	none	Ad ID
»»» source_ad_id	string	true	none	Ad Creative ID
»»» country	[string] \| null	true	none	Region
»»» adset_count	integer	true	none	Ad Sets Count
»»» ad_audience_reach	integer \| null	true	none	Audience Reach
»»» ad_cost	number \| null	true	none	Ad Spend
»»» ad_ended_at	integer \| null	true	none	Ad End Time	Unix timestamp (seconds)
»»» ad_started_at	integer \| null	true	none	Ad Start Time	Unix timestamp (seconds)
»»» latest_actived_at	integer \| null	true	none	Last Active Time	Unix timestamp (seconds)
»»» first_discovered_at	integer \| null	true	none	First Discovery Time	Unix timestamp (seconds)
»»» last_discovered_at	integer	true	none	Last Updated Time	Unix timestamp (seconds)
»»» ad_content	string \| null	true	none	Ad Copy
»»» active_days	integer \| null	true	none	Active Days
»»» landing_pages	[string] \| null	true	none	Landing Page URLs
»»» ad_status	integer \| null	true	none	Ad Status	Options: `1`-Running, `2`-Stopped, `3`-Removed
»»» ad_forecast	integer \| null	true	none	AI Score
»»» ad_platform	[string] \| null	true	none	Ad Platform
»»» ad_audience	object \| null	true	none	Audience Details
»»»» total_reach	integer	true	none	Total Reach
»»»» gender_audience	string \| null	true	none	Gender
»»»» age_audience	object	true	none	Age Range
»»»»» min	integer \| null	true	none	Min Age
»»»»» max	integer \| null	true	none	Max Age
»»»» details	[object]	true	none	Regional Breakdown
»»»»» country	string	true	none	Region
»»»»» total_reach	integer	true	none	Reach
»»»»» age_gender_breakdowns	[object]	true	none	Demographic Details
»»»»»» age_range	string \| null	true	none	Age Range
»»»»»» male	integer \| null	true	none	Male
»»»»»» female	integer \| null	true	none	Female
»»»»»» unknown	integer \| null	true	none	Unknown
»»» language	string \| null	true	none	Language
»»» media_format	integer \| null	true	none	Media Format
»»» button_type	string \| null	true	none	Button Type
»»» landing_page_type	integer \| null	true	none	Landing Page Type
»»» products	[object] \| null	true	none	Products
»»»» id	string	true	none	Product ID
»»»» name	string	true	none	Product Name
»»»» price	number	true	none	Price
»»»» price_usd	number	true	none	Price (USD)
»»»» ad_count	integer	true	none	Ad Count
»»»» category_id	string \| null	true	none	Category ID
»»»» category_name	string \| null	true	none	Category Name
»»»» creation_time	integer \| null	true	none	Creation Time
»»»» image_url	string \| null	true	none	Image URL
»»»» ad_started_at	integer	true	none	Ad Start Time
»»»» ad_ended_at	integer	true	none	Ad End Time
»»»» ad_cost	number \| null	true	none	Ad Spend	In USD
»»»» total_revenue	number \| null	true	none	Revenue	In USD
»»»» ad_cost_ratio	number \| null	true	none	Ad Spend Ratio	Range: `0~1`
»»»» currency	string \| null	true	none	Currency
»»»» source_product_link	string	true	none	Product Link
»»» advertiser	object \| null	true	none	Advertiser
»»»» id	string	true	none	Advertiser ID
»»»» source_advertiser_id	string	true	none	Advertiser Page ID
»»»» name	string	true	none	Advertiser Name
»»»» ad_count	integer	true	none	Ad Count
»»»» like_count	integer \| null	true	none	Likes
»»»» profile_picture_url	string \| null	true	none	Profile Image
»»»» source_advertiser_link	string \| null	true	none	Profile Link
»»»» adset_count	integer \| null	true	none	Ad Sets Count
»»»» e_commerce_platform	string \| null	true	none	E-commerce Platform
»»»» ad_country	[string]	true	none	Target Countries
»»»» user_blocked	integer	true	none	Blocked Status	`1`-Yes, `2`-No
»»»» ads_library_link	string	true	none	Ads Library Link
»»» images	[object]	true	none	Images
»»»» url	string	true	none	Image URL
»»»» width	integer \| null	true	none	Width
»»»» height	integer \| null	true	none	Height
»»» videos	[object]	true	none	Videos
»»»» url	string	true	none	Video URL
»»»» cover_url	string \| null	true	none	Thumbnail URL
»»»» width	integer \| null	true	none	Width
»»»» height	integer \| null	true	none	Height
»»»» duration	integer \| null	true	none	Duration	In seconds
»»» cards	[object]	true	none	Carousels
»»»» media_type	integer	true	none	Media Type	Options: `1`-Video, `2`-Image
»»»» url	string	true	none	Media URL
»»»» cover_url	string \| null	true	none	Thumbnail URL
»»»» width	integer \| null	true	none	Width
»»»» height	integer \| null	true	none	Height
»»»» duration	integer \| null	true	none	Duration	In seconds
»»» store	object \| null	true	none	Store
»»»» id	string	true	none	Store ID
»»»» name	string	true	none	Store Name
»»»» ad_count	integer	true	none	Ad Count
»»»» e_commerce_platform	string \| null	true	none	E-commerce Platform
»»»» e_commerce_types	[integer] \| null	true	none	E-commerce Types	Options: `1`-Dropshipping, `2`-POD, `3`-COD, `4`-Digital Products
»»»» logo_url	string \| null	true	none	Logo URL
»»»» source_store_link	string \| null	true	none	Store Link
»»» user_collected	integer	true	none	Saved Status	`1`-Not Saved, `2`-Saved
»»» button_text	string \| null	true	none	Button Text
»»» ad_title	string \| null	true	none	Ad Title
»» last_page	integer	true	none	Last Page
»» per_page	integer	true	none	Page Size
»» total	integer	true	none	Total Records
»» ad_status_group	object \| null	false	none	Ad Status Stats	Returned if `with_ad_status_group` is set
»»» ad_status_all	integer	true	none	Total
»»» ad_status_1	integer	true	none	Running
»»» ad_status_2	integer	true	none	Stopped
»»» ad_status_3	integer	true	none	Removed
»» search_after	[any]	false	none	Pagination Cursor	Returned if `search_after` is used
»» has_more	boolean	false	none	More Pages	Returned if `search_after` is used
» credits	object	true	none	Credits information	Credits information for the current API request
»» remaining_credits	integer	true	none	Remaining credits	Remaining credits after this request
»» consumed_credits	integer	true	none	Consumed credits	Credits consumed by this request
»» total_credits	integer	true	none	Total credits	Total credits of the current credits type

Advertisement List API

Request headers

Request example

Request parameters 59 fields

Response example

Response structure

Base URLs

API Information