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.

Ad Library List API

API Information

  • API Name: Ad Library List Query
  • Request Method: POST
  • API Address: /open-api/v1/data
  • API Path: /v3/api/open/lib-ads/list
  • API Description: Retrieve ad library list data with multi-dimensional filtering and pagination support, suitable for ad analysis, competitor research, creative mining, and other scenarios
  • Pricing: 1 credit per data record retrieved

Request Headers:

  • Content-Type: application/json
  • Accept: application/json

Request Parameters

Request Structure

Parameter Type Description Example Required Default
key string External API request key "your_api_key_here" Yes
uri string API path "/v3/api/open/lib-ads/list" Yes
params object API parameter object See parameter list Yes

Request Body Parameters (params object)

Basic Parameters

Parameter Type Required Description
page Integer No Page number, minimum value is 1. Used for paginated queries to specify which page of data to retrieve
per_page Integer No Page size, range 1-100. Specifies the number of ads returned per page
order_by String No Sort field, determines which metric to sort results by. Available values:
• ad_started_at - Ad creation time
• first_discovered_at - Ad discovery time
• last_discovered_at - Ad last update time
• latest_actived_at - Ad last active time
• active_days - Ad duration
• ad_cost - Ad spend
• ad_audience_reach - Reach
• adset_count - Adset count
• advertiser_ad_count - Advertiser ad count
• product_ad_count - Product ad count
• product_price_usd - Product price
• product_creation_time - Product creation time
• store_ad_count - Store ad count
• video_duration - Video duration
• app_last_month_download_count - App monthly downloads
• app_last_month_revenue_usd - App monthly revenue (USD)
• app_rate_score - App rating
• app_creation_time - App release date
direction String No Sort direction, works with order_by. Available values:
• desc - Descending (high to low)
• asc - Ascending (low to high)

Ad Basic Filters

Parameter Type Required Description
ad_content String No Ad text, search for ads containing specific content
ad_content_md5 String No MD5 hash of ad text, for exact matching of identical text
ad_platform String No Ad platform, filter ads running on specific platforms. Available values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, THREADS
ad_status String No Ad status, filter ads by different running states. Available values:
• 1 - Active (running)
• 2 - Inactive (paused)
• 3 - Removed (stopped)
ad_forecast Long No Ad prediction, AI-evaluated ad stage. Available values:
• 1 - Testing
• 2 - Scaling
• 3 - Winning
country String No Country, filter ads running in specific countries. Use ISO 3166-1 alpha-2 country codes, multiple countries separated by commas. Example: "US,CA,GB"
language String No Language, filter ads in specific languages. Use ISO 639-1 language codes. Example: "en"
data_type String No Ad type (major category), multiple values can be separated by commas. Available values:
• 1 - E-commerce
• 2 - Dropshipping
• 3 - Games
• 4 - App
• 5 - AI
• 6 - Short Drama
source_ad_id String No Ad creative ID, multiple values separated by commas. Example: "3617279838571920,6767880647973308"
source_advertiser_id String No Page ID, query all ads from a specific advertiser

Ad Time Filters

Parameter Type Required Description
ad_started_at_start Long No Ad creation time (start), timestamp in seconds. Lower bound for ad creation time range
ad_started_at_end Long No Ad creation time (end), timestamp in seconds. Upper bound for ad creation time range. Works with ad_started_at_start
first_discovered_at_start Long No Ad discovery time (start), timestamp in seconds. Lower bound for ad discovery time range
first_discovered_at_end Long No Ad discovery time (end), timestamp in seconds. Upper bound for ad discovery time range. Works with first_discovered_at_start
last_discovered_at_start Long No Ad last update time (start), timestamp in seconds. Lower bound for ad last update time range
last_discovered_at_end Long No Ad last update time (end), timestamp in seconds. Upper bound for ad last update time range. Works with last_discovered_at_start
latest_actived_at_start Long No Ad last active time (start), timestamp in seconds. Lower bound for ad last active time range
latest_actived_at_end Long No Ad last active time (end), timestamp in seconds. Upper bound for ad last active time range. Works with latest_actived_at_start

Ad Duration Filters

Parameter Type Required Description
active_days_start Long No Ad duration (start), lower bound for ad running days. More days indicate longer continuous running time
active_days_end Long No Ad duration (end), upper bound for ad running days. Works with active_days_start

Ad Data Filters

