# 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](https://www.pipispy.com/zh/doc/others-product-category) |
| 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 |
#### Keyword Search
| 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
```bash
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
```json
{
"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 |
### Carousel Information Fields (cards)
| 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
```json
{
"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.