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.

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

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

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

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