Store Meta Ads Library Longest Running Ad Content List API
- API Name: Get Store Longest Running Ad Content List
- Request Method: POST
- API Endpoint:
/open-api/v1/data
- API Path:
/v3/api/open/ppspy/pp-stores/ad-content/longest-run
- API Description: Retrieve the list of ad content with the longest running time in the Meta Ads Library for a specified store, including ad content, media materials (images/videos/carousels), days of operation, etc., to help analyze the store's long-term stable advertising materials
- Pricing:
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 |
API path |
"/v3/api/open/ppspy/pp-stores/ad-content/longest-run" |
Yes |
|
| params |
object |
API input parameter object |
See parameter list |
Yes |
|
Request Body Parameters (params object)
| Parameter |
Type |
Required |
Description |
| id |
String |
Yes |
Store unique identifier ID, a 13-character string (e.g., c2d5b2547218a), corresponds to the store_id field in the store ranking list API response |
| order_by |
String |
No |
Sort field. Options: active_days-sort by days active, ad_started_at-sort by ad start time. Default: active_days |
| direction |
String |
No |
Sort order. Options: desc-descending (large to small/new to old), asc-ascending (small to large/old to new). Default: desc |
| page_size |
Long |
No |
Number of records per page, specifies the number of ads returned per page. Default: 20 |
| current_page |
Long |
No |
Current page number, pages start from 1. Default: 1 |
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/ppspy/pp-stores/ad-content/longest-run",
"params": {
"id": "c2d5b2547218a",
"order_by": "active_days",
"direction": "desc",
"page_size": 20,
"current_page": 1
}
}'
Response Parameters
Response Body Structure
{
"code": 200,
"message": "success",
"data": {
"current_page": 1,
"data": [],
"first_page_url": "",
"from": 1,
"is_logged_in": false,
"last_page": 1,
"last_page_url": "",
"next_page_url": null,
"path": "",
"per_page": 20,
"prev_page_url": null,
"to": 20,
"total": 100
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"success": true,
"fail": false
}
Response Field Description
| Field |
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 |
Whether the request was successful |
| fail |
Boolean |
Whether the request failed |
| Field |
Type |
Description |
| current_page |
Long |
Current page number |
| data |
Array |
Ad content list |
| first_page_url |
String |
URL of the first page |
| from |
Long |
Starting record position (position of the first record of the current page in the total result set) |
| is_logged_in |
Boolean |
Whether the user is logged in, used to identify data permission status |
| last_page |
Long |
Last page number (total pages) |
| last_page_url |
String |
URL of the last page |
| next_page_url |
String |
URL of the next page, null if no next page |
| path |
String |
API request path |
| per_page |
Long |
Number of records per page |
| prev_page_url |
String |
URL of the previous page, null if no previous page |
| to |
Long |
Ending record position (position of the last record of the current page in the total result set) |
| total |
Long |
Total number of records |
Ad Content Fields (AdContent)
| Field |
Type |
Description |
| id |
String |
Ad unique identifier ID |
| source_ad_id |
String |
Original ad ID (unique ad identifier from source platform) |
| ad_content |
String |
Ad copy content |
| media_format |
Long |
Media format type. 1-Single image, 2-Single video, 3-Carousel |
| images |
Array |
Image material list, has value when media_format=1 |
| videos |
Array |
Video material list, has value when media_format=2 |
| cards |
Array |
Carousel card list, has value when media_format=3 |
| ad_started_at |
Long |
Ad start time, Unix timestamp (seconds) |
| active_days |
Long |
Days the ad has been active (from start to now or end) |
| ad_status |
Long |
Ad status. 1-Active, 2-Inactive, 3-Removed |
| ad_content_md5 |
String |
MD5 hash of ad content, used to identify ads with the same content |
Image Material Fields (Image)
| Field |
Type |
Description |
| url |
String |
Image resource URL |
| width |
Long |
Image width (pixels) |
| height |
Long |
Image height (pixels) |
Video Material Fields (Video)
| Field |
Type |
Description |
| url |
String |
Video resource URL |
| width |
Long |
Video width (pixels) |
| height |
Long |
Video height (pixels) |
| duration |
Double |
Video duration (seconds) |
| cover_url |
String |
Video cover image URL |
Carousel Card Fields (Card)
| Field |
Type |
Description |
| url |
String |
Card media resource URL (image or video) |
| width |
Long |
Media width (pixels) |
| height |
Long |
Media height (pixels) |
| duration |
Double |
Video duration (seconds), has value only when media_type=1 |
| cover_url |
String |
Video cover image URL, has value only when media_type=1 |
| media_type |
Long |
Media type. 1-Video, 2-Image |
Response Example
{
"code": 200,
"message": "success",
"data": {
"current_page": 1,
"data": [
{
"id": "ad_001",
"source_ad_id": "123456789012345",
"ad_content": "Shop now and get 50% off! Limited time offer. Free shipping on orders over $50.",
"media_format": 2,
"images": [],
"videos": [
{
"url": "https://example.com/video/ad_video_001.mp4",
"width": 1080,
"height": 1920,
"duration": 15.5,
"cover_url": "https://example.com/cover/ad_cover_001.jpg"
}
],
"cards": [],
"ad_started_at": 1680000000,
"active_days": 180,
"ad_status": 1,
"ad_content_md5": "a1b2c3d4e5f6g7h8i9j0"
},
{
"id": "ad_002",
"source_ad_id": "123456789012346",
"ad_content": "New arrivals! Check out our latest collection.",
"media_format": 3,
"images": [],
"videos": [],
"cards": [
{
"url": "https://example.com/image/card_001.jpg",
"width": 1080,
"height": 1080,
"duration": null,
"cover_url": null,
"media_type": 2
},
{
"url": "https://example.com/video/card_002.mp4",
"width": 1080,
"height": 1080,
"duration": 10,
"cover_url": "https://example.com/cover/card_002.jpg",
"media_type": 1
}
],
"ad_started_at": 1685000000,
"active_days": 120,
"ad_status": 1,
"ad_content_md5": "b2c3d4e5f6g7h8i9j0k1"
},
{
"id": "ad_003",
"source_ad_id": "123456789012347",
"ad_content": "Best seller! Don't miss out.",
"media_format": 1,
"images": [
{
"url": "https://example.com/image/ad_image_001.jpg",
"width": 1200,
"height": 628
}
],
"videos": [],
"cards": [],
"ad_started_at": 1690000000,
"active_days": 90,
"ad_status": 0,
"ad_content_md5": "c3d4e5f6g7h8i9j0k1l2"
}
],
"first_page_url": "https://api.example.com/ads?page=1",
"from": 1,
"is_logged_in": false,
"last_page": 5,
"last_page_url": "https://api.example.com/ads?page=5",
"next_page_url": "https://api.example.com/ads?page=2",
"path": "https://api.example.com/ads",
"per_page": 20,
"prev_page_url": null,
"to": 20,
"total": 100
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"success": true,
"fail": false
}
Error Code Description
| Error Code |
Description |
| 200 |
Success |
| 400 |
Invalid request parameters |
| 401 |
Unauthorized |
| 403 |
Insufficient permissions |
| 500 |
Internal server error |