# Monitor Task Ad List
## API Information
- **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
```bash
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
```json
{
"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 |
### Response Data Information Fields
#### Pagination Information Fields
| 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 |
### Video Information Fields (objects in videos array)
| 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) |
### Advertiser Information Fields (advertiser object)
| 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
```json
{
"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 |