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.

Adspy Detail API

API Information

  • API Name: Get Adspy Detail
  • Request Method: POST
  • API Endpoint: /open-api/v1/data
  • Interface URI: /v3/api/open/adspy/detail
  • Description: Retrieves detailed Adspy information by ad ID
  • Pricing: The base cost is 1 credit per request. A request is free if either condition applies: the same ID was retrieved within the previous 3 days, or the ID appeared in your ranking-list query results within the previous 3 days.

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 assigned to the user "your_api_key_here" Yes
uri string Interface URI "/v3/api/open/adspy/detail" Yes
params object Interface parameter object See the parameter table below Yes

Parameter List (params Object)

Parameter Type Required Description
id String Yes Unique ad creative identifier. Use the video_id returned by the Adspy List API

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/adspy/detail",
    "params": {
      "id": "1795208137186337"
    }
  }'

Response Parameters

Response Body Structure

{
  "code": 200,
  "message": "success",
  "data": {},
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}

Response Fields

Field Type Description
code Integer Business status code. 200 indicates success; any other value indicates failure
message String Response message. On failure, describes causes such as invalid parameters or missing data
data Object/null Adspy detail object. May be null when no matching ad is found
version String Open API response version, such as v1
timestamp Number/null Gateway response timestamp; null when disabled
sign String/null Response signature; null when signature verification is disabled
remaining_credits Long Available credits remaining for the API key after this request
consumed_credits Long Credits consumed by this request; may be 0 when a free-access condition applies
success Boolean Whether the business request succeeded; true on success
fail Boolean Whether the business request failed; the inverse of success

Adspy Detail Fields

Field usage notes:

  • All time fields are Unix timestamps in seconds, such as 1752199828. Convert them to the consumer's display time zone as needed.
  • Play, like, comment, share, and favorite metrics are cumulative values from the latest collection and may not match the media platform in real time.
  • URLs may become unavailable because the source ad was removed, regional restrictions apply, or the media platform requires authentication. Consumers should handle access failures.
  • Fields that do not apply to the current platform or creative type may be null, an empty string, an empty array, or omitted. Do not use field presence to determine request success.
  • Union types such as Number/String and Array/String support legacy data. Deserializers should accept all documented types.
Field Type Description
active_status Number Ad activity status, consistent with ad_state in the list API. 1 means the ad has been observed recently and may still be running; 0 means it has stopped or no recent delivery has been observed
ad_advertiser Object/null Advertiser information. null when no advertiser can be associated; see the nested fields below
ad_create_time Number Time the ad was created or first published on the media platform, as a Unix timestamp in seconds
ad_developer Object/null Developer associated with the promoted app. null for non-app ads or when no developer is linked
ad_fee Long Compatibility metric calculated as play_count / 1000; not the actual media-account spend. Use the CPM estimate fields for the displayed spend range
ad_id String Ad ID assigned by the media platform. A creative may have different ad_id and video_id values
ad_shop Object/null TikTok Shop associated with the ad. null for non-TikTok-Shop ads
ad_store Object/null Website or independent store associated with the landing page. null when no store is identified
aigc_label_type Number/null AI-video label. 0 or null means the video is not identified as AI-generated; another value identifies the corresponding AIGC type
ai_analysis Object/null AI analysis of the video content. May be null for non-video ads or while analysis is unavailable
app_dev Object/null Original app developer data, commonly including id, name, icon, and url
app_image String Full URL of the advertiser avatar, TikTok account avatar, or app icon
app_info Object/null Details of the promoted app, including its name, rating, downloads, category, and revenue. null for non-app ads
app_name String Advertiser name. Usually the account nickname for TikTok and the page or advertiser name for Facebook
app_store String App store identifier, such as apple or google; may be empty for non-app ads
app_system String App operating system, such as ios or android; may be empty for non-app ads
app_type String Type of promoted destination, such as app, game, or web
app_url String Landing page, app store page, or product page opened when the user clicks the ad
age_range Array Original audience age-range list. Usually empty when unavailable; use audience.age for display
aspect_ratio String Normalized creative dimension string. TikTok usually returns widthxheight, such as 576x1024; this is not necessarily a mathematical aspect ratio
ad_category Array Original ad category list; usually an empty array when unavailable
audience Object Audience overview including reach, regions, ages, genders, and sources
carousel Array Creative cards for a carousel ad. Present only when type=3; see the nested fields below
clarity String/null Video quality label, such as SD or HD; null when unavailable
collect_count Number Cumulative favorite count collected from the media platform; usually 0 when unsupported
comment_count Number Cumulative comment count collected from the media platform
content_list Array Normalized ad copy, CTA, and landing-page entries. Carousel ads may contain multiple entries
cover String Full video cover image URL; may be empty for image ads or when no cover is available
data_type String/null String representation of the business-category set, such as "[3,4]". Unlike the list API, this is not a JSON array; see the enumerations below
digg_count Number Cumulative like count collected from the media platform
digg_play_rate Number Like rate, normally a decimal from 0 to 1; for example, 0.0033 is approximately 0.33%
download_count Number Cumulative download count collected from the media platform; usually 0 when unsupported
duration Number/String Video duration in seconds. May be an empty string for non-video ads or when unavailable; consumers must support both types
fetch_region Array/String Compatibility field. Usually an array of country/region codes when available, or an empty string when absent. Use audience.region for delivery regions
facebook_category Array/null Categories assigned by Facebook; usually empty or omitted for non-Facebook ads
facebook_display_format String Facebook display format, such as video, image, or carousel; may be empty for non-Facebook ads
facebook_like_info Array/null Facebook reaction statistics. Each item contains a reaction type and count; see the nested fields below
facebook_link String Facebook ad, post, or Ad Library URL; may be empty for non-Facebook ads
forward_count Number Cumulative forward count; normally 0 on platforms that do not provide this metric
found_time Number Time PipiAds first discovered the ad, as a Unix timestamp in seconds; not the ad creation time
hot_value Number PipiAds popularity metric. A larger value generally indicates greater current engagement
image String Full URL of the primary image creative; usually empty for video ads
isSpark Boolean Compatibility-derived field inferred from is_ad_fake; it is not definitive proof of the platform's official Spark Ads status and may be omitted when the source flag is unavailable
is_ad_fake Boolean/null Ad authenticity classification: true means suspected copied or non-native content, false means not suspected, and null means unclassified
is_collection Boolean Whether the account associated with the current API key has saved this ad
is_download Boolean Whether the current API key may download this creative; this does not guarantee that the creative URL remains available
label Object/null Manual or system category label. null when unlabeled; may contain Chinese and English label names
language Array Ad content language codes, such as ["en"] or ["zh-cn"], generally using ISO language codes
last_put_time Number Most recent observed delivery time, currently based on modify_time, as a Unix timestamp in seconds
max_cpa Number/null Estimated maximum CPA based on PipiAds data and general target-region benchmarks; may contain estimation error and is null when unavailable
max_cpm Number/null Estimated maximum CPM based on PipiAds data and general target-region benchmarks; may contain estimation error and is null when unavailable
min_cpa Number/null Estimated minimum CPA based on PipiAds data and general target-region benchmarks; may contain estimation error and is null when unavailable
min_cpm Number/null Estimated minimum CPM based on PipiAds data and general target-region benchmarks; may contain estimation error and is null when unavailable
modify_time Number Most recent time the ad was observed running or its data changed, as a Unix timestamp in seconds
music_id String ID of the music or sound used by the TikTok video; may be empty on other platforms
music_name String Name of the music or sound used by the TikTok video; may be empty on other platforms
music_url String URL of the TikTok video's music or sound resource; may be empty on other platforms
pack_url String App package download URL; an empty string when unavailable
platform Number Platform: 1 TikTok, 2 Facebook
play_count Number Cumulative plays or impressions collected from the media platform; the exact definition varies by platform
popular_person_id String/null PipiAds influencer-profile ID associated with the TikTok author; omitted or null when no profile is linked
product_currency String Product currency code, such as USD or THB
product_id String PipiAds ID of the associated product
product_image String Full URL of the associated product's primary image
product_price String Product price string, which may contain decimals or a currency symbol; treat it as display text
product_title String Name or title of the associated product
publisher_platform Array Platforms on which the ad was published, such as ["facebook","instagram"] or ["tiktok"]
put_days Number Cumulative number of observed delivery days
resolution String Creative resolution, normally widthxheight, such as 540x960
root_path String Root domain extracted from the landing page, such as example.com; not a complete URL
root_path_id String Unique PipiAds profile ID for the root domain or advertiser
search_by_image_tag Boolean Whether image-similarity search is supported for the product image associated with this ad
share_count Number Cumulative share count collected from the media platform
size String/null Creative aspect-ratio or size label, such as 9:16; null when unavailable
shop_type String/null Detected site builder or e-commerce platform, such as Shopify; null when unidentified or not applicable
source Array Ad source device or operating system list, such as ["Android"]
tiktok_author String TikTok publisher username, corresponding to the name after @ in the profile URL
tiktok_author_url String Full URL of the TikTok publisher profile
tiktok_shop Array TikTok Shop products attached to the ad. May contain multiple products; see the nested fields below
type Number Creative type: 1 video, 2 image, 3 carousel
update_time Number Detail update time. TikTok currently uses modify_time; Facebook uses facebook_update_time. Unix timestamp in seconds
url String Media-platform post or ad URL. TikTok derives it from the creative ID, while Facebook usually uses facebook_link; differs from external landing-page app_url
url_history Array Previously resolved redirect URLs for the landing page; may be used to reconstruct the redirect chain
video_id String Unique PipiAds creative ID and the recommended id when calling this API
video_url String Full video file URL; present only for video creatives or carousel cards containing video

Field Enumerations

Field Value Description
platform 1 TikTok ad
platform 2 Facebook/Meta ad, potentially published across Facebook, Instagram, and other placements
type 1 Video creative
type 2 Single-image creative
type 3 Carousel creative; see carousel for individual cards
data_type 1 Product or trending-product ad
data_type 2 TikTok Shop ad
data_type 3 Web e-commerce ad
data_type 4 Brand or Spark Ads category
data_type 5 Game ad
data_type 6 App ad
data_type 7 AI app ad
data_type 8 Short-drama app ad
data_type 9 AI web ad
data_type 10 Short-drama web ad

data_type may contain multiple categories. For example, "[2,3,4]" means the ad has TikTok Shop, e-commerce, and brand/Spark Ads attributes.

AI Analysis Fields (ai_analysis Object)

Field Type Description
ai_analysis_language String Primary ad language identified by AI, such as en or zh-cn
ai_analysis_human_presenter String Whether AI detected a human presenter; returned as a string such as yes, no, true, or false
ai_analysis_main_hook String Main marketing hook, opening selling point, or attention-grabbing message extracted by AI
ai_analysis_script String Ad script derived from video speech, subtitles, and visual content
ai_analysis_tags Array AI-generated topic, product, scenario, and selling-point tags, such as ["#shoes","#sale"]

Audience Fields (audience Object)

Field Type Description
gender Array Audience gender list; may contain all, men, or women; empty when unavailable
covered Number/null Estimated reach. For TikTok this commonly represents play reach; for Facebook it represents available audience reach
source Array Audience source device or operating system list, such as ["Android"]
region Array Audience country/region codes, such as ["TH"]
category Array Ad or audience-interest categories
age Array Age ranges, such as ["25-35","35-45"]
max_data Object Summary of the leading Facebook audience region and age range; omitted when detailed audience data is unavailable

Facebook Audience Summary Fields (audience.max_data Object)

Field Type Description
region String Country/region code with the highest reach
ragion_rate Number Share of reach for the leading region, from 0 to 1; the field name preserves the API's spelling
age String Age range with the highest reach
age_rate Number Share of reach for the leading age range, from 0 to 1

Content List Fields (content_list Array Items)

Field Type Description
cta String Call-to-action text, such as Shop Now, Learn More, or Buy Now
cta_text String CTA text for a Facebook carousel card; returned only for some carousel items
caption String Facebook ad-card caption or short description
landing_page String Landing-page URL opened when the user clicks this content item
title String Ad title, app name, or carousel-card title
desc String Ad copy, video description, or card body
url_history Array Landing-page redirect URLs associated with this content item
link_description String Supplementary text displayed below a Facebook ad link

TikTok Shop Fields (tiktok_shop Array Items)

Field Type Description
new_source Number Product-source identifier used to distinguish data channels; consumers may preserve it as an opaque value
image String Full URL of the TikTok Shop product's primary image
product_id String TikTok Shop product ID, uniquely identifying the product on the platform
shop_id String ID of the TikTok Shop that owns the product
real_price String Current display price, usually including a currency symbol, such as $10.04
original_price String List price or price before discount; may be empty when no discount is available
title String Full TikTok Shop product title
category_id_list Array TikTok Shop category IDs, potentially containing multiple category levels
url String Full TikTok Shop product detail URL
sold_count Number Cumulative sales displayed on the product page

Associated Object Fields (ad_advertiser, ad_store, ad_shop, and ad_developer Objects)

Field Type Description
id String/null Unique ID of the associated object in PipiAds or the relevant media platform
store_id String/null Website/store ID associated with the advertiser; returned only by ad_advertiser
name String/null Advertiser, website store, TikTok Shop, or app developer name
avatar String/null Full URL of the advertiser avatar, store image, or developer icon
link String/null Advertiser root domain, store page, or developer page URL

Facebook Reaction Fields (facebook_like_info Array Items)

Field Type Description
count Number Cumulative count for the reaction type
id String Facebook reaction-type ID; may be empty when the platform provides no ID
localized_name String Localized reaction name, such as Like, Love, Wow, Haha, Sad, Angry, or Care
Field Type Description
type Number Card creative type: 1 video, 2 image
image String Creative URL for an image card
video_url String Video URL for a video card
cover String Cover image URL for a video card
duration String/Number Card video duration in seconds; legacy data may return a string
title String Card title
body String Card body text
caption String Short card caption; returned by some Facebook records
cta_text String Card call-to-action text
link_url String Landing-page URL opened when the card is clicked
link_description String Supplementary card link description
url_history Array Redirect URL history for the card landing page
aspect_ratio String Creative aspect ratio, such as 9:16
quality String Creative quality label, such as SD or HD
resolution String Creative resolution, such as 1080x1920

App Developer Fields (app_dev Object)

Field Type Description
id String Unique app developer ID
name String App developer name
icon String Full URL of the developer icon or avatar
url String Developer page URL in the app store or on the official website

App Information Fields (app_info Object)

Field Type Description
id String Unique app ID. The value may be obfuscated and is intended only for linking records within this Open API
name String App name displayed in the app store
url String App store detail-page URL
icon String App icon URL
download Number Cumulative downloads or the download count displayed by the app store
app_comment_count Number Cumulative app review count
category Object App category information; see the nested fields below
rate Object App rating information; see the nested fields below
revenue Object/null App revenue information; null when unavailable; see the nested fields below
last_month_app_download_count Number Estimated downloads during the most recent calendar month
create_time Number App record creation time as a Unix timestamp in seconds

App Rating Fields (app_info.rate Object)

Field Type Description
score Number Overall app rating
count Number Number of users who submitted a rating
rate1 Number Number of one-star ratings
rate2 Number Number of two-star ratings
rate3 Number Number of three-star ratings
rate4 Number Number of four-star ratings
rate5 Number Number of five-star ratings

App Category Fields (app_info.category Object)

Field Type Description
id String App category ID
name String App category name
type String Category type or level
app_system String Operating system associated with the category, such as ios or android
children Array Child categories; each item may contain id, name, type, and app_system

App Revenue Fields (app_info.revenue Object)

Field Type Description
value Number Revenue amount
unit String Monetary unit; for example, cent means the amount is expressed in cents
currency String Currency code, such as USD
type String Value type, such as currency

Response Example

{
  "comment_count": 1,
  "forward_count": 0,
  "pack_url": "",
  "source": [
    "Android"
  ],
  "type": 1,
  "resolution": "540x960",
  "ai_analysis": {
    "ai_analysis_language": "zh-cn",
    "ai_analysis_human_presenter": "yes",
    "ai_analysis_main_hook": "What are you secretly filming?",
    "ai_analysis_script": "What are you secretly filming? Thailand's DTV visa can be processed without leaving the country. Approval in as fast as 7 days, starting from just 9,000 yuan. Valid for 5 years, unlimited entries and exits to Thailand, stay up to 180 days per visit. Refunds available upon application. Click the link below to apply now.",
    "ai_analysis_tags": [
      "#DTVVisa",
      "#Thailand",
      "#NoNeedToLeave",
      "#Apply",
      "#ApprovalIn7Days",
      "#From9000Yuan",
      "#5YearValidity",
      "#UnlimitedEntries",
      "#180Days",
      "#RefundAvailable",
      "#LinkBelow",
      "#ApplyNow",
      "#Visa"
    ]
  },
  "cover": "https://cdn-video.pipispy.com/cover_6f730728bdc01d3cdce00223de09fc4f.jpg",
  "max_cpm": 2.4,
  "last_put_time": 1752199828,
  "root_path_id": "682e25abe87d0e8f5818189b",
  "put_days": 2,
  "image": "",
  "audience": {
    "gender": [],
    "covered": 909,
    "source": [
      "Android"
    ],
    "region": [
      "TH"
    ],
    "category": [],
    "age": [
      "35-45"
    ]
  },
  "play_count": 909,
  "ad_create_time": 1751942170,
  "ad_id": "1837044055239874",
  "root_path": "ccddsite88.net",
  "digg_count": 3,
  "content_list": [
    {
      "cta": "Learn More",
      "landing_page": "https://ccddsite88.net/landing-page/thailand/tk/1747707570548/?ttclid=E_C_P_CssBEU5QXACDVfMYNCqcBdOW23Ndidd7knaaqh33vgz0N3--FsUbYw0wC8RfDBrdG6Q0HLWvHnPjwINxzZrvXXozfcERzmjOAnAaD-B-tVEeQ1fnAfs3uWEPeRU9_45T4jl7QSzD1Zi-zQLz4IwgsHo2ssq9veFvzuXZnpw0b6lZcNRonZMSZBRxG-cjyUsRIvMKn-qkMV3Q1kCD2niYVect6n7ZTSrHK8f894b_6_5V7_sD2zGP2hudN80m55zW5hBOeM9tzNMJXreMoIoSBHYyLjA",
      "title": "Starting today, meet these 2 conditions for Thailand DTV, approval in as fast as 7 days, refundable!",
      "desc": "Starting today, meet these 2 conditions for Thailand DTV, approval in as fast as 7 days, refundable!",
      "url_history": []
    }
  ],
  "is_download": false,
  "publisher_platform": [
    "tiktok"
  ],
  "aspect_ratio": "540x960",
  "digg_play_rate": 0.0033,
  "modify_time": 1752199828,
  "min_cpa": 0.0,
  "is_collection": false,
  "platform": 1,
  "duration": 17,
  "update_time": 1752199828,
  "video_url": "https://cdn-video.pipispy.com/video_1cd71dc2169dd279821b1ba4736d4e19.mp4",
  "tiktok_author_url": "https://www.tiktok.com/@ThailandDTV",
  "ad_fee": 0,
  "min_cpm": 0.6,
  "app_url": "https://ccddsite88.net/landing-page/thailand/tk/1747707570548/?ttclid=E_C_P_CssBEU5QXACDVfMYNCqcBdOW23Ndidd7knaaqh33vgz0N3--FsUbYw0wC8RfDBrdG6Q0HLWvHnPjwINxzZrvXXozfcERzmjOAnAaD-B-tVEeQ1fnAfs3uWEPeRU9_45T4jl7QSzD1Zi-zQLz4IwgsHo2ssq9veFvzuXZnpw0b6lZcNRonZMSZBRxG-cjyUsRIvMKn-qkMV3Q1kCD2niYVect6n7ZTSrHK8f894b_6_5V7_sD2zGP2hudN80m55zW5hBOeM9tzNMJXreMoIoSBHYyLjA",
  "fetch_region": "",
  "max_cpa": 1.0,
  "url": "https://m.tiktok.com/v/7524534322666228999.html",
  "collect_count": 1,
  "download_count": 0,
  "share_count": 0,
  "tiktok_author": "ThailandDTV",
  "app_name": "ThailandDTV",
  "active_status": 1,
  "hot_value": 4,
  "data_type": "[4]",
  "url_history": [],
  "video_id": "496b74d6a6135f80c17d",
  "app_image": "https://cdn-video.pipispy.com/avatar_5eabd0708ef037d43a4377d740ae2c53.jpg"
}

Error Codes

Error Code Description
200 Request processed successfully. Also check whether data is null; data=null means no matching ad was found
400 Invalid request parameters, such as a missing, empty, or unsupported params.id
404 Some gateways or legacy versions may return this code when the ad does not exist. Consumers should also support 200 with data=null
500 Internal service or dependency error. Record message and use a limited retry strategy with backoff