Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

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

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

{
  "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

{
  "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