Parameter Type Required Description
ad_audience_reach_start Integer No Reach (start), lower bound for ad reach range. Reach indicates unique users reached by the ad
ad_audience_reach_end Integer No Reach (end), upper bound for ad reach range. Works with ad_audience_reach_start
ad_cost_start Double No Ad spend (start), in USD. Lower bound for ad spend amount range
ad_cost_end Double No Ad spend (end), in USD. Upper bound for ad spend amount range. Works with ad_cost_start
adset_count_start Long No Adset count (start), lower bound for adset count range
adset_count_end Long No Adset count (end), upper bound for adset count range. Works with adset_count_start

Advertiser Filters

Parameter Type Required Description
advertiser_id String No Advertiser ID, query all ads from a specific advertiser
advertiser_name String No Page name, search for advertisers containing specific names
advertiser_ad_count_start Long No Advertiser ad count (start), lower bound for advertiser creative count range
advertiser_ad_count_end Long No Advertiser ad count (end), upper bound for advertiser creative count range. Works with advertiser_ad_count_start
with_blockded_advertiser String No Return blocked advertisers, control whether to include blocked advertisers in results

Button Filters

Parameter Type Required Description
button_text String No Button text, search for ads containing specific button text, Allowed values:
• Apply now
• Book now
• Buy tickets
• Contact us
• Donate now
• Download
• Get offer
• Get quote
• Get showtimes
• Send message
• Install now
• Learn more
• No button
• Order now
• Play game
• Request time
• See menu
• Shop now
• Sign up
• Subscribe
• Watch more
button_type String No Button type, filter ads using specific call-to-action button types, Allowed values:
• APPLY_NOW
• BOOK_TRAVEL
• BUY_TICKETS
• CONTACT_US
• DONATE_NOW
• DOWNLOAD
• GET_OFFER
• GET_OFFER_VIEW
• GET_QUOTE
• GET_SHOWTIMES
• INSTAGRAM_MESSAGE
• INSTALL_MOBILE_APP
• LEARN_MORE
• NO_BUTTON
• ORDER_NOW
• PLAY_GAME
• REQUEST_TIME
• SEE_MENU
• SHOP_NOW
• SIGN_UP
• SUBSCRIBE
• WATCH_MORE

Media Creative Filters

Parameter Type Required Description
media_format String No Media format, filter ads with specific creative formats. Available values:
• 1 - Video
• 2 - Image
• 3 - Carousel
video_duration_start Long No Video duration (start), in seconds. Lower bound for video duration range
video_duration_end Long No Video duration (end), in seconds. Upper bound for video duration range. Works with video_duration_start
size String No Size ratio, multiple values separated by commas. Filter ad creatives with specific size ratios
aspect_ratio String No Aspect ratio, multiple values separated by commas. Filter ad creatives with specific aspect ratios
clarity String No Video quality, multiple values separated by commas. Available values:
• HD - High Definition
• SD - Standard
• LD - Low
• UNKNOWN

Audience Filters

Parameter Type Required Description
gender_audience String No Gender, multiple values separated by commas. Available values:
• All
• Men
• Women
age_audience String No Age, multiple values separated by commas. Filter ad audience by specific age ranges

Landing Page Filters

Parameter Type Required Description
landing_pages String No Landing page URL, search for ads with specific landing page links
landing_pages_md5 String No MD5 hash of landing page, for exact matching of identical landing pages
landing_page_type String No Landing page type, filter ads with specific landing page types. Available values:
• 1 - E-commerce product
• 2 - E-commerce collection pages
• 3 - E-commerce other
• 4 - APP
• 5 - AI website
• 6 - Short drama website
• 100 - Other
• 101 - With redirect (not supported, reserved)
related_roots String No Domains, multiple values separated by commas. Filter ads under specific domains

E-commerce Platform Filters

Parameter Type Required Description
e_commerce_platform String No E-commerce platform, filter ads from specific platforms. Available values:
• shopify
• woocommerce
• magento
• prestashop
• opencart
• bigcommerce
• ecwid
• shopline
• shoplazza
• wix
• squarespace
e_commerce_type String No E-commerce type, multiple values separated by commas. Available values:
• 1 - Dropshipping
• 2 - Print on demand (POD)
• 3 - Cash/collect on delivery (COD)
• 4 - Digital products

Product Filters

Parameter Type Required Description
product_name String No Product name, search for ads containing specific product names
product_category_id String No Product category, filter ads for products in specific categories. See E-commerce Categories
product_price_usd_start Double No Product price (start), in USD. Lower bound for product price range
product_price_usd_end Double No Product price (end), in USD. Upper bound for product price range. Works with product_price_usd_start
product_creation_time_start Long No Product creation time (start), timestamp in seconds. Lower bound for product creation time range
product_creation_time_end Long No Product creation time (end), timestamp in seconds. Upper bound for product creation time range. Works with product_creation_time_start
product_ad_count_start Long No Product ad count (start), lower bound for product creative count range
product_ad_count_end Long No Product ad count (end), upper bound for product creative count range. Works with product_ad_count_start
related_product_ids String No Product IDs, multiple values separated by commas. Batch query ads for specified products. Example: "prod_1,prod_2"

Store Filters

Parameter Type Required Description
store_ad_count_start Long No Store ad count (start), lower bound for store creative count range
store_ad_count_end Long No Store ad count (end), upper bound for store creative count range. Works with store_ad_count_start
related_store_ids String No Store IDs, multiple values separated by commas. Batch query ads for specified stores. Example: "store_1,store_2"

App Filters

Parameter Type Required Description
app_store String No App platform, multiple values separated by commas. Available values:
• apple - Apple App Store
• google - Google Play
• web - Website
app_category String No App category (using pipiads organized categories), multiple values separated by commas. Filter ads for apps in specific categories
app_ai_category String No App AI category, multiple values separated by commas. AI-based intelligent app classification
app_developer_ids String No App developer IDs, multiple values separated by commas. Query all app ads from specific developers
app_creation_time_start Long No App release date (start), timestamp in seconds. Lower bound for app release time range
app_creation_time_end Long No App release date (end), timestamp in seconds. Upper bound for app release time range. Works with app_creation_time_start
app_rate_score_start Double No App rating (start), lower bound for app rating range. Rating range is typically 0-5
app_rate_score_end Double No App rating (end), upper bound for app rating range. Works with app_rate_score_start
app_last_month_download_count_start Long No App monthly downloads (start), lower bound for app monthly download range. Refers to estimated downloads in the last month
app_last_month_download_count_end Long No App monthly downloads (end), upper bound for app monthly download range. Works with app_last_month_download_count_start
app_last_month_revenue_usd_start Double No App monthly revenue (start), in USD. Lower bound for app monthly revenue range. Refers to estimated revenue in the last month
app_last_month_revenue_usd_end Double No App monthly revenue (end), in USD. Upper bound for app monthly revenue range. Works with app_last_month_revenue_usd_start
Parameter Type Required Description
extend_keywords Array No Keyword search list, search ads by keywords. Supports multiple keyword combination searches. Each object in the array contains the following fields:
• field - Search field, available values: all, ad_content (ad text), landing_pages (landing page URL), advertiser_name (advertiser page name), product_name (product name), product (e-commerce product: product name, product link), store (store: store name, store link), app_name, app_developer_name, advertiser (social page: advertiser name, source advertiser ID), material (creative info: script/Hook/Tags, reserved, not yet available)
• logic_operator - Logic operator, available values: and, or
• value - Search content
exclude_keywords Array No Exclude keyword list, exclude ads containing specific keywords. Same structure as extend_keywords

Exclusion Filters

Parameter Type Required Description
exclude_ad_content Array No Exclude ad text, exclude ads containing specific text
exclude_advertiser_id String No Exclude advertiser IDs, multiple values separated by commas. Exclude ads from specific advertisers
exclude_advertiser_name Array No Exclude advertiser page names, exclude advertisers with specific names
exclude_landing_pages Array No Exclude landing page URLs, exclude ads with specific landing page links
exclude_product_name Array No Exclude product names, exclude ads containing specific product names

Advanced Options

Parameter Type Required Description
enable_token_search Integer No Token search switch, control whether to enable token search. Available values:
• 0 - Disable token search, match complete words
• 1 - Enable token search, support fuzzy matching and partial word matching
release_area String No Release area. Available values:
• 1 - EU version
search_after String No Deep pagination query (compatibility: if using this method, also pass this parameter for the first page with an empty string value, &=search_after)
Format: [{sort field value}, {ID value}]
with_ad_status_group String No Return ad count by status, when set, the response will include ad_status_group field with statistics for each status
with_ad_started_at_group String No Return first ad date statistics, when set, the response will include ad_started_at_group field with statistics by time period (today, yesterday, last 7 days, last 30 days, last 90 days, total)

