# Get Monitor Task List
## API Information
- **API Name**: Get Monitor Task List
- **Request Method**: POST
- **API URL**: `open-api/v1/monitor/data`
- **Endpoint Path**: `/v3/api/ad-monitor-task/list`
- **Description**:
- Query all monitoring ad tasks for the current user, support filtering by keyword, task type, country and other conditions, support pagination and sorting (ascending/descending by start time), return task basic information (ID, start time, duration, etc.)
- 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/list" | Yes | |
| params | object | Request parameters object | See parameter list | Yes | |
### Request Body Parameters (params object)
| Parameter | Type | Required | Description |
|----------------------|----------|----------|-----------------------------------------------------------------------------------------|
| keyword | String | No | Monitor task name keyword |
| monitor_task_type | integer | No | Monitor task type, 1:Facebook advertiser, 2:Store/Website |
| country | string | No | Country |
| order_by | string | No | Sort field, values:
started_at(monitor start date)
ad_total_count(total ad count)
ad_total_active_count(total active ad count)
ad_today_count(today's new ad count)
ad_yesterday_count(yesterday's new ad count)
landing_page_total_count(total landing page count)
landing_page_today_count(today's new landing page)
landing_page_yesterday_count(yesterday's new landing page)
product_total_count(total product count)
product_today_count(today's new product)
product_yesterday_count(yesterday's new product) |
| direction | string | No | Sort order: desc(descending), asc(ascending) |
| page | integer | No | Page number (default 1) |
| per_page | integer | No | Page size (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/list",
"params": {
"keyword": "ChicMe",
"monitor_task_type": 1,
"order_by": "ad_total_active_count",
"direction": "desc",
"page": 1,
"per_page": 10
}
}'
```
## Response Parameters
### Response Structure
```json
{
"code": 200,
"message": "success",
"data": {},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"fail": false,
"success": true
}
```
### 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 |
### Search Result Information Fields
| Field Name | Type | Description |
|--------------------------------|------------------|---------------------------------------------------------------------------------|
| per_page | integer | Number of data items per page |
| total | integer | Total number of data items |
| last_page | integer | Last page number |
| current_page | integer | Current page number |
| country | string | Country code |
| task_id | string | Task ID |
| facebook_page_id | string | FB ads advertiser ID |
| name | string | Monitor object name |
| category | string | Advertiser category displayed on FB ad library, not available for store/website |
| avatar_url | string | Monitor object avatar |
| started_at | integer | Monitor start time, timestamp, unit: seconds |
| stoped_at | integer | Monitor stop time, timestamp, unit: seconds |
| monitor_expire_time | integer | Monitor expiration time, timestamp, unit: seconds |
| facebook_shop_url | string | FB ads store URL |
| monitor_task_type | integer | Monitor task type 1:Facebook advertiser, 2:Store/Website |
| country | string | Advertiser country (some have), store country |
| ad_total_count | integer | Total ad count |
| ad_total_active_count | integer | Total active count |
| ad_today_count | integer | Today's new ad count |
| ad_yesterday_count | integer | Yesterday's new ad count |
| landing_page_total_count | integer | Total landing page count |
| landing_page_today_count | integer | Today's new landing page count |
| landing_page_yesterday_count | integer | Yesterday's new landing page count |
| product_total_count | integer | Total product count |
| product_today_count | integer | Today's new product count |
| product_yesterday_count | integer | Yesterday's new product count |
| latest_ad_data | array[object] | Latest ad data |
| latest_ad_data[].id | string | Ad ID |
| latest_ad_data[].cover_url | string | Cover |
| latest_ad_data[].ad_started_at | integer | Publish time timestamp, unit: seconds |
| latest_ad_data[].duration | integer | Video duration (seconds) |
| latest_ad_data[].type | integer | Ad type |
| latest_ad_data[].video_url | string | Video ad URL address |
| latest_ad_data[].cards | array[object] | Ad cards array, contains multiple ad materials |
| latest_ad_data[].cards[].width | integer | Card width, unit: pixels |
| latest_ad_data[].cards[].height | integer | Card height, unit: pixels |
| latest_ad_data[].cards[].type | integer | Card type (1=video, 2=image) |
| latest_ad_data[].cards[].url | string | Card resource URL address |
| videos_ad_total_count | integer | Total video ad count |
| cards_ad_total_count | integer | Total card ad count |
| images_ad_total_count | integer | Total image ad count |
| ad_seven_day_count | integer | New ad count in last 7 days |
| landing_page_seven_day_count | integer | New landing page count in last 7 days |
| product_seven_day_count | integer | New product count in last 7 days |
| updated_at | integer | Last update time, timestamp, unit: seconds |
| monitored_days | integer | Monitored days |
| status | integer | Monitor status 1: Monitoring, 2: Cancelled |
## Response Example
```json
{
"code": 200,
"message": "success",
"data": {
"per_page": 1,
"total": 1,
"data": [
{
"country": "PL",
"latest_ad_data": [
{
"duration": 28,
"cover_url": "https://cdn.pipidata.com/images/ffa2dbbd8eeaf537f07439410251c81f1505516772fb4eb08eeb1abdfc1169ba.png",
"cards": [
{
"duration": 28,
"cover_url": "https://cdn.pipidata.com/images/ffa2dbbd8eeaf537f07439410251c81f1505516772fb4eb08eeb1abdfc1169ba.png",
"width": 720,
"type": 1,
"url": "https://cdn.pipidata.com/videos/34006a2c3591e52c0822ed20228f9f15a9e4007738bfebdcf25c3bc393de3ca7.mp4",
"height": 1280
},
{
"duration": 28,
"cover_url": "https://cdn.pipidata.com/images/ffa2dbbd8eeaf537f07439410251c81f1505516772fb4eb08eeb1abdfc1169ba.png",
"width": 720,
"type": 1,
"url": "https://cdn.pipidata.com/videos/34006a2c3591e52c0822ed20228f9f15a9e4007738bfebdcf25c3bc393de3ca7.mp4",
"height": 1280
},
{
"duration": 28,
"cover_url": "https://cdn.pipidata.com/images/193cab5ca17e4fe71c48d051010d36c1f23fb2304db14eb6ff18438b7f1c4392.png",
"width": 720,
"type": 1,
"url": "https://cdn.pipidata.com/videos/b09f6a2e42674f4707559ac036719510ebd55db607a17e837547eea32f8142bc.mp4",
"height": 900
}
],
"video_url": "https://cdn.pipidata.com/videos/34006a2c3591e52c0822ed20228f9f15a9e4007738bfebdcf25c3bc393de3ca7.mp4",
"id": "1269635651567302",
"ad_started_at": 1758092400,
"type": 3
}
],
"product_seven_day_count": 0,
"landing_page_yesterday_count": 0,
"task_id": "68f98898850c5345a4c87e67",
"product_yesterday_count": 0,
"videos_ad_total_count": 640,
"ad_yesterday_count": 0,
"updated_at": 1761208806,
"monitor_task_type": 1,
"product_today_count": 0,
"ad_total_active_count": 16423,
"monitored_days": 1,
"ad_seven_day_count": 0,
"landing_page_seven_day_count": 0,
"product_total_count": 0,
"cards_ad_total_count": 16560,
"images_ad_total_count": 1063,
"facebook_page_id": "614178972053891",
"ad_total_count": 18263,
"landing_page_today_count": 0,
"landing_page_total_count": 4305,
"avatar_url": "https://cdn.pipidata.com/images/fb4225ffd00b4c0317d905cf8392ee01975c8664abd19bb361466200a0a82d5c.png",
"ad_today_count": 0,
"name": "ChicMe",
"started_at": 1761183896,
"stoped_at": null,
"monitor_expire_time": 1763821563,
"category": "Clothing (Brand)",
"status": 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 |