Advertisement Library Detail API
- 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 |
Advertisement History Fields (ads_history)
| 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) |
Advertisement Detail Fields (advertisement)
| 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 |
| 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) |
| 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 |
| 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 |
| 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 |
| 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
- Advertisement ID must be a valid system internal ID
- URLs in response have been converted to CDN addresses
- All timestamps are Unix timestamps (seconds)
- AI analysis fields are only returned for video advertisements
- Some fields may be empty depending on advertisement type and data completeness