Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: 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.

Advertisement Library Detail API

API Information

  • API Name: Get Advertisement Library Detail
  • Request Method: POST
  • API URL: /open-api/v1/data
  • Interface URI path: /v3/api/open/lib-ads/detail
  • Description: Get detailed advertisement information by advertisement ID, including advertisement history change data
  • Pricing: Details API pricing rules: Base fee: 1 credit/request. Free access conditions (if either is met): Details for this ID have been retrieved within the past 3 days; This ID appeared in your leaderboard list query results within the past 3 days.

Request Headers:

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

Request Parameters

Request Structure

Parameter Name Type Description Example Required Default
key string User's external API request key "your_api_key_here" Yes
uri string Interface URI path "/v3/api/open/lib-ads/detail" Yes
params object Interface parameter object See parameter list below Yes

Parameter List (params object)

Parameter Name Type Description Example Required Default
id string Advertisement ID, unique identifier in system "06c7df340f26f2539c8dada9fa5afe27" Yes

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/detail",
    "params": {
      "id": "06c7df340f26f2539c8dada9fa5afe27"
    }
  }'

Response

Response Body Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "ads_history": {
      // Advertisement history change data
    },
    "advertisement": {
      // Detailed advertisement information
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}

Response Field Description

Main Response Fields
Field Name Type Description
ads_history object Advertisement history change data
advertisement object Detailed advertisement information
version string API version number
timestamp long Response timestamp
sign string Response signature
remaining_credits number Current remaining available credits after this request
consumed_credits number Credits consumed by this request
success boolean Whether the request was successful
fail boolean Whether the request failed
Field Name Type Description
ad_cost object Advertisement cost history data
adset_count object Adset count history data
History Data Timeline Fields (timeline)
Field Name Type Description
count double Value
date string Date (YYYY-MM-DD format)
Field Name Type Description
id string Advertisement ID, unique identifier in system
active_days long Advertisement duration
ad_audience object Advertisement audience information
ad_audience_reach long Advertisement reach
ad_caption string Advertisement description
ad_content string Advertisement content
ad_cost double Advertisement cost
ad_forecast long Advertisement forecast status (1:Testing 2:Scaling 3:Winning)
ad_link string Advertisement link
ad_link_description string Advertisement link description
ad_platform array Advertisement platforms list
ad_started_at long Advertisement creation time
ad_status long Advertisement status (1:Active 2:Inactive 3:Removed)
ad_title string Advertisement title
adset_count long Adset count
advertiser object Advertiser information
button_text string Button text
button_type string Button type
cards array Carousel list
country array Target countries list
first_discovered_at long First discovered time
images array Advertisement images list
landing_page_type long Landing page type
landing_pages array Landing page URLs list
language string Advertisement language
last_discovered_at long Last updated time
latest_actived_at long Latest active time
media_format long Media format type
products array Advertisement products list
source_ad_id string Source ad ID
store object Advertisement store information
user_collected long User collection status (1:Collected 2:Not collected)
videos array Advertisement videos list
size string Size information
clarity string Clarity information
aspect_ratio string Aspect ratio information
ai_analysis object AI analysis results
AI Analysis Object Fields (ai_analysis)
Field Name Type Description
ai_analysis_human_presenter string Whether human presenter is present
ai_analysis_language string Video language
ai_analysis_main_hook string Main hook content
ai_analysis_script string Video script
ai_analysis_tags array Video tags list
Advertiser Information Object Fields (advertiser)
Field Name Type Description
id string Advertiser ID
name string Advertiser name
ad_count long Advertiser ad count
ad_country array Advertiser target countries
ads_library_link string Ads library link
adset_count long Adset count
e_commerce_platform string E-commerce platform
like_count long Like count
profile_picture_url string Profile picture URL
source_advertiser_id string Source advertiser ID
source_advertiser_link string Source advertiser link
user_blocked long User blocked status (1:Yes 2:No)
Product Information Object Fields (products)
Field Name Type Description
id string Product ID
name string Product name
ad_count long Product ad count
category_id string Category ID
category_name string Category name
creation_time long Creation time
currency string Currency type
image_url string Product image URL
price double Product price
price_usd double Product USD price
source_product_link string Source product link
Store Information Object Fields (store)
Field Name Type Description
id string Store ID
name string Store name
ad_count long Store ad count
categories array Store categories list
e_commerce_platform string E-commerce platform
e_commerce_types array E-commerce types list
logo_url string Store logo URL
source_store_link string Source store link
Store Category Object Fields (categories)
Field Name Type Description
id string Category ID
name_en string Category English name
name_zh string Category Chinese name
Video Information Object Fields (videos)
Field Name Type Description
url string Video URL
cover_url string Cover URL
duration long Video duration (seconds)
width long Video width
height long Video height
Image Information Object Fields (images)
Field Name Type Description
url string Image URL
width long Image width
height long Image height
Field Name Type Description
url string Media URL
cover_url string Cover URL
duration long Duration (for videos)
width long Width
height long Height
media_type long Media type (1:Video 2:Image)

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "ads_history": {
      "ad_cost": {
        "timeline": [
          {
            "count": 0.0,
            "date": "2025-06-04"
          },
          {
            "count": 0.0,
            "date": "2025-06-05"
          }
        ]
      },
      "adset_count": {
        "timeline": [
          {
            "count": 1.0,
            "date": "2025-06-04"
          },
          {
            "count": 1.0,
            "date": "2025-06-05"
          }
        ]
      }
    },
    "advertisement": {
      "id": "9a4566becbe35c6f6c0f1beac8dd6e30",
      "active_days": 1,
      "ad_caption": "ladyluxve.com",
      "ad_content": "🚨 ALERTA TENDENCIA 🚨\nEl botín que está arrasando en redes sociales ya llegó a Venezuela 🇻🇪",
      "ad_forecast": 1,
      "ad_link": "https://www.facebook.com/ads/library/?id=1124613119690978",
      "ad_link_description": "⭐⭐⭐⭐⭐",
      "ad_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "AUDIENCE_NETWORK",
        "MESSENGER",
        "THREADS"
      ],
      "ad_started_at": 1749020400,
      "ad_status": 3,
      "ad_title": "35% OFF Hoy+ Envio GRATIS",
      "adset_count": 1,
      "advertiser": {
        "id": "7302fd79a2d742bb6c0f1beac8dd6e30",
        "name": "Lady Lux",
        "ad_count": 11,
        "ad_country": ["other"],
        "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=685400174653320",
        "adset_count": 11,
        "e_commerce_platform": "shopify",
        "like_count": 1201,
        "profile_picture_url": "https://fb-cdn.pipispy.com/images/38f38e24fa774ca1bf01da9aba9ac47e.png",
        "source_advertiser_id": "685400174653320",
        "source_advertiser_link": "https://facebook.com/61576957564176",
        "user_blocked": 2
      },
      "button_text": "Shop now",
      "button_type": "SHOP_NOW",
      "cards": [],
      "country": ["other"],
      "first_discovered_at": 1749024028,
      "images": [],
      "landing_page_type": 1,
      "landing_pages": [
        "https://ladyluxve.com/products/botin%E2%84%A2-starway"
      ],
      "language": "es",
      "last_discovered_at": 1749108995,
      "latest_actived_at": 1749106800,
      "media_format": 1,
      "products": [
        {
          "currency": "USD",
          "id": "dd66f501d1faa6adbe16801b708c35d5",
          "name": "Botin™ - Starway",
          "price": 49.99,
          "ad_count": 3,
          "creation_time": 1748732926,
          "image_url": "https://fb-cdn.pipispy.com/images/pimg_85d72df090674a0b56a4f.png",
          "price_usd": 49.99,
          "source_product_link": "https://ladyluxve.com/products/botin%E2%84%A2-starway"
        }
      ],
      "source_ad_id": "1124613119690978",
      "store": {
        "categories": [
          {
            "id": "62739ba938365b2f72048eca",
            "name_en": "Shoes",
            "name_zh": "鞋类"
          }
        ],
        "id": "389f77b24aefc6ffbe16801b708c35d5",
        "name": "Lady lux",
        "ad_count": 11,
        "e_commerce_platform": "shopify",
        "logo_url": "http://ladyluxve.com/cdn/shop/files/ladyancho.jpg?crop=center&height=32&v=1748537443&width=32",
        "source_store_link": "https://ladyluxve.com"
      },
      "user_collected": 2,
      "videos": [
        {
          "duration": 16,
          "height": 1280,
          "url": "https://fb-cdn.pipispy.com/videos/a98e21abd3b3b2340f9998d5a8f209ac.mp4",
          "width": 720,
          "cover_url": "https://fb-cdn.pipispy.com/images/40960e1f77f4077634bf463593b629ba.png"
        }
      ],
      "size": "9:16",
      "clarity": "FHD",
      "aspect_ratio": "720x1280"
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}

Error Codes

Error Code Description
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
500 Internal Server Error

Notes

  1. Advertisement ID must be a valid system internal ID
  2. URLs in response have been converted to CDN addresses
  3. All timestamps are Unix timestamps (seconds)
  4. AI analysis fields are only returned for video advertisements
  5. Some fields may be empty depending on advertisement type and data completeness