Monitor Task Ad List
- API Name: Monitor Task Ad List
- Request Method: POST
- API URL:
open-api/v1/monitor/data
- Endpoint Path:
/v3/api/ad-monitor-task/ad-library-list
- Description:
- Ad Library Query - Query all ad data under the task based on monitor task ID
- Dimension Filtering - Support filtering ads by multiple conditions, including:
- Keyword search
- Ad creation time range
- Ad forecast status (Testing/Scaling/Winning)
- Ad set count range
- Ad end time range
- Ad delivery duration range
- Coverage range
- Ad spend range
- Media format (Video/Image/Carousel)
- Video duration range
- Button text (CTA)
- Ad platform (Facebook/Instagram, etc.)
- Ad status (Active/Inactive/Removed)
- Product price range
- Product creation time range
- Landing page URL
- Ad copy content
- Related product ID list
- Sorting and Pagination - Support sorting by multiple fields and pagination query
- Usage Note:
Free
Request Headers:
- Content-Type: application/json
- Accept: application/json
Request Parameters
Request Structure
| Parameter |
Type |
Description |
Example |
Required |
Default |
| key |
string |
User's external API request key |
"your_api_key_here" |
Yes |
|
| uri |
string |
Endpoint path |
"/v3/api/ad-monitor-task/ad-library-list" |
Yes |
|
| params |
object |
Request parameters object |
See parameter list |
Yes |
|
Request Body Parameters (params object)
| Parameter |
Type |
Required |
Description |
| task_id |
string |
true |
Task ID |
| keyword |
string |
false |
Search keyword |
| ad_started_at_start |
integer |
false |
Ad creation time (from), timestamp, unit: seconds |
| ad_started_at_end |
integer |
false |
Ad creation time (to), timestamp, unit: seconds |
| ad_forecast_list |
array[integer] |
false |
Ad forecast, values: 1:Testing, 2:Scaling, 3:Winning |
| adset_count_start |
integer |
false |
Ad set count (from) |
| adset_count_end |
integer |
false |
Ad set count (to) |
| ad_ended_at_start |
integer |
false |
Ad end time (from), timestamp, unit: seconds |
| ad_ended_at_end |
integer |
false |
Ad end time (to), timestamp, unit: seconds |
| active_days_start |
integer |
false |
Ad duration (from) |
| active_days_end |
integer |
false |
Ad duration (to) |
| ad_audience_reach_start |
integer |
false |
Coverage (from) |
| ad_audience_reach_end |
integer |
false |
Coverage (to) |
| ad_cost_start |
double |
false |
Ad spend (from) |
| ad_cost_end |
double |
false |
Ad spend (to) |
| media_format_list |
array[integer] |
false |
Media format, values: 1:Video, 2:Image, 3:Carousel |
| video_duration_start |
integer |
false |
Video duration (from), timestamp, unit: seconds |
| video_duration_end |
integer |
false |
Video duration (to), timestamp, unit: seconds |
| button_text_list |
array[string] |
false |
Button text - CTA |
| ad_platform_list |
array[string] |
false |
Ad platform, values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER |
| ad_status_list |
array[integer] |
false |
Ad status, values: 1:Active, 2:Inactive, 3:Removed |
| product_price_usd_start |
double |
false |
Product price (from), USD |
| product_price_usd_end |
number |
false |
Product price (to), USD |
| product_creation_time_start |
integer |
false |
Product creation time (from), timestamp, unit: seconds |
| product_creation_time_end |
integer |
false |
Product creation time (to), timestamp, unit: seconds |
| landing_page |
string |
false |
Landing page URL |
| ad_content |
string |
false |
Ad copy |
| related_product_id_list |
array[string] |
false |
Product ID |
| order_by |
string |
false |
Sort field, values: ad_started_at(ad start time) ad_ended_at(ad end time) active_days(delivery days) adCost(ad spend) ad_audience_reach(coverage count) latest_actived_at(latest active time) |
| direction |
string |
false |
Sort order, values: desc(descending), asc(ascending) |
| page |
integer |
false |
Page number (default 1) |
| per_page |
integer |
false |
Items per page (default 10) |
Request Example
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/ad-monitor-task/ad-library-list",
"params": {
"order_by": "ad_started_at",
"direction": "desc",
"page": 1,
"ad_started_at_start": 1753574400,
"ad_started_at_end": 1761350399,
"per_page": 20,
"task_id": "68fa2e36789edb5700215e03",
"media_format_list": [
1,
2,
3
],
"button_text_list": [
"Add to cart",
"Apply now",
"Book now",
"Buy now"
]
}
}'
Response Parameters
Response Structure
{
"code": 200,
"message": "success",
"data": {},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"success": true,
"fail": false
}
Response Field Description
| Field Name |
Type |
Description |
| code |
Integer |
Response status code, 200 means success |
| message |
String |
Response message |
| data |
Object |
Response data |
| version |
String |
API version |
| timestamp |
String |
Response timestamp |
| sign |
String |
Response signature |
| remaining_credits |
Long |
Current remaining available credits after this request |
| consumed_credits |
Long |
Credits consumed by this request |
| success |
Boolean |
Request success status |
| fail |
Boolean |
Request failure status |
| Field Name |
Type |
Description |
| per_page |
integer |
Items per page |
| total |
integer |
Total records |
| last_page |
integer |
Last page number |
| current_page |
integer |
Current page number |
Ad Data Fields (objects in data array)
| Field Name |
Type |
Description |
| id |
string |
Ad unique identifier ID |
| ad_title |
string |
Ad title |
| ad_content |
string |
Ad copy content |
| ad_caption |
string |
Ad caption text |
| ad_link |
string |
Link to ad in Facebook ads library |
| ad_started_at |
integer |
Ad start delivery timestamp (seconds) |
| ad_ended_at |
integer |
Ad end timestamp (seconds) |
| first_discovered_at |
integer |
First discovery timestamp (seconds) |
| last_discovered_at |
integer |
Last discovery timestamp (seconds) |
| latest_actived_at |
integer |
Latest active timestamp (seconds) |
| active_days |
integer |
Ad active days |
| ad_status |
integer |
Ad status (1:Active, 2:Inactive, 3:Removed) |
| ad_forecast |
integer |
Ad forecast status (1:Testing, 2:Scaling, 3:Winning) |
| ad_cost |
double |
Ad spend amount |
| ad_audience_reach |
integer |
Ad coverage count |
| adset_count |
integer |
Number of ad sets |
| media_format |
integer |
Media format (1:Video, 2:Image, 3:Carousel) |
| landing_page_type |
integer |
Landing page type |
| button_type |
string |
Button type (e.g.: APPLY_NOW) |
| button_text |
string |
Button text content |
| country |
array |
Ad delivery countries list |
| ad_platform |
array |
Ad delivery platforms (FACEBOOK, INSTAGRAM, etc.) |
| landing_pages |
array |
Landing page URLs list |
| Field Name |
Type |
Description |
| duration |
integer |
Video duration (seconds) |
| cover_url |
string |
Video cover image URL |
| url |
string |
Video file URL |
| width |
integer |
Video width (pixels) |
| height |
integer |
Video height (pixels) |
| Field Name |
Type |
Description |
| id |
string |
Advertiser ID |
| name |
string |
Advertiser name |
| source_advertiser_id |
string |
Source advertiser ID |
| profile_picture_url |
string |
Advertiser profile picture URL |
| like_count |
integer |
Advertiser like count |
| ad_count |
integer |
Advertiser total ad count |
| ad_country |
array |
Advertiser delivery countries list |
| ads_library_link |
string |
Advertiser link in Facebook ads library |
Response Example
{
"code": 200,
"message": "success",
"data": {
"per_page": 20,
"total": 1,
"data": [
{
"country": [
"NL"
],
"ad_caption": "werkenbijcoolblue.nl/winkel-alkmaar",
"button_type": "APPLY_NOW",
"videos": [
{
"duration": 15,
"cover_url": "https://cdn.pipidata.com/images/0e62b0d751f21752a0b1ab5b69f7a183949b87627d7f59a1638890cd01331b19.png",
"width": 720,
"url": "https://cdn.pipidata.com/videos/810468b5afa64b5f8ab521d319f02e9edc81e5de50df84b1f8a6c2966f805009.mp4",
"height": 1280
}
],
"ad_content": "Wil je werken met de leukste collega's? Word onderdeel van ons team. #WerkenbijCoolblue #Alkmaar",
"last_discovered_at": 1755532885,
"ad_title": "Word onderdeel van ons team.",
"ad_ended_at": 1755500400,
"ad_link": "https://www.facebook.com/ads/library/?id=1779094526050412",
"ad_forecast": 2,
"id": "1779094526050412",
"latest_actived_at": 1755500400,
"landing_page_type": 3,
"advertiser": {
"like_count": 463298,
"profile_picture_url": "https://cdn.pipidata.com/images/b467aa4e0f396674a14f1ffaa99a1d76.png",
"ad_count": 14383,
"source_advertiser_id": "422603325536",
"name": "Coolblue",
"id": "422603325536",
"ad_country": [
"NL",
"BE",
"DE",
"ES",
"HU"
],
"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=422603325536"
},
"ad_cost": 1559.74,
"first_discovered_at": 1755532885,
"landing_pages": [
"https://www.werkenbijcoolblue.nl/winkels/?location=alkmaar"
],
"ad_audience_reach": 11192,
"adset_count": 1,
"ad_status": 1,
"media_format": 1,
"ad_platform": [
"FACEBOOK",
"INSTAGRAM"
],
"button_text": "Apply now",
"ad_started_at": 1755500400,
"active_days": 1
}
],
"last_page": 1,
"current_page": 1
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"success": true,
"fail": false
}
Error Codes
| Error Code |
Description |
| 200 |
Success |
| 400 |
Invalid request parameters |
| 500 |
Internal server error |