# 获取监控任务列表接口
## 接口信息
- **接口名称**: 获取监控任务列表接口
- **请求方法**: POST
- **接口地址**: `open-api/v1/monitor/data`
- **接口路径**: `/v3/api/ad-monitor-task/list`
- **接口描述**:
- 查询当前用户的所有监控中的广告任务，支持按关键词、任务类型、国家等条件筛选，支持分页和排序（按开始时间升序/降序），返回任务的基本信息（ID、开始时间、持续时间等）
- 价格说明: `免费`
**请求头:**
- Content-Type: application/json
- Accept: application/json
## 请求参数
### 请求结构
| 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ----------------------------------- | ---- | ------ |
| key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | |
| uri | string | 接口路径 | "/v3/api/ad-monitor-task/list" | 是 | |
| params | object | 接口入参对象 | 见参数列表 | 是 | |
### 请求体参数 (params 对象)
| 参数名 | 类型 | 必填 | 描述 |
|------------------|--------|----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| keyword | String | 否 | 监控任务名称关键词 |
| monitor_task_type | integer | 否 | 监控任务类型，1:facebook广告主, 2:店铺/网站 |
| country | string | 否 | 国家 |
| order_by | string | 否 | 排序字段可取值：
started_at(开始监控日期)
ad_total_count(总广告数)
ad_total_active_count(总活跃广告数)
ad_today_count(今日新增广告数)
ad_yesterday_count(昨日新增广告数)
landing_page_total_count(落地页总数)
landing_page_today_count(今日新增落地页)
landing_page_yesterday_count(昨日新增落地页)
product_total_count(总产品数)
product_today_count(今日新增产品)
product_yesterday_count(昨日新增产品) |
| direction | string | 否 | 排序方式： desc(降序), asc(升序) |
| page | integer | 否 | 页码（默认1） |
| per_page | integer | 否 | 分页大小（默认10） |
### 请求示例
```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
}
}'
```
## 响应参数
### 响应体结构
```json
{
"code": 200,
"message": "success",
"data": {},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"fail": false,
"success": true
}
```
### 响应字段说明
| 字段名 | 类型 | 描述 |
| --------- | ------- | ------------------------ |
| code | Integer | 响应状态码，200 表示成功 |
| message | String | 响应消息 |
| data | Object | 响应数据 |
| version | String | API 版本 |
| timestamp | String | 响应时间戳 |
| sign | String | 响应签名 |
| remaining_credits | Long | 当前请求后的剩余可用积分 |
| consumed_credits | Long | 本次请求消耗的积分 |
| success | Boolean | 请求是否成功 |
| fail | Boolean | 请求是否失败 |
### 搜索结果信息字段
| 字段名 | 类型 | 描述 |
|---------------------------------------|------------------|---------------------------------|
| per_page | integer | 每页显示的数据条数 |
| total | integer | 总数据条数 |
| last_page | integer | 最后一页的页码 |
| current_page | integer | 当前页码 |
| country | string | 国家代码 |
| task_id | string | 任务id |
| facebook_page_id | string | fb ads广告主id |
| facebook_page_id | string | fb ads广告主id |
| name | string | 监控对象名称 |
| category | string | 广告主展示fb ad library上的类别, 店铺/网站没有 |
| avatar_url | string | 监控对象头像 |
| started_at | integer | 开始监控时间，时间戳，单位s |
| stoped_at | integer | 监控停止时间，时间戳，单位s |
| monitor_expire_time | integer | 监控到期时间，时间戳，单位s |
| facebook_shop_url | string | fb ads店铺url |
| monitor_task_type | integer | 监控任务类型 1:facebook广告主, 2:店铺/网站 |
| country | string | 广告主国家（部分有）, 店铺国家 |
| ad_total_count | integer | 总广告数 |
| ad_total_active_count | integer | 总活跃 |
| ad_today_count | integer | 今日新增广告数 |
| ad_yesterday_count | integer | 昨日新增广告数 |
| landing_page_total_count | integer | 落地页总数 |
| landing_page_today_count | integer | 今日新增落地页 |
| landing_page_yesterday_count | integer | 昨日新增落地页 |
| product_total_count | integer | 总产品数 |
| product_today_count | integer | 今日新增产品 |
| product_yesterday_count | integer | 昨日新增产品 |
| latest_ad_data | array[object{3}] | 最新广告数据 |
| latest_ad_data[].id | string | 广告id |
| latest_ad_data[].cover_url | string | 封面 |
| latest_ad_data[].ad_started_at | integer | 发布时间时间戳，单位s |
| latest_ad_data[].duration | integer | 视频时长（秒） |
| latest_ad_data[].type | integer | 广告类型 |
| latest_ad_data[].video_url | string | 视频广告的URL地址 |
| latest_ad_data[].cards | array[object] | 广告卡片数组，包含多个广告素材 |
| latest_ad_data[].cards[].width | integer | 卡片宽度，单位像素 |
| latest_ad_data[].cards[].height | integer | 卡片高度，单位像素 |
| latest_ad_data[].cards[].type integer | 卡片类型（1=视频，2=图片） |
| latest_ad_data[].cards[].url | string | 卡片资源URL地址 |
| videos_ad_total_count | integer | 视频广告总数 |
| cards_ad_total_count | integer | 卡片广告总数 |
| images_ad_total_count | integer | 图片广告总数 |
| ad_seven_day_count | integer | 近7天新增广告数 |
| landing_page_seven_day_count | integer | 近7天新增落地页数 |
| product_seven_day_count | integer | 近7天新增产品数 |
| updated_at | integer | 最后更新时间，时间戳，单位秒 |
| monitored_days | integer | 已监控天数 |
| status | integer | 监控状态 1: 监控中, 2: 已取消监控 |
## 响应示例
```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
}
```
## 错误码说明
| 错误码 | 描述 |
| ------ | -------------- |
| 200 | 成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |