# Store Meta Ads Library Most Used Ad Content List API ## API Information - **API Name**: Get Store Most Used Ad Content List - **Request Method**: POST - **API Endpoint**: `/open-api/v1/data` - **API Path**: `/v3/api/open/ppspy/pp-stores/ad-content/most-used` - **API Description**: Retrieve the list of most frequently used ad content in the Meta Ads Library for a specified store, including content, number of ads using this content, active ad count, delivery time, etc., to help analyze the store's core ad content strategy - **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/most-used" | 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: `ad_count`-sort by ad count, `active_ad_count`-sort by active ad count, `latest_ad_started_at`-sort by latest ad date. Default: `ad_count` | | 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 content items returned per page. Default: 20 | | current_page | Long | No | Current page number, pages start from 1. Default: 1 | ### 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/ppspy/pp-stores/ad-content/most-used", "params": { "id": "c2d5b2547218a", "order_by": "ad_count", "direction": "desc", "page_size": 20, "current_page": 1 } }' ``` ## Response Parameters ### Response Body Structure ```json { "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 | ### Pagination Data Fields (data.data) | 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 (Datum) | Field | Type | Description | | -------------------- | ------ | ---------------------------------------------------------------------------------------------------- | | id | String | Content record unique identifier ID | | ad_content_md5 | String | MD5 hash of ad content, used to identify content with the same text | | ad_content | String | Ad copy content | | ad_count | Long | Total number of ads using this content, indicates how many times this content has been reused | | active_ad_count | Long | Number of active ads using this content (currently running ads) | | ad_started_at | Long | First delivery time of this content, Unix timestamp (seconds) | | ad_ended_at | Long | Last delivery end time of this content, Unix timestamp (seconds) | | active_days | Long | Cumulative days this content has been active | | latest_ad_started_at | Long | Start time of the most recent ad using this content, Unix timestamp (seconds) | | percentage | Double | Usage percentage of this content among all store content (0.0-1.0) | ## Response Example ```json { "code": 200, "message": "success", "data": { "current_page": 1, "data": [ { "id": "content_001", "ad_content_md5": "a1b2c3d4e5f6g7h8i9j0", "ad_content": "Shop now and get 50% off! Limited time offer. Free shipping on orders over $50. Don't miss out on this amazing deal!", "ad_count": 85, "active_ad_count": 23, "ad_started_at": 1680000000, "ad_ended_at": 1700000000, "active_days": 230, "latest_ad_started_at": 1699500000, "percentage": 0.125 }, { "id": "content_002", "ad_content_md5": "b2c3d4e5f6g7h8i9j0k1", "ad_content": "New arrivals! Check out our latest collection. Premium quality at affordable prices.", "ad_count": 62, "active_ad_count": 18, "ad_started_at": 1685000000, "ad_ended_at": 1699800000, "active_days": 170, "latest_ad_started_at": 1699200000, "percentage": 0.091 }, { "id": "content_003", "ad_content_md5": "c3d4e5f6g7h8i9j0k1l2", "ad_content": "Best seller! Thousands of 5-star reviews. Order yours today!", "ad_count": 48, "active_ad_count": 0, "ad_started_at": 1670000000, "ad_ended_at": 1695000000, "active_days": 290, "latest_ad_started_at": 1694500000, "percentage": 0.071 } ], "first_page_url": "https://api.example.com/contents?page=1", "from": 1, "is_logged_in": false, "last_page": 10, "last_page_url": "https://api.example.com/contents?page=10", "next_page_url": "https://api.example.com/contents?page=2", "path": "https://api.example.com/contents", "per_page": 20, "prev_page_url": null, "to": 20, "total": 200 }, "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 |