Request Example

curl -X POST "https://www.pipispy.com/open-api/v1/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/open/lib-ads/list",
    "params": {
      "page": 1,
      "per_page": 20,
      "ad_platform": "FACEBOOK",
      "ad_status": "1",
      "country": "US",
      "ad_cost_start": 100,
      "ad_cost_end": 1000,
      "extend_keywords": [
        {
          "field": "ad_content",
          "value": "sale",
          "logic_operator": "and"
        }
      ],
      "order_by": "ad_started_at",
      "direction": "desc",
      "with_ad_status_group": "true"
    }
  }'

Response Parameters

Response Body Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "ad_started_at_group": {},
    "ad_status_group": {},
    "current_page": 1,
    "data": [],
    "first_page_url": "",
    "from": 1,
    "last_page": 10,
    "last_page_url": "",
    "next_page_url": "",
    "path": "",
    "per_page": 20,
    "prev_page_url": "",
    "to": 20,
    "total": 200,
    "search_after": [],
    "has_more": false,
    "is_manual_search": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Response Field Description

Field Type Description
code Integer Business status code, 200 indicates success
message String Response message, typically "success" on success
data Object Response data object
version String API version
timestamp Long 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 Whether request was successful
fail Boolean Whether request failed

Pagination Information Fields

Field Type Description
ad_started_at_group Object First ad date statistics, returned only if with_ad_started_at_group is set
ad_status_group Object Ad count by status, returned only if with_ad_status_group is set
current_page Integer Current page number
data Array Ad data list, contains array of ad information
first_page_url String First page URL
from Integer Starting record number of current page
last_page Integer Last page number, can be used to determine total pages
last_page_url String Last page URL
next_page_url String Next page URL
path String Pagination path
per_page Integer Page size, number of records returned per page
prev_page_url String Previous page URL
to Integer Ending record number of current page
total Integer Total data count, total number of ads matching the filter criteria
search_after Array Deep pagination "marker", returned only if search_after is set
has_more Boolean Whether there are more results, returned only if search_after is set
is_manual_search Boolean Whether free user has changed filter criteria, true = yes

First Ad Date Statistics Fields (ad_started_at_group)

When with_ad_started_at_group is set in the request, this field will be included in the response:

Field Type Description
today Integer Today
yesterday Integer Yesterday
last_7_days Integer Last 7 days
last_30_days Integer Last 30 days
last_90_days Integer Last 90 days
total Integer Total

Ad Status Statistics Fields (ad_status_group)

When with_ad_status_group is set in the request, this field will be included in the response:

Field Type Description
ad_status_1 Integer Active
ad_status_2 Integer Inactive
ad_status_3 Integer Removed
ad_status_all Integer Total

Ad Information Fields (data)

Field Type Description
id String Ad ID, internal unique identifier
active_days Long Ad duration
ad_audience Object Audience
ad_audience_reach Long Reach
ad_content String Ad text
ad_cost Double Ad spend
ad_forecast Long Ad prediction
ad_platform Array Ad platform
ad_started_at Long Ad creation time
ad_status Long Active status
adset_count Long Adset count
advertiser Object Advertiser
button_type String Button type
button_text String Button text
cards Array Carousel
country Array Country
first_discovered_at Long Ad discovery time
images Array Images
landing_page_type Long Landing page type
landing_pages Array Landing page URLs
language String Language
last_discovered_at Long Ad last update time
latest_actived_at Long Ad last active time
media_format Long Media format
products Array Ad products
source_ad_id String Source ad ID
store Object Ad store
user_collected Integer User collected ad, 1: yes; 2: no
videos Array Videos
related_roots Array Advertisers based on domain
group_name String Collection group name
favorite_time Long Collection time, timestamp
store_id String Store ID, corresponds to store.pipiads_biz_id
root_path_id String root_path database ID
shop_id String TikTok shop ID, null for PPSPY data
app_id String App ID, null for PPSPY data

Ad Audience Information Fields (ad_audience)

Field Type Description
age_audience Object Audience age range
details Array Audience country details
gender_audience String Audience gender group
total_reach Long Total audience reach

Audience Age Range Fields (age_audience)

Field Type Description
max Long Maximum age
min Long Minimum age

Audience Country Details Fields (details)

Field Type Description
age_gender_breakdowns Array Audience details
country String Country
total_reach Long Audience count

Age Gender Breakdown Fields (age_gender_breakdowns)

