Store Ad Meta Ads Library Delivery Trend Analysis API

API Information

API Name: Store Ad Meta Ads Library Delivery Trend Analysis API
Request Method: POST
API Endpoint: /open-api/v1/data
API Path: /v3/api/open/ppspy/pp-stores/analysis/ad-trend
API Description: Retrieve ad delivery trend data for a specified store in the Meta Ads Library, including historical trends of active ad count, total ad count, and new ad count
Pricing: Free

Request Headers:

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

Request Parameters

Request Structure

Parameter	Type	Description	Example	Required
key	string	User's external API request key	"your_api_key_here"	Yes
uri	string	API path	"/v3/api/open/ppspy/pp-stores/analysis/ad-trend"	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
start_time	Long	Yes	Query start time, Unix timestamp (seconds). Used to specify the start date for statistics
end_time	Long	Yes	Query end time, Unix timestamp (seconds). Used to specify the end date for statistics. Recommended time range should not exceed 90 days for optimal performance

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/analysis/ad-trend",
    "params": {
        "id": "c2d5b2547218a",
        "start_time": 1700000000,
        "end_time": 1707776000
    }
  }'

Response Parameters

Response Body Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [],
    "ad_count_history": [],
    "ad_started_history": [],
    "is_logged_in": false
  },
  "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

Ad Trend Analysis Data Fields (data.data)

Field	Type	Description
active_ad_count_history	Array	Historical data of active ad count, records the number of ads actively running each day. Active ads are ads still in delivery status on that day
ad_count_history	Array	Historical data of total ad count, records the cumulative total number of ads each day. This is a cumulative value including all historical ads (active + stopped)
ad_started_history	Array	Historical data of new ad count, records the number of ads that started running each day. Indicates new ads that went live on that day
is_logged_in	Boolean	Whether the user is logged in, used to identify data permission status

Historical Data Item Fields (HistoryItem)

Each element in the active_ad_count_history, ad_count_history, and ad_started_history arrays contains the following fields:

Field	Type	Description
date	String	Statistical date, format is yyyy-MM-dd (e.g., 2024-01-15)
count	Long	Count value for that date. Depending on the array, it represents: active ad count, total ad count, or new ad count

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 125
      },
      {
        "date": "2024-01-02",
        "count": 138
      },
      {
        "date": "2024-01-03",
        "count": 145
      }
    ],
    "ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 1500
      },
      {
        "date": "2024-01-02",
        "count": 1523
      },
      {
        "date": "2024-01-03",
        "count": 1548
      }
    ],
    "ad_started_history": [
      {
        "date": "2024-01-01",
        "count": 15
      },
      {
        "date": "2024-01-02",
        "count": 23
      },
      {
        "date": "2024-01-03",
        "count": 25
      }
    ],
    "is_logged_in": false
  },
  "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