API REFERENCE

Advertisement Details API

GET/open-api/v1/advertisements/{id}

·api.ppspy.com

Data and monitoring usage rules

Points Consumption Rules: 1. Retrieving a Shopify data result consumes 1 data, while retrieving an ad library data result consumes 2 data. Retrieving additional data details for a data result does not consume data. 2. Ad monitoring and sales monitoring: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

Request headers

AUTHORIZATIONAuthorization: {API Key}

CONTENT-TYPEapplication/json

ACCEPTapplication/json

Request example

cURL

curl --location --request GET 'https://api.ppspy.com/open-api/v1/advertisements/e0b433132cf6dbafb09243e4b5fc5fe1' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}'

Request parameters 1 fields

Pass each parameter in its specified location.

Parameter	Type	Description
id path · required	string	Advertisement ID \|

Response example

Response · JSON

{
    "code": 200,
    "message": "success",
    "data": {
        "advertisement": {
            "id": "e0b433132cf6dbafb09243e4b5fc5fe1",
            "advertiser_id": "ed20f6b1d42e31d1b09243e4b5fc5fe1",
            "source_ad_id": "4123806491240834",
            "ad_source": 1,
            "ad_content": "Tired of tanning products that dry out or irritate your skin? Decadence by BeautiEdit changes everything. It’s a luxurious gradual tanning cream that nourishes your skin while adding a radiant gradual glow. \n\nNo streaks, No fuss just a nourishing, hydrated glow to your skin. \n\nMake tanning part of your skin-care routine, try Decadence by Lorraine Keane Today!",
            "ad_link": "https:\/\/www.facebook.com\/ads\/library\/?id=4123806491240834",
            "first_discovered_at": 1754591870,
            "last_discovered_at": 1754591870,
            "country": [
                "GB",
                "IE"
            ],
            "language": "en",
            "adset_count": 4,
            "ad_forecast": 1,
            "media_format": 1,
            "images": [],
            "videos": [
                {
                    "url": "https:\/\/fb-cdn.ppspy.com\/videos\/87d2d6c5c900e5ff035aabc106c8ceaf.mp4",
                    "width": 720,
                    "height": 1280,
                    "duration": 25.633333333333333,
                    "cover_url": "https:\/\/fb-cdn.ppspy.com\/images\/a73b21b9cc50258ba82bdc20d6915943.png"
                }
            ],
            "cards": [],
            "e_commerce_platform": "shopify",
            "ad_started_at": 1754550000,
            "ad_ended_at": 1754550000,
            "latest_actived_at": 1754550000,
            "active_days": 1,
            "button_type": "SHOP_NOW",
            "ad_status": 1,
            "ad_platform": [
                "FACEBOOK",
                "INSTAGRAM",
                "AUDIENCE_NETWORK",
                "MESSENGER",
                "THREADS"
            ],
            "landing_page_type": 1,
            "landing_pages": [
                "https:\/\/www.beautiedit.co.uk\/products\/decadence-by-lorraine-keane"
            ],
            "related_product_ids": [
                "80a48db50a11fbcaf2d7255e126a510d"
            ],
            "e_commerce_types": null,
            "related_store_ids": [
                "e591b0461e390666f2d7255e126a510d"
            ],
            "store_adset_count": null,
            "ad_audience": {
                "details": [
                    {
                        "country": "IE",
                        "total_reach": 13,
                        "age_gender_breakdowns": [
                            {
                                "male": 0,
                                "female": 0,
                                "unknown": 1,
                                "age_range": "18-24"
                            },
                            {
                                "male": 0,
                                "female": 3,
                                "unknown": 0,
                                "age_range": "25-34"
                            },
                            {
                                "male": 0,
                                "female": 4,
                                "unknown": 0,
                                "age_range": "35-44"
                            },
                            {
                                "male": 0,
                                "female": 24,
                                "unknown": 1,
                                "age_range": "45-54"
                            },
                            {
                                "male": 1,
                                "female": 30,
                                "unknown": 2,
                                "age_range": "55-64"
                            },
                            {
                                "male": 0,
                                "female": 13,
                                "unknown": 0,
                                "age_range": "65+"
                            }
                        ]
                    },
                    {
                        "country": "GB",
                        "total_reach": 1,
                        "age_gender_breakdowns": [
                            {
                                "male": 0,
                                "female": 1,
                                "unknown": 0,
                                "age_range": "45-54"
                            },
                            {
                                "male": 0,
                                "female": 1,
                                "unknown": 0,
                                "age_range": "65+"
                            }
                        ]
                    }
                ],
                "total_reach": 80,
                "age_audience": {
                    "max": 65,
                    "min": 18
                },
                "gender_audience": "All"
            },
            "ad_audience_reach": 80,
            "ad_cost": 1.56,
            "ad_caption": "www.beautiedit.co.uk",
            "ad_title": "Hydrate, Nourish, and Radiate your skin",
            "ad_link_description": null,
            "button_text": "Shop now",
            "advertiser": {
                "id": "ed20f6b1d42e31d1b09243e4b5fc5fe1",
                "source_advertiser_id": "105480794477709",
                "name": "BeautiEdit",
                "like_count": 4053,
                "ad_count": 602,
                "profile_picture_url": "https:\/\/fb-cdn.ppspy.com\/images\/596132196b0f1eea5f1783d36d94854e.png",
                "source_advertiser_link": "https:\/\/facebook.com\/BeautiEdit",
                "adset_count": 999,
                "e_commerce_platform": "shopify",
                "ad_country": [
                    "IE",
                    "GB",
                    "other",
                    "LT",
                    "CY",
                    "ES",
                    "FR",
                    "PL",
                    "BG",
                    "PT",
                    "EE",
                    "IT",
                    "GR",
                    "JP"
                ],
                "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=105480794477709",
                "user_blocked": 2
            },
            "size": "9:16",
            "clarity": "FHD",
            "aspect_ratio": "720x1280",
            "products": [
                {
                    "id": "80a48db50a11fbcaf2d7255e126a510d",
                    "store_id": "e591b0461e390666f2d7255e126a510d",
                    "name": "Decadence by Lorraine Keane **Limited Edition**",
                    "source_product_link": "https:\/\/www.beautiedit.com\/products\/decadence-by-lorraine-keane",
                    "currency": "EUR",
                    "price": 30,
                    "price_usd": 34.91,
                    "ad_count": 19,
                    "category_id": "62739ba438365b2f72048ec9",
                    "creation_time": 1668601826,
                    "images": [
                        "images\/pimg_de334c56ff3495f861da.png",
                        "images\/pimg_ce254c9085fdbc6d341b.png",
                        "images\/pimg_9ca2dad76211178d0ec8.png",
                        "images\/pimg_e526af57cf7a09cc281a.png",
                        "images\/pimg_1180eabe98c0101e1abc.png"
                    ],
                    "ad_cost": 436.86,
                    "category": {
                        "id": "62739ba438365b2f72048ec9",
                        "name_en": "Beauty & Health"
                    },
                    "image_url": "https:\/\/fb-cdn.ppspy.com\/images\/pimg_de334c56ff3495f861da.png",
                    "category_name": "Beauty & Health"
                }
            ],
            "store": {
                "id": "e591b0461e390666f2d7255e126a510d",
                "name": "BeautiEdit",
                "ad_count": 599,
                "e_commerce_platform": "shopify",
                "e_commerce_types": null,
                "logo_url": "http:\/\/www.beautiedit.com\/cdn\/shop\/files\/fav.png?v=1667884772&width=180",
                "source_store_link": "https:\/\/www.beautiedit.com",
                "category_ids": [
                    "62739ba438365b2f72048ec9"
                ],
                "categories": [
                    {
                        "id": "62739ba438365b2f72048ec9",
                        "name_en": "Beauty & Health",
                        "name_zh": "美容与健康"
                    }
                ]
            },
            "user_collected": 2
        },
        "ads_history": {
            "adset_count": {
                "timeline": [
                    {
                        "date": "2025-08-07",
                        "count": 4
                    }
                ]
            },
            "ad_cost": {
                "timeline": [
                    {
                        "date": "2025-08-07",
                        "count": 1.56
                    }
                ]
            }
        }
    },
    "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	Response Message	none
» data	object	true	none	Response Data	none
»» advertisement	object	true	none	Advertisement Data	none
»»» id	string	true	none	Advertisement ID	none
»»» source_ad_id	string	true	none	Ad Creative ID	none
»»» country	[string]¦null	true	none	Region	none
»»» adset_count	integer	true	none	Number of Ad Groups	none
»»» ad_audience_reach	integer¦null	true	none	Audience Reach	none
»»» ad_cost	number¦null	true	none	Ad Spend	Unit: USD.
»»» ad_started_at	integer¦null	true	none	Ad Creation Time	Timestamp (seconds).
»»» latest_actived_at	integer¦null	true	none	Last Active Time	Timestamp (seconds).
»»» first_discovered_at	integer¦null	true	none	First Detected Time	Timestamp (seconds).
»»» last_discovered_at	integer	true	none	Last Updated Time	Timestamp (seconds).
»»» ad_content	string¦null	true	none	Ad Copy	none
»»» active_days	integer¦null	true	none	Active Days	none
»»» landing_pages	[string]¦null	true	none	Landing Page URLs	none
»»» ad_status	integer¦null	true	none	Active Status	Options: 1-Running, 2-Stopped, 3-Removed.
»»» ad_forecast	integer¦null	true	none	AI Score	Options: 1-Testing, 2-Growing, 3-Profitable.
»»» ad_platform	[string]¦null	true	none	Ad Platform	none
»»» ad_audience	object¦null	true	none	Audience Coverage	none
»»»» total_reach	integer	true	none	Total Reach	none
»»»» gender_audience	string¦null	true	none	Gender	Options: Women, All, Men, null.
»»»» age_audience	object	true	none	Age Range	none
»»»»» min	integer¦null	true	none	Min Age	none
»»»»» max	integer¦null	true	none	Max Age	none
»»»» details	[object]	true	none	Country Breakdown	none
»»»»» country	string	true	none	Country/Region	none
»»»»» total_reach	integer	true	none	Reach Count	none
»»»»» age_gender_breakdowns	[object]	true	none	Demographics	none
»»»»»» age_range	string¦null	true	none	Age Group	none
»»»»»» male	integer¦null	true	none	Male Count	none
»»»»»» female	integer¦null	true	none	Female Count	none
»»»»»» unknown	integer¦null	true	none	Unknown Gender	none
»»» language	string¦null	true	none	Language	none
»»» media_format	integer¦null	true	none	Media Format	Options: 1-Video, 2-Image, 3-Carousel.
»»» button_type	string¦null	true	none	Button Type	none
»»» landing_page_type	integer¦null	true	none	Landing Page Type	Options: 1-Product, 2-Collection, 3-Other.
»»» products	[object]¦null	true	none	Product List	none
»»»» id	string	true	none	Product ID	none
»»»» name	string	true	none	Product Name	none
»»»» price	number	true	none	Price	none
»»»» price_usd	number	true	none	Price (USD)	none
»»»» ad_count	integer	true	none	Ad Count for Product	none
»»»» category_id	string¦null	true	none	Category ID	none
»»»» category_name	string¦null	true	none	Category Name	none
»»»» creation_time	integer¦null	true	none	Creation Time	Timestamp (seconds).
»»»» image_url	string¦null	true	none	Product Image	none
»»»» currency	string¦null	true	none	Currency	none
»»»» source_product_link	string	true	none	Product Link	none
»»» store	object¦null	true	none	Store	none
»»»» id	string	true	none	Store ID	none
»»»» name	string	true	none	Store Name	none
»»»» ad_count	integer	true	none	Ad Count for Store	none
»»»» e_commerce_platform	string¦null	true	none	E-commerce Platform	none
»»»» e_commerce_types	[integer]¦null	true	none	E-commerce Types	none
»»»» logo_url	string¦null	true	none	Store Logo	none
»»»» source_store_link	string¦null	true	none	Store Link	none
»»»» categories	[object]¦null	true	none	Store Categories	none
»»»»» id	string	true	none	Category ID	none
»»»»» name_en	string	true	none	Category Name (English)	none
»»»»» name_zh	string	true	none	Category Name (Chinese)	none
»»» advertiser	object¦null	true	none	Advertiser	none
»»»» id	string	true	none	Advertiser ID	none
»»»» source_advertiser_id	string	true	none	Advertiser Page ID	none
»»»» name	string	true	none	Advertiser Name	none
»»»» ad_count	integer	true	none	Ad Count for Advertiser	none
»»»» like_count	integer¦null	true	none	Advertiser Likes	none
»»»» profile_picture_url	string¦null	true	none	Profile Picture	none
»»»» source_advertiser_link	string¦null	true	none	Advertiser Page Link	none
»»»» adset_count	integer¦null	true	none	Ad Group Count	none
»»»» e_commerce_platform	string¦null	true	none	E-commerce Platform	none
»»»» user_blocked	integer	true	none	Blocked Status	1-Yes, 2-No.
»»»» ad_country	[string]	true	none	Ad Countries	none
»»»» ads_library_link	string	true	none	Ads Library Link	none
»»» images	[object]	true	none	Images	none
»»»» url	string	true	none	Image URL	none
»»»» width	integer¦null	true	none	Image Width	none
»»»» height	integer¦null	true	none	Image Height	none
»»» videos	[object]	true	none	Videos	none
»»»» url	string	true	none	Video URL	none
»»»» cover_url	string¦null	true	none	Video Cover URL	none
»»»» width	integer¦null	true	none	Video Width	none
»»»» height	integer¦null	true	none	Video Height	none
»»»» duration	integer¦null	true	none	Video Duration	Unit: seconds.
»»» cards	[object]	true	none	Carousel Cards	none
»»»» media_type	integer	true	none	Media Type	Options: 1-Video, 2-Image.
»»»» url	string	true	none	Media URL	none
»»»» cover_url	string¦null	true	none	Video Cover URL	none
»»»» width	integer¦null	true	none	Media Width	none
»»»» height	integer¦null	true	none	Media Height	none
»»»» duration	integer¦null	true	none	Video Duration	Unit: seconds.
»»» ad_caption	string¦null	true	none	Ad Caption	none
»»» ad_title	string¦null	true	none	Ad Title	none
»»» ad_link_description	string¦null	true	none	Link Description	none
»»» ad_link	string¦null	true	none	Ad Link	none
»»» user_collected	integer	true	none	Favorited Status	Options: 1-Not Favorited, 2-Favorited.
»»» button_text	string¦null	true	none	Button Text	none
»»» size	string¦null	true	none	Size Ratio	none
»»» clarity	string¦null	true	none	Clarity	none
»»» aspect_ratio	string¦null	true	none	Resolution	none
»» ads_history	object	true	none	Ad History	none
»»» adset_count	object	true	none	Ad Group Count	none
»»»» timeline	[object]	true	none	Timeline	none
»»»»» date	string	true	none	Date	UTC time.
»»»»» count	number	true	none	Count	none
»»» ad_cost	object	true	none	Ad Spend	none
»»»» timeline	[object]	true	none	Timeline	none
»»»»» date	string	true	none	Date	UTC time.
»»»»» count	number	true	none	Spend	Unit: USD.
» 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

Original API information and base URL

Base URLs

Production Environment: https://api.ppspy.com

API Information

API Name: Ad Product Details
Request Method: GET
API URL: /open-api/v1/advertisements/{id}
Usage Note: Get the id from the Advertisement List API before using this endpoint. If the id expires, get a new one or you'll get error 403002.