Field Type Description
age_range String Age range
female Long Female count
male Long Male count
unknown Long Other count

Advertiser Information Fields (advertiser)

Field Type Description
id String Advertiser ID
name String Advertiser page name
ad_count Long Advertiser page creative count
ad_country Array Countries advertised in
ads_library_link String Library link
adset_count Long Adset count
e_commerce_platform String E-commerce platform
like_count Long Advertiser page likes
profile_picture_url String Advertiser profile picture URL
source_advertiser_id String Page ID
source_advertiser_link String Advertiser source link
user_blocked Integer User blocked advertiser, 1: yes; 2: no
Field Type Description
cover_url String Video cover image URL
duration Long Video duration
height Long Video/image height
media_type Long Media type, 1: video; 2: image
url String Video/image URL
width Long Video/image width

Image Information Fields (images)

Field Type Description
height Long Image height
url String Image URL
width Long Image width

Video Information Fields (videos)

Field Type Description
cover_url String Video cover URL
duration Long Video duration
height Long Video height
url String Video URL
width Long Video width

Product Information Fields (products)

Field Type Description
id String Product ID
name String Product name
ad_cost Double Ad spend
ad_cost_ratio Double Product ad spend ratio in this ad, 0~1
ad_count Long Product ad creative count
ad_ended_at Long Ad end time
ad_started_at Long Ad start time
category_id String Category ID
category_name String Category name
creation_time Long Creation time
currency String Currency
image_url String Product image
price Double Product price
price_usd Double Product price (USD)
source_product_link String Product link
total_revenue Double Product revenue

Store Information Fields (store)

Field Type Description
id String Store ID
name String Store name
ad_count Long Store creative count
e_commerce_platform String E-commerce platform
e_commerce_types Array E-commerce types
logo_url String Store logo image
source_store_link String Store link
pipiads_biz_id String Pipiads store ID

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "ad_started_at_group": {
      "today": 10,
      "yesterday": 25,
      "last_7_days": 150,
      "last_30_days": 500,
      "last_90_days": 1200,
      "total": 41166
    },
    "ad_status_group": {
      "ad_status_1": 15000,
      "ad_status_2": 20000,
      "ad_status_3": 6166,
      "ad_status_all": 41166
    },
    "current_page": 1,
    "data": [
      {
        "id": "428822805b9d1826ae0486cb66311288",
        "active_days": 1,
        "ad_audience": {
          "details": [
            {
              "country": "BE",
              "age_gender_breakdowns": [
                {
                  "female": 0,
                  "male": 1,
                  "unknown": 0,
                  "age_range": "25-34"
                }
              ],
              "total_reach": 2
            }
          ],
          "age_audience": {
            "max": 65,
            "min": 25
          },
          "gender_audience": "All",
          "total_reach": 0
        },
        "ad_audience_reach": 0,
        "ad_content": "No knife skills, no stress — just load, press, and boom, you've got sushi 🍱🙌",
        "ad_cost": 1.37,
        "ad_forecast": 1,
        "ad_platform": [
          "FACEBOOK",
          "INSTAGRAM",
          "AUDIENCE_NETWORK",
          "MESSENGER",
          "THREADS"
        ],
        "ad_started_at": 1752130800,
        "ad_status": 2,
        "adset_count": 1,
        "advertiser": {
          "id": "c979c0120e4b6d5dae0486cb66311288",
          "name": "Stumpf Alston Nicholas",
          "ad_count": 643,
          "ad_country": [
            "SE",
            "ES",
            "BE",
            "AT",
            "DE",
            "FR",
            "IT",
            "IE",
            "PT",
            "NL"
          ],
          "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=127604557091989",
          "adset_count": 1381,
          "e_commerce_platform": "shopify",
          "like_count": 7,
          "profile_picture_url": "https://fb-cdn.pipispy.com/images/af109907042f563cd317a8a64ddce21e.png",
          "source_advertiser_id": "127604557091989",
          "source_advertiser_link": "https://facebook.com/61550723637932",
          "user_blocked": 2
        },
        "button_text": "Shop now",
        "button_type": "SHOP_NOW",
        "cards": [],
        "country": [
          "BE",
          "DE",
          "GB",
          "DK",
          "FI",
          "PT",
          "SE",
          "IE",
          "IT",
          "ES",
          "AT"
        ],
        "first_discovered_at": 1752188451,
        "images": [],
        "landing_page_type": 1,
        "landing_pages": [
          "https://counitty.com/products/ultimate-sushi-making-kit"
        ],
        "language": "en",
        "last_discovered_at": 1752188451,
        "latest_actived_at": 1752130800,
        "media_format": 1,
        "products": [
          {
            "id": "b71e0551cfbb314175c4dac1b4cf2dfc",
            "name": "🍣 Ultimate Sushi Making Kit | Fun for All Ages · Easy to Use · Dishwasher Safe 🎉",
            "ad_count": 7,
            "ad_cost": 15.52,
            "ad_cost_ratio": 0.0883,
            "ad_ended_at": 1752130800,
            "ad_started_at": 1752130800,
            "category_id": "62739b6038365b2f72048ec1",
            "category_name": "Home & Garden",
            "creation_time": 1752134135,
            "currency": "GBP",
            "image_url": "https://fb-cdn.pipispy.com/images/pimg_8372835ac9512990130d7.png",
            "price": 17.0,
            "price_usd": 23.1,
            "source_product_link": "https://counitty.com/products/ultimate-sushi-making-kit"
          }
        ],
        "source_ad_id": "1489834018843759",
        "store": {
          "id": "7458071d08bd6c3c75c4dac1b4cf2dfc",
          "name": "Community Nail Care CenterLTD",
          "ad_count": 421,
          "e_commerce_platform": "shopify",
          "e_commerce_types": [1, 2],
          "logo_url": "https://fb-cdn.pipispy.com/images/store_logo.png",
          "source_store_link": "https://counitty.com",
          "pipiads_biz_id": "biz_123456"
        },
        "user_collected": 2,
        "videos": [
          {
            "duration": 21,
            "height": 1280,
            "url": "https://fb-cdn.pipispy.com/videos/63a2820717c43d00f1481d20af5d0b6d.mp4",
            "width": 720,
            "cover_url": "https://fb-cdn.pipispy.com/images/d38b7ac2a4d956e541d338d84b3d10ae.png"
          }
        ],
        "related_roots": [
          "counitty.com"
        ],
        "favorite_time": 0,
        "group_name": null,
        "store_id": "biz_123456",
        "root_path_id": "root_123",
        "shop_id": null,
        "app_id": null
      }
    ],
    "first_page_url": "http://app.ppspy.com/v1/lib-ads/list?page=1",
    "from": 1,
    "last_page": 2059,
    "last_page_url": "http://app.ppspy.com/v1/lib-ads/list?page=2059",
    "next_page_url": "http://app.ppspy.com/v1/lib-ads/list?page=2",
    "path": "http://app.ppspy.com/v1/lib-ads/list",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 41166,
    "search_after": null,
    "has_more": false,
    "is_manual_search": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Error Code Description

