# 监控任务的广告列表
## 接口信息
- **接口名称**: 监控任务的广告列表
- **请求方法**: POST
- **接口地址**: `open-api/v1/monitor/data`
- **接口路径**: `/v3/api/ad-monitor-task/ad-library-list`
- **接口描述**:
- 广告库查询 - 根据监控任务ID查询该任务下的所有广告数据
- 维度筛选 - 支持按多种条件筛选广告，包括：
- 关键字搜索
- 广告创建时间范围
- 广告预测状态（Testing/Scaling/Winning）
- 广告组数量范围
- 广告结束时间范围
- 广告投放时长范围
- 覆盖人数范围
- 广告花费范围
- 媒体格式（视频/图片/轮播图）
- 视频时长范围
- 按钮文本（CTA）
- 广告平台（Facebook/Instagram等）
- 广告状态（活跃/不活跃/下架）
- 产品价格范围
- 产品创建时间范围
- 落地页URL
- 广告文案内容
- 关联产品ID列表
- 排序和分页 - 支持按多种字段排序和分页查询
- 价格说明: `免费`
**请求头:**
- Content-Type: application/json
- Accept: application/json
## 请求参数
### 请求结构
| 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ----------------------------------- | ---- | ------ |
| key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | |
| uri | string | 接口路径 | "/v3/api/ad-monitor-task/ad-library-list" | 是 | |
| params | object | 接口入参对象 | 见参数列表 | 是 | |
### 请求体参数 (params 对象)
| 参数名 | 类型 | 必填 | 描述 |
|---------|----------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| task_id | string | true | 任务id |
| keyword | string | false | 搜索关键词 | 搜索关键词 |
| ad_started_at_start | integer | false | 广告创建时间（起）,时间戳，单位s |
| ad_started_at_end | integer | false | 广告创建时间（止）,时间戳，单位s |
| ad_forecast_list | array[integer] | false | 广告预测，可取值： 1：Testing, 2：Scaling, 3：Winning |
| adset_count_start | integer | false | 广告组数（起） |
| adset_count_end | integer | false | 广告组数（止） |
| ad_ended_at_start | integer | false | 广告结束时间（起）,时间戳，单位s |
| ad_ended_at_end | integer | false | 广告结束时间（止）,时间戳，单位s |
| active_days_start | integer | false | 广告时长（起） |
| active_days_end | integer | false | 广告时长（止） |
| ad_audience_reach_start | integer | false | 覆盖（起） |
| ad_audience_reach_end | integer | false | 覆盖（止） |
| ad_cost_start | double | false | 广告花费（起） |
| ad_cost_end | double | false | 广告花费（止） |
| media_format_list | array[integer] | false | 媒体格式，可取值： 1：视频, 2：图片, 3：轮播图 |
| video_duration_start | integer | false | 视频时长（起），时间戳，单位s |
| video_duration_end | integer | false | 视频时长（止），时间戳，单位s |
| button_text_list | array[string] | false | 按钮文本-cta |
| ad_platform_list | array[string] | false | 广告平台，可取值： FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER |
| ad_status_list | array[integer] | false | 广告状态，可取值： 1：活跃, 2：不活跃, 3：下架 |
| product_price_usd_start | double | false | 产品价格（起），美元 |
| product_price_usd_end | number | false | 产品价格（止），美元 |
| product_creation_time_start | integer | false | 产品创建时间（起），时间戳，单位s |
| product_creation_time_end | integer | false | 产品创建时间（止，时间戳，单位s |
| landing_page | string | false | 落地页URL |
| ad_content | string | false | 广告文案 |
| related_product_id_list | array[string] | false | 产品 ID |
| order_by | string | false | 排序字段, 可取值： ad_started_at(广告开始时间)
ad_ended_at(广告结束时间)
active_days(投放天数)
adCost(广告花费)
ad_audience_reach(覆盖人数)
latest_actived_at(最近活跃时间) |
| direction | string | false | 排序方式, 可取值：desc(降序), asc(升序) |
| page | integer | false | 页码（默认值1） |
| perPage | integer | false | 每页数据数量（默认值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/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"
]
}
}'
```
## 响应参数
### 响应体结构
```json
{
"code": 200,
"message": "success",
"data": {},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"success": true,
"fail": false
}
```
### 响应字段说明
| 字段名 | 类型 | 描述 |
| --------- | ------- | ------------------------ |
| 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 | 当前页码 |
#### 广告数据字段（data数组中的对象）
| 字段名 | 类型 | 描述 |
|---------------------|-----------|----------------------------------------|
| id | string | 广告唯一标识ID |
| ad_title | string | 广告标题 |
| ad_content | string | 广告文案内容 |
| ad_caption | string | 广告说明文字 |
| ad_link | string | 广告在Facebook广告库的链接 |
| ad_started_at | integer | 广告开始投放时间戳（秒） |
| ad_ended_at | integer | 广告结束时间戳（秒） |
| first_discovered_at | integer | 首次发现时间戳（秒） |
| last_discovered_at | integer | 最后发现时间戳（秒） |
| latest_actived_at | integer | 最近活跃时间戳（秒） |
| active_days | integer | 广告活跃天数 |
| ad_status | integer | 广告状态（1:活跃，2:不活跃，3:下架） |
| ad_forecast | integer | 广告预测状态（1:Testing，2:Scaling，3:Winning） |
| ad_cost | double | 广告花费金额 |
| ad_audience_reach | integer | 广告覆盖人数 |
| adset_count | integer | 广告组数量 |
| media_format | integer | 媒体格式（1:视频，2:图片，3:轮播图） |
| landing_page_type | integer | 落地页类型 |
| button_type | string | 按钮类型（如：APPLY_NOW）|
| button_text | string | 按钮文本内容|
| country | array | 广告投放国家列表|
| ad_platform | array | 广告投放平台（FACEBOOK、INSTAGRAM等）|
| landing_pages | array | 落地页URL列表|
### 视频信息字段（videos数组中的对象）
| 字段名 | 类型 | 描述 |
|-----------|-----------|----------------------------------------|
| duration | integer | 视频时长（秒）|
| cover_url | string |视频封面图片URL|
| url | string |视频文件URL|
| width | integer |视频宽度（像素）|
| height | integer |视频高度（像素）|
### 广告主信息字段（advertiser对象）
| 字段名 | 类型 | 描述 |
|----------------------|----------|---------------------|
| id | string | 广告主ID |
| name | string | 广告主名称 |
| source_advertiser_id | string | 源广告主ID |
| profile_picture_url | string | 广告主头像URL |
| like_count | integer | 广告主点赞数 |
| ad_count | integer | 广告主总广告数 |
| ad_country | array | 广告主投放国家列表 |
| ads_library_link | string | 广告主在Facebook广告库的链接 |
## 响应示例
```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
}
```
## 错误码说明
| 错误码 | 描述 |
| ------ | -------------- |
| 200 | 成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |