API Marketing
Phiên bản API Đồ thị

Ad Account, Insights

The Insights API can return several metrics which are estimated or in-development. In some cases a metric may be both estimated and in-development.

  • Estimated - Provide directional insights for outcomes that are hard to precisely quantify. They may evolve as we gather more data. See Ads Help Center, Estimated metrics.

  • In Development - Still being tested and may change as we improve our methodologies. We encourage you to use it for directional guidance, but please use caution when using it for historical comparisons or strategic planning. See Ads Help Center, In development metrics.

For more information, see Insights API, Estimated and Deprecated Metrics

Facebook will no longer be able to aggregate non-inline conversion metric values across iOS 14.5 and non-iOS 14.5 campaigns due to differences in attribution logic. Querying across iOS 14.5 and non-iOS 14.5 campaigns will result in no data getting returned for non-inline conversion metrics such as app installs and purchases. Inline event metrics like impressions, link clicks, and video views, however, can still be aggregated. Please visit our changelog for more information.

The date_preset = lifetime parameter is disabled in Graph API v10.0 and replaced with date_preset = maximum, which returns a maximum of 37 months of data. For v9.0 and below, date_preset = maximum will be enabled on May 25, 2021, and any lifetime calls will default to maximum and return only 37 months of data.

Đọc

Provides insights on your advertising performance. Allows for deduped metrics across child objects, such as unique_clicks, sorting of metrics, and async reporting.

Ví dụ

Graph API Explorer
GET /v21.0/<AD_SET_ID>/insights?fields=impressions&breakdown=publisher_platform HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/<AD_SET_ID>/insights?fields=impressions&breakdown=publisher_platform',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/<AD_SET_ID>/insights",
    {
        "fields": "impressions",
        "breakdown": "publisher_platform"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("fields", "impressions");
params.putString("breakdown", "publisher_platform");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/<AD_SET_ID>/insights",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
NSDictionary *params = @{
  @"fields": @"impressions",
  @"breakdown": @"publisher_platform",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/<AD_SET_ID>/insights"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X GET -G \
  -d 'fields="impressions"' \
  -d 'breakdown="publisher_platform"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<AD_SET_ID>/insights
Nếu bạn muốn tìm hiểu cách sử dụng API Đồ thị, hãy đọc Hướng dẫn sử dụng API Đồ thị của chúng tôi.

Thông số

Thông sốMô tả
action_attribution_windows
list<enum{1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, 1d_ev, dda, default, 7d_view_first_conversion, 28d_view_first_conversion, 7d_view_all_conversions, 28d_view_all_conversions, skan_view, skan_click}>
Giá trị mặc định: default

The attribution window for the actions.
For example, 28d_click means the API returns all actions that happened 28 days after someone clicked on the ad. 1d_ev refers to engaged-view conversions counted when a skippable video ad is played for at least 10 seconds, or for at least 97% of its total length if it’s shorter than 10 seconds, and a person takes an action within 1 day.
The default option means ["7d_click","1d_view"].

action_breakdowns
list<enum{action_device, conversion_destination, matched_persona_id, matched_persona_name, signal_source_bucket, standard_event_content_type, action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}>
Giá trị mặc định: Vec

How to break down action results. Supports more than one breakdowns. Default value is ["action_type"].

action_report_time
enum{impression, conversion, mixed}

Determines the report time of action stats. For example, if a person saw the ad on Jan 1st but converted on Jan 2nd, when you query the API with action_report_time=impression, you see a conversion on Jan 1st. When you query the API with action_report_time=conversion, you see a conversion on Jan 2nd.

breakdowns
list<enum{ad_format_asset, age, app_id, body_asset, breakdown_reporting_ad_id, call_to_action_asset, coarse_conversion_value, country, description_asset, fidelity_type, gender, hsid, image_asset, impression_device, is_conversion_id_modeled, is_rendered_as_delayed_skip_ad, landing_destination, link_url_asset, mdsa_landing_destination, media_asset_url, media_creator, media_destination_url, media_format, media_origin_url, media_text_content, media_type, postback_sequence_index, product_id, redownload, region, skan_campaign_id, skan_conversion_id, skan_version, sot_attribution_model_type, sot_attribution_window, sot_channel, sot_event_type, sot_source, title_asset, user_persona_id, user_persona_name, video_asset, dma, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, mmm, place_page_id, publisher_platform, platform_position, device_platform, standard_event_content_type, conversion_destination, signal_source_bucket, marketing_messages_btn_name}>

How to break down the result. For more than one breakdown, only certain combinations are available: See Combining Breakdowns and the Breakdowns page. The option impression_device cannot be used by itself.

date_preset
enum{today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year}
Giá trị mặc định: last_30d

Represents a relative time range. This field is ignored if time_range or time_ranges is specified.

default_summary
boolean
Giá trị mặc định: false

Determine whether to return a summary. If summary is set, this param is be ignored; otherwise, a summary section with the same fields as specified by fields will be included in the summary section.

export_columns
list<string>

Select fields on the exporting report file. It is an optional param. Exporting columns are equal to the param fields, if you leave this param blank

export_format
string

Set the format of exporting report file. If the export_format is set, Report file is asyncrhonizely generated. It expects ["xls", "csv"].

export_name
string

Set the file name of the exporting report.

fields
list<string>

Fields to be retrieved. Default behavior is to return impressions and spend.

filtering
list<Filter Object>
Giá trị mặc định: Vec

Filters on the report data. This parameter is an array of filter objects.

field
string

Bắt buộc
operator
enum {EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, STARTS_WITH, ENDS_WITH, ANY, ALL, AFTER, BEFORE, ON_OR_AFTER, ON_OR_BEFORE, NONE, TOP}

Bắt buộc
value
string

Bắt buộc
level
enum {ad, adset, campaign, account}

Represents the level of result.

product_id_limit
integer

Maximum number of product ids to be returned for each ad when breakdown by product_id.

sort
list<string>
Giá trị mặc định: Vec

Field to sort the result, and direction of sorting. You can specify sorting direction by appending "_ascending" or "_descending" to the sort field. For example, "reach_descending". For actions, you can sort by action type in form of "actions:<action_type>". For example, ["actions:link_click_ascending"]. This array supports no more than one element. By default, the sorting direction is ascending.

summary
list<string>

If this param is used, a summary section will be included, with the fields listed in this param.

summary_action_breakdowns
list<enum{action_device, conversion_destination, matched_persona_id, matched_persona_name, signal_source_bucket, standard_event_content_type, action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}>
Giá trị mặc định: Vec

Similar to action_breakdowns, but applies to summary. Default value is ["action_type"].

time_increment
enum{monthly, all_days} or integer
Giá trị mặc định: all_days

If it is an integer, it is the number of days from 1 to 90. After you pick a reporting period by using time_range or date_preset, you may choose to have the results for the whole period, or have results for smaller time slices. If "all_days" is used, it means one result set for the whole period. If "monthly" is used, you will get one result set for each calendar month in the given period. Or you can have one result set for each N-day period specified by this param. This param is ignored if time_ranges is specified.

time_range
{'since':YYYY-MM-DD,'until':YYYY-MM-DD}

A single time range object. UNIX timestamp not supported. This param is ignored if time_ranges is provided.

since
datetime

A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.

until
datetime

A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.

time_ranges
list<{'since':YYYY-MM-DD,'until':YYYY-MM-DD}>

Array of time range objects. Time ranges can overlap, for example to return cumulative insights. Each time range will have one result set. You cannot have more granular results with time_increment setting in this case.If time_ranges is specified, date_preset, time_range and time_increment are ignored.

since
datetime

A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.

until
datetime

A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.

use_account_attribution_setting
boolean
Giá trị mặc định: false

When this parameter is set to true, your ads results will be shown using the attribution settings defined for the ad account.

use_unified_attribution_setting
boolean

When this parameter is set to true, your ads results will be shown using unified attribution settings defined at ad set level and parameter use_account_attribution_setting will be ignored.

Trường

Đọc từ cạnh này sẽ trả về một kết quả JSON đã định dạng:

{
    "data": [],
    "paging": {},
    "summary": {}
}

data

Danh sách nút AdsInsights.

paging

Để biết thêm chi tiết về chia trang, hãy xem hướng dẫn về API Đồ thị.

summary

Thông tin tổng hợp về cạnh, chẳng hạn số lượng. Hãy chỉ định các trường để tìm nạp trong thông số tóm tắt (như summary=account_currency).

TrườngMô tả
account_currency
string

Currency that is used by your ad account.

account_id
numeric string

The ID number of your ad account, which groups your advertising activity. Your ad account includes your campaigns, ads and billing.

Mặc định
account_name
string

The name of your ad account, which groups your advertising activity. Your ad account includes your campaigns, ads and billing.

action_values
list<AdsActionStats>

The total value of all conversions attributed to your ads.

actions
list<AdsActionStats>

The total number of actions people took that are attributed to your ads. Actions may include engagement, clicks or conversions.

activity_recency
string

activity_recency

ad_click_actions
list<AdsActionStats>

ad_click_actions

ad_format_asset
string

ad_format_asset

ad_id
numeric string

The unique ID of the ad you're viewing in reporting.

Mặc định
ad_impression_actions
list<AdsActionStats>

ad_impression_actions

ad_name
string

The name of the ad you're viewing in reporting.

adset_id
numeric string

The unique ID of the ad set you're viewing in reporting. An ad set is a group of ads that share the same budget, schedule, delivery optimization and targeting.

Mặc định
adset_name
string

The name of the ad set you're viewing in reporting. An ad set is a group of ads that share the same budget, schedule, delivery optimization and targeting.

age_targeting
string

age_targeting

attribution_setting
string

The default attribution window to be used when attribution result is calculated. Each ad set has its own attribution setting value. The attribution setting for campaign or account is calculated based on existing ad sets.

auction_bid
numeric string

auction_bid

auction_competitiveness
numeric string

auction_competitiveness

auction_max_competitor_bid
numeric string

auction_max_competitor_bid

body_asset
AdAssetBody

body_asset

buying_type
string

The method by which you pay for and target ads in your campaigns: through dynamic auction bidding, fixed-price bidding, or reach and frequency buying. This field is currently only visible at the campaign level.

campaign_id
numeric string

The unique ID number of the ad campaign you're viewing in reporting. Your campaign contains ad sets and ads.

Mặc định
campaign_name
string

The name of the ad campaign you're viewing in reporting. Your campaign contains ad sets and ads.

canvas_avg_view_percent
numeric string

The average percentage of the Instant Experience that people saw. An Instant Experience is a screen that opens after someone interacts with your ad on a mobile device. It may include a series of interactive or multimedia components, including video, images product catalog and more.

canvas_avg_view_time
numeric string

The average total time, in seconds, that people spent viewing an Instant Experience. An Instant Experience is a screen that opens after someone interacts with your ad on a mobile device. It may include a series of interactive or multimedia components, including video, images product catalog and more.

catalog_segment_actions
list<AdsActionStats>

The number of actions performed attributed to your ads promoting your catalog segment, broken down by action type.

catalog_segment_value
list<AdsActionStats>

The total value of all conversions from your catalog segment attributed to your ads.

catalog_segment_value_mobile_purchase_roas
list<AdsActionStats>

The total return on ad spend (ROAS) from mobile app purchases for your catalog segment.

catalog_segment_value_omni_purchase_roas
list<AdsActionStats>

The total return on ad spend (ROAS) from all purchases for your catalog segment.

catalog_segment_value_website_purchase_roas
list<AdsActionStats>

The total return on ad spend (ROAS) from website purchases for your catalog segment.

clicks
numeric string

The number of clicks on your ads.

coarse_conversion_value
string

Allows advertisers and ad networks to receive directional post-install quality insights when the volume of campaign conversions isn't high enough to meet the privacy threshold needed to unlock the standard conversion value. Possible values of this breakdown are low, medium and high.
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

comparison_node
AdsInsightsComparison

Parent node that encapsulates fields to be compared (current time range Vs comparison time range)

conversion_values
list<AdsActionStats>

conversion_values

conversions
list<AdsActionStats>

conversions

converted_product_quantity
list<AdsActionStats>

The number of products purchased which are recorded by your merchant partner's pixel or app SDK for a given product ID and driven by your ads. Has to be used together with converted product ID breakdown.

converted_product_value
list<AdsActionStats>

The value of purchases recorded by your merchant partner's pixel or app SDK for a given product ID and driven by your ads. Has to be used together with converted product ID breakdown.

cost_per_15_sec_video_view
list<AdsActionStats>

cost_per_15_sec_video_view

cost_per_2_sec_continuous_video_view
list<AdsActionStats>

cost_per_2_sec_continuous_video_view

cost_per_action_type
list<AdsActionStats>

The average cost of a relevant action.

cost_per_ad_click
list<AdsActionStats>

cost_per_ad_click

cost_per_conversion
list<AdsActionStats>

cost_per_conversion

cost_per_dda_countby_convs
numeric string

cost_per_dda_countby_convs

cost_per_inline_link_click
numeric string

The average cost of each inline link click.

cost_per_inline_post_engagement
numeric string

The average cost of each inline post engagement.

cost_per_one_thousand_ad_impression
list<AdsActionStats>

cost_per_one_thousand_ad_impression

cost_per_outbound_click
list<AdsActionStats>

The average cost for each outbound click.

cost_per_thruplay
list<AdsActionStats>

The average cost for each ThruPlay. This metric is in development.

cost_per_unique_action_type
list<AdsActionStats>

The average cost of each unique action. This metric is estimated.

cost_per_unique_click
numeric string

The average cost for each unique click (all). This metric is estimated.

cost_per_unique_conversion
list<AdsActionStats>

cost_per_unique_conversion

cost_per_unique_inline_link_click
numeric string

The average cost of each unique inline link click. This metric is estimated.

cost_per_unique_outbound_click
list<AdsActionStats>

The average cost for each unique outbound click. This metric is estimated.

country
string

country

cpc
numeric string

The average cost for each click (all).

cpm
numeric string

The average cost for 1,000 impressions.

cpp
numeric string

The average cost to reach 1,000 people. This metric is estimated.

created_time
string

created_time

ctr
numeric string

The percentage of times people saw your ad and performed a click (all).

date_start
string

The start date for your data. This is controlled by the date range you've selected for your reporting view.

Mặc định
date_stop
string

The end date for your data. This is controlled by the date range you've selected for your reporting view.

Mặc định
dda_countby_convs
numeric string

dda_countby_convs

dda_results
list<AdsInsightsDdaResult>

dda_results

description_asset
AdAssetDescription

description_asset

device_platform
string

device_platform

dma
string

dma

estimated_ad_recall_rate_lower_bound
numeric string

estimated_ad_recall_rate_lower_bound

estimated_ad_recall_rate_upper_bound
numeric string

estimated_ad_recall_rate_upper_bound

estimated_ad_recallers_lower_bound
numeric string

estimated_ad_recallers_lower_bound

estimated_ad_recallers_upper_bound
numeric string

estimated_ad_recallers_upper_bound

fidelity_type
string

To differentiate StoreKit-rendered ads from view-through ads, SKAdNetwork defines a fidelity-type parameter, which you include in the ad signature and receive in the install-validation postback. Use a fidelity-type value of 1 for StoreKit-rendered ads and attributable web ads, and 0 for view-through ads.
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

frequency
numeric string

The average number of times each person saw your ad. This metric is estimated.

frequency_value
string

frequency_value

full_view_impressions
numeric string

The number of Full Views on your Page's posts as a result of your ad.

full_view_reach
numeric string

The number of people who performed a Full View on your Page's post as a result of your ad.

gender_targeting
string

gender_targeting

hourly_stats_aggregated_by_advertiser_time_zone
string

hourly_stats_aggregated_by_advertiser_time_zone

hourly_stats_aggregated_by_audience_time_zone
string

hourly_stats_aggregated_by_audience_time_zone

hsid
string

The hsid key is available for ad impressions that use SKAdNetwork 4 and later. This integer can have up to four digits. You can encode information about your advertisement in each set of digits; you may receive two, three, or all four digits of the sourceIdentifier in the first winning postback, depending on the ad impression's postback data tier.
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

image_asset
AdAssetImage

image_asset

impression_device
string

impression_device

impressions
numeric string

The number of times your ads were on screen.

Mặc định
inline_link_click_ctr
numeric string

The percentage of time people saw your ads and performed an inline link click.

inline_link_clicks
numeric string

The number of clicks on links to select destinations or experiences, on or off Facebook-owned properties. Inline link clicks use a fixed 1-day-click attribution window.

inline_post_engagement
numeric string

The total number of actions that people take involving your ads. Inline post engagements use a fixed 1-day-click attribution window.

instagram_upcoming_event_reminders_set
numeric string

instagram_upcoming_event_reminders_set

instant_experience_clicks_to_open
numeric string

instant_experience_clicks_to_open

instant_experience_clicks_to_start
numeric string

instant_experience_clicks_to_start

instant_experience_outbound_clicks
list<AdsActionStats>

instant_experience_outbound_clicks

interactive_component_tap
list<AdsActionStats>

interactive_component_tap

labels
string

labels

landing_destination
string

landing_destination

location
string

location

marketing_messages_delivery_rate
numeric string

The number of messages delivered divided by the number of messages sent. Some messages may not be delivered, such as when a customer's device is out of service. This metric doesn't include messages sent to Europe and Japan.

media_asset
AdAssetMedia

media_asset

mobile_app_purchase_roas
list<AdsActionStats>

The total return on ad spend (ROAS) from mobile app purchases. This is based on the value that you assigned when you set up the app event.

objective
string

The objective reflecting the goal you want to achieve with your advertising. It may be different from the selected objective of the campaign in some cases.

optimization_goal
string

The optimization goal you selected for your ad or ad set. Your optimization goal reflects what you want to optimize for the ads.

outbound_clicks
list<AdsActionStats>

The number of clicks on links that take people off Facebook-owned properties.

outbound_clicks_ctr
list<AdsActionStats>

The percentage of times people saw your ad and performed an outbound click.

platform_position
string

platform_position

postback_sequence_index
string

Sequence of postbacks received from SkAdNetwork API version 4.0. Possible values of this breakdown are 0 (first postback), 1 (second postback) and 2 (third postback).
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

product_id
string

product_id

publisher_platform
string

publisher_platform

purchase_roas
list<AdsActionStats>

The total return on ad spend (ROAS) from purchases. This is based on information received from one or more of your connected Facebook Business Tools and attributed to your ads.

qualifying_question_qualify_answer_rate
numeric string

qualifying_question_qualify_answer_rate

reach
numeric string

The number of people who saw your ads at least once. Reach is different from impressions, which may include multiple views of your ads by the same people. This metric is estimated.

redownload
string

Boolean flag that indicates the customer redownloaded and reinstalled the app when the value is true. A 1 indicates customer has reinstalled the app and 0 indicates that customer hasn’t reinstalled the app
Note: This breakdown is only supported by the total_postbacks_detailed_v4 field.

rule_asset
AdAssetRule

rule_asset

shops_assisted_purchases
string

shops_assisted_purchases

social_spend
numeric string

The total amount you've spent so far for your ads showed with social information. (ex: Jane Doe likes this).

spend
numeric string

The estimated total amount of money you've spent on your campaign, ad set or ad during its schedule. This metric is estimated.

Mặc định
title_asset
AdAssetTitle

title_asset

updated_time
string

updated_time

user_segment_key
string

user_segment_key

video_30_sec_watched_actions
list<AdsActionStats>

The number of times your video played for at least 30 seconds, or for nearly its total length if it's shorter than 30 seconds. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video.

video_asset
AdAssetVideo

video_asset

video_avg_time_watched_actions
list<AdsActionStats>

The average time a video was played, including any time spent replaying the video for a single impression.

video_continuous_2_sec_watched_actions
list<AdsActionStats>

video_continuous_2_sec_watched_actions

video_p100_watched_actions
list<AdsActionStats>

The number of times your video was played at 100% of its length, including plays that skipped to this point.

video_p25_watched_actions
list<AdsActionStats>

The number of times your video was played at 25% of its length, including plays that skipped to this point.

video_p50_watched_actions
list<AdsActionStats>

The number of times your video was played at 50% of its length, including plays that skipped to this point.

video_p75_watched_actions
list<AdsActionStats>

The number of times your video was played at 75% of its length, including plays that skipped to this point.

video_p95_watched_actions
list<AdsActionStats>

The number of times your video was played at 95% of its length, including plays that skipped to this point.

video_play_actions
list<AdsActionStats>

The number of times your video starts to play. This is counted for each impression of a video, and excludes replays. This metric is in development.

video_play_curve_actions
list<AdsHistogramStats>

A video-play based curve graph that illustrates the percentage of video plays that reached a given second. Entries 0 to 14 represent seconds 0 thru 14. Entries 15 to 17 represent second ranges [15 to 20), [20 to 25), and [25 to 30). Entries 18 to 20 represent second ranges [30 to 40), [40 to 50), and [50 to 60). Entry 21 represents plays over 60 seconds.

video_play_retention_0_to_15s_actions
list<AdsHistogramStats>

video_play_retention_0_to_15s_actions

video_play_retention_20_to_60s_actions
list<AdsHistogramStats>

video_play_retention_20_to_60s_actions

video_play_retention_graph_actions
list<AdsHistogramStats>

video_play_retention_graph_actions

video_time_watched_actions
list<AdsActionStats>

video_time_watched_actions

website_ctr
list<AdsActionStats>

The percentage of times people saw your ad and performed a link click.

website_purchase_roas
list<AdsActionStats>

The total return on ad spend (ROAS) from website purchases. This is based on the value of all conversions recorded by the Facebook pixel on your website and attributed to your ads.

wish_bid
numeric string

wish_bid

Mã lỗi

LỗiMô tả
100Invalid parameter
2635You are calling a deprecated version of the Ads API. Please update to the latest version.
80000There have been too many calls from this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-insights.
200Permissions error
2642Invalid cursors values
190Invalid OAuth 2.0 Access Token
3018The start date of the time range cannot be beyond 37 months from the current date
2500Error parsing graph query
3001Invalid query

Tạo

Bạn có thể tạo yêu cầu POST đến cạnh insights từ các đường dẫn sau:
Khi đăng lên cạnh này, hệ thống sẽ tạo an AdReportRun.

Thông số

Thông sốMô tả
action_attribution_windows
list<enum{1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, 1d_ev, dda, default, 7d_view_first_conversion, 28d_view_first_conversion, 7d_view_all_conversions, 28d_view_all_conversions, skan_view, skan_click}>
Giá trị mặc định: default

The attribution window for the actions. For example, 28d_click means the API returns all actions that happened 28 days after someone clicked on the ad. The default option means ["7d_view","1d_click"].

action_breakdowns
list<enum{action_device, conversion_destination, matched_persona_id, matched_persona_name, signal_source_bucket, standard_event_content_type, action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}>
Giá trị mặc định: Vec

How to break down action results. Supports more than one breakdowns. Default value is ["action_type"]

action_report_time
enum{impression, conversion, mixed}

Determines the report time of action stats. For example, if a person saw the ad on Jan 1st but converted on Jan 2nd, when you query the API with action_report_time=impression, you see a conversion on Jan 1st. When you query the API with action_report_time=conversion, you see a conversion on Jan 2nd

breakdowns
list<enum{ad_format_asset, age, app_id, body_asset, breakdown_reporting_ad_id, call_to_action_asset, coarse_conversion_value, country, description_asset, fidelity_type, gender, hsid, image_asset, impression_device, is_conversion_id_modeled, is_rendered_as_delayed_skip_ad, landing_destination, link_url_asset, mdsa_landing_destination, media_asset_url, media_creator, media_destination_url, media_format, media_origin_url, media_text_content, media_type, postback_sequence_index, product_id, redownload, region, skan_campaign_id, skan_conversion_id, skan_version, sot_attribution_model_type, sot_attribution_window, sot_channel, sot_event_type, sot_source, title_asset, user_persona_id, user_persona_name, video_asset, dma, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, mmm, place_page_id, publisher_platform, platform_position, device_platform, standard_event_content_type, conversion_destination, signal_source_bucket, marketing_messages_btn_name}>

How to break down the result. For more than one breakdown, only certain combinations are available: See "Combining Breakdowns" in the Breakdowns page. The option impression_device cannot be used by itself

date_preset
enum{today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year}
Giá trị mặc định: last_30d

Represents a relative time range. This field is ignored if time_range or time_ranges is specified

default_summary
boolean
Giá trị mặc định: false

Determine whether to return a summary. If summary is set, this param is ignored; otherwise, a summary section with the same fields as specified by fields is included in the summary section

export_columns
list<string>

Select fields on the exporting report file. It is an optional param. Exporting columns are equal to the param fields if you leave this param blank

export_format
string

Set the format of exporting report file. If the export_format is set, Report file is asyncrhonizely generated. It expects ["xls", "csv"].

export_name
string

Set the file name of the exporting report.

fields
list<string>

Fields to be retrieved. Default behavior is to return a list of most used fields

filtering
list<Filter Object>
Giá trị mặc định: Vec

Filters on the report data. This parameter is an array of filter objects

field
string

Bắt buộc
operator
enum {EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, STARTS_WITH, ENDS_WITH, ANY, ALL, AFTER, BEFORE, ON_OR_AFTER, ON_OR_BEFORE, NONE, TOP}

Bắt buộc
value
string

Bắt buộc
level
enum {ad, adset, campaign, account}

Represents the level of result

product_id_limit
integer

Maximum number of product ids to be returned for each ad when breakdown by product_id.

sort
list<string>
Giá trị mặc định: Vec

Field to sort the result, and direction of sorting. You can specify sorting direction by appending "_ascending" or "_descending" to the sort field. For example, "reach_descending". For actions, you can sort by action type in form of "actions:<action_type>". For example, ["actions:link_click_ascending"]. This array supports no more than one element. By default, the sorting direction is ascending

summary
list<string>

If this param is used, a summary section is included, with the fields listed in this param

summary_action_breakdowns
list<enum{action_device, conversion_destination, matched_persona_id, matched_persona_name, signal_source_bucket, standard_event_content_type, action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}>
Giá trị mặc định: Vec

Similar to action_breakdowns, but applies to summary. Default value is ["action_type"]

time_increment
enum{monthly, all_days} or integer
Giá trị mặc định: all_days

If it is an integer, it is the number of days from 1 to 90. After you pick a reporting period by using time_range or date_preset, you may choose to have the results for the whole period, or have results for smaller time slices. If "all_days" is used, it means one result set for the whole period. If "monthly" is used, you get one result set for each calendar month in the given period. Or you can have one result set for each N-day period specified by this param. This param is ignored if time_ranges is specified

time_range
{'since':YYYY-MM-DD,'until':YYYY-MM-DD}

A single time range object. UNIX timestamp not supported. This param is ignored if time_ranges is provided

since
datetime

A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.

until
datetime

A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.

time_ranges
list<{'since':YYYY-MM-DD,'until':YYYY-MM-DD}>

Array of time range objects. Time ranges can overlap, for example to return cumulative insights. Each time range has one result set. You cannot have more granular results with time_increment setting in this case.If time_ranges is specified, date_preset, time_range and time_increment are ignored

since
datetime

A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.

until
datetime

A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.

use_account_attribution_setting
boolean
Giá trị mặc định: false

When this parameter is set to true, your ads results are shown using the attribution settings defined for the ad account

use_unified_attribution_setting
boolean

When this parameter is set to true, your ads results will be shown using unified attribution settings defined at ad set level and parameter use_account_attribution_setting will be ignored.
Note: Please set this to true to get the same behavior as in the Ads Manager.

Kiểu trả về

Struct {
report_run_id: numeric string,
}

Mã lỗi

LỗiMô tả
100Invalid parameter
80000There have been too many calls from this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-insights.
2635You are calling a deprecated version of the Ads API. Please update to the latest version.
3018The start date of the time range cannot be beyond 37 months from the current date
190Invalid OAuth 2.0 Access Token
200Permissions error
2500Error parsing graph query

Cập nhật

Bạn không thể thực hiện thao tác này trên điểm cuối này.

Xóa

Bạn không thể thực hiện thao tác này trên điểm cuối này.