Error Code Description
200 Success
400 Bad request - please check parameter format and value ranges
401 Unauthorized - API key is invalid or expired
403 Forbidden - insufficient balance or API access restricted
404 Not found - API path does not exist
444 Too many requests - rate limit triggered
500 Internal server error - please try again later

Important Notes

  1. Pagination Limits: Recommended page size is 20-100; larger page sizes may affect response time
  2. Time Format: All time fields use Unix timestamp (seconds); please convert accordingly
  3. Array Parameters: When using array-type filter conditions, results will match any value in the array (OR logic)
  4. Range Filters: When using paired start and end parameters, ensure start ≤ end
  5. Keyword Search: extend_keywords and exclude_keywords can be used together; inclusion filters are applied first, then exclusion filters
  6. Sort Optimization: Recommend specifying order_by and direction parameters; otherwise default sorting (ad_started_at descending) will be used
  7. Deep Pagination: For large datasets, recommend using search_after parameter for better performance
  8. Statistics Fields: with_ad_status_group and with_ad_started_at_group only affect statistics in the response, not the data list content
  9. Data Updates: Ad data is updated regularly; recommend periodic re-querying for latest data
  10. Multi-value Parameters: Some fields support multiple comma-separated values, such as country, ad_platform, etc.
  11. Keyword Fields: extend_keywords and exclude_keywords support field values including all, ad_content, landing_pages, advertiser_name, product_name, product, store, app_name, app_developer_name, advertiser, material, etc.
  12. E-commerce Platforms: e_commerce_platform supports platforms including shopify, woocommerce, magento, prestashop, opencart, bigcommerce, ecwid, shopline, shoplazza, wix, squarespace, etc.