API REFERENCE

Monitor Task Ad Details API

POST/open-api/v1/ad-monitor-task/ad-details/{ad_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 POST 'https://api.ppspy.com/open-api/v1/ad-monitor-task/ad-details/2413709115670604' \
--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
ad_id path · required	string	Ad ID \|

Response example

Response · JSON

{
    "code": 200,
    "message": "success",
    "data": {
        "advertisement": {
            "id": "2413709115670604",
            "active_days": 1,
            "ad_audience": null,
            "ad_audience_reach": null,
            "ad_link": "https:\/\/www.facebook.com\/ads\/library\/?id=2413709115670604",
            "ad_content": "Workwear just got a whole lot cuter, and EASIER 👏🏻 \n\nComment WANT for the link! \n\n#MidsizeStyle #MidsizeFashion #MidsizeOutfit #MidsizeWorkwear #WorkwearStyle #WorkwearFashion #OfficeOOTD #ChicAndComfy #OOTDInspo #StyleForAll #EverydayStyle #WorkwearLooks #MidsizeConfidence #RealisticStyle #BodyPositiveFashion #OfficeChic #MidsizeBabe #WearToWork #AffordableStyle #WorkwearWardrobe #bloomchic #bloomchicfashion",
            "ad_cost": null,
            "impression": null,
            "ad_cost_min": null,
            "ad_cost_max": null,
            "estimated_conversion_min": null,
            "estimated_conversion_max": null,
            "ad_forecast": 1,
            "ad_platform": [
                "FACEBOOK",
                "INSTAGRAM",
                "AUDIENCE_NETWORK",
                "MESSENGER",
                "THREADS"
            ],
            "ad_started_at": 1761289200,
            "ad_ended_at": 1761289200,
            "ad_status": 1,
            "adset_count": 1,
            "advertiser": {
                "id": "100842618611379",
                "ad_count": 42579,
                "ad_country": [],
                "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=100842618611379",
                "adset_count": null,
                "like_count": 579749,
                "name": "BloomChic",
                "profile_picture_url": "https:\/\/cdn.pipidata.com\/images\/62010c88ca72922575428f938eda7b1e.png",
                "source_advertiser_id": "100842618611379",
                "source_advertiser_link": null,
                "e_commerce_platform": null
            },
            "button_type": "SHOP_NOW",
            "cards": null,
            "country": null,
            "first_discovered_at": 1761314043,
            "images": null,
            "landing_page_type": 2,
            "landing_pages": [
                "https:\/\/bloomchic.com\/collections\/bloom-dress?sort_by=geometric-print-waist-cinched-tiered-midi-dress"
            ],
            "language": null,
            "last_discovered_at": 1761314043,
            "latest_actived_at": 1761289200,
            "media_format": 1,
            "ad_caption": "bloomchic.com",
            "ad_title": null,
            "ad_link_description": null,
            "button_text": "Shop now",
            "products": null,
            "source_ad_id": null,
            "store": {
                "id": "f65b3d7c58eb2b3fe1a54854ccfbadc9",
                "ad_count": 51299,
                "logo_url": "http:\/\/bloomchic.com\/cdn\/shop\/files\/20240102-144940_32x32.png?v=1704178240",
                "name": "BloomChic",
                "source_store_link": "https:\/\/bloomchic.com",
                "e_commerce_platform": "shopify",
                "e_commerce_types": null
            },
            "videos": [
                {
                    "cover_url": "https:\/\/cdn.pipidata.com\/images\/e330a7b0eb5c67ea9f7eb6645f31b758.png",
                    "duration": 45,
                    "height": 1280,
                    "url": "https:\/\/cdn.pipidata.com\/videos\/9bd5c12419cf03228dca988c0bf75822.mp4",
                    "width": 720
                }
            ]
        },
        "ads_history": {
            "ad_active_day": {
                "timeline": [
                    {
                        "count": 1,
                        "date": "2025-10-24"
                    }
                ]
            },
            "ad_cost": {
                "timeline": [
                    {
                        "count": 0,
                        "date": "2025-10-24"
                    }
                ]
            },
            "adset_count": {
                "timeline": [
                    {
                        "count": 1,
                        "date": "2025-10-24"
                    }
                ]
            }
        }
    },
    "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	Ad Data	none
»»» id	string	true	none	Ad ID	none
»»» country	[string]¦null	true	none	Country/Region	none
»»» adset_count	integer	true	none	Ad Set Count	none
»»» ad_audience_reach	integer¦null	true	none	Audience Reach	none
»»» ad_cost	number¦null	true	none	Ad Spend	Currency: USD
»»» ad_ended_at	integer¦null	true	none	Ad End Time	Timestamp in seconds.
»»» ad_started_at	integer¦null	true	none	Ad Creation Time	Timestamp in seconds.
»»» latest_actived_at	integer¦null	true	none	Ad Last Active Time	Timestamp in seconds.
»»» first_discovered_at	integer¦null	true	none	Ad First Discovered Time	Timestamp in seconds.
»»» last_discovered_at	integer	true	none	Ad Last Updated Time	Timestamp in 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 URL	none
»»» ad_status	integer¦null	true	none	Active Status	Options: 1-Active, 2-Stopped, 3-Removed.
»»» ad_forecast	integer¦null	true	none	Ad Forecast	Options: 1-Testing Phase, 2-Growth Phase, 3-Profit Phase.
»»» ad_platform	[string]¦null	true	none	Ad Platform	none
»»» ad_audience	object¦null	true	none	Audience	none
»»»» total_reach	integer	true	none	Total Audience Reach	none
»»»» gender_audience	string¦null	true	none	Audience Gender	none
»»»» age_audience	object	true	none	Audience Age Range	none
»»»»» min	integer¦null	true	none		none
»»»»» max	integer¦null	true	none		none
»»»» details	[object]	true	none	Audience Country Details	none
»»»»» country	string	true	none	Country	none
»»»»» total_reach	integer	true	none	Audience Count	none
»»»»» age_gender_breakdowns	[object]	true	none	Audience Details	none
»»»»»» age_range	string¦null	true	none	Age Range	none
»»»»»» male	integer¦null	true	none	Male Count	none
»»»»»» female	integer¦null	true	none	Female Count	none
»»»»»» unknown	integer¦null	true	none	Other Count	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 Landing Page, 2-Collection Landing Page, 3-Other.
»»» products	[object]¦null	true	none	Ad Products	none
»»»» id	string	true	none		none
»»»» name	string	true	none	Product Name	none
»»»» price	number	true	none	Product Price	none
»»»» price_usd	number	true	none	Product Price (USD)	none
»»»» ad_count	integer	true	none	Product Ad Creative Count	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	none
»»»» image_url	string¦null	true	none	Product Image	none
»»»» ad_started_at	integer	true	none	Ad Start Time	none
»»»» ad_ended_at	integer	true	none	Ad End Time	none
»»»» ad_cost	number¦null	true	none	Ad Spend	none
»»»» total_revenue	number¦null	true	none	Product Revenue	none
»»»» ad_cost_ratio	number¦null	true	none	Product Ad Spend Ratio	none
»»»» currency	string¦null	true	none	Currency	none
»»» advertiser	object¦null	true	none	Advertiser	none
»»»» id	string	true	none		none
»»»» source_advertiser_id	string	true	none	Page ID	none
»»»» name	string	true	none	Advertiser Page Name	none
»»»» ad_count	integer	true	none	Advertiser Page Creative Count	none
»»»» like_count	integer¦null	true	none	Advertiser Page Likes	none
»»»» profile_picture_url	string¦null	true	none	Advertiser Profile Picture URL	none
»»»» source_advertiser_link	string¦null	true	none	Advertiser Source Link	none
»»»» adset_count	integer¦null	true	none	Ad Set Count	none
»»»» e_commerce_platform	string¦null	true	none	E-commerce Platform	none
»»»» ad_country	[string]	true	none	Target Countries	none
»»»» ads_library_link	string	true	none	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 Image 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	none
»»» cards	[object]	true	none	Carousel	none
»»»» media_type	integer	true	none	Media Type	Options: 1-Video, 2-Image.
»»»» url	string	true	none	Video/Image URL	none
»»»» cover_url	string¦null	true	none	Video Cover Image URL	none
»»»» width	integer¦null	true	none	Video/Image Width	none
»»»» height	integer¦null	true	none	Video/Image Height	none
»»»» duration	integer¦null	true	none	Video Duration	none
»»» store	object¦null	true	none	Ad Store	none
»»»» id	string	true	none	Store ID	none
»»»» name	string	true	none	Store Name	none
»»»» ad_count	integer	true	none	Store Creative Count	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 Image	none
»»»» source_store_link	string¦null	true	none	Store Link	none
»» ads_history	object	true	none	Ad History	none
»»» adset_count	object	true	none	Ad Set Count	none
»»»» timeline	[object]	true	none	Timeline	none
»»»»» date	string	true	none	Date	none
»»»»» 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	none
»»»»» count	number	true	none	Count	none
» 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: Monitor Task Ad Details
Request Method: POST
API URL: /open-api/v1/ad-monitor-task/ad-details/{ad_id}
Usage Note: Free