图谱 API
图谱 API 版
返回中文(简体)
文档已更新。
中文(简体) 译文尚未完成。
英语更新时间：9月11日
中文(简体) 更新时间：2018年10月26日

Page Insights

Represents insights for Facebook Pages and Page posts. Refer to our Pages API documentation.

On March 14, 2024, a number of the Page Insights metrics were deprecated for all API versions. The API returns an invalid metric error when calling any of these metrics. Read our blog to learn more.

读取

Get metrics for Pages or Page posts.

New Page Experience

This endpoint is supported for New Page Experience.

Limitations

  • Page Insights data is only available on Pages with 100 or more likes.
  • Most metrics will update once every 24 hours.
  • Only the last two years of insights data is available.
  • The values for period are calculated from the initial collection of the data point.
  • "Period" in the tables below only refers to the time frame for which the metric can be accessed in an aggregated form.
  • The value "lifetime" means the time period for which the insights data is available. By default, this time period is 2 years or shorter.
  • Only 90 days of insights can be viewed at one time when using the since and until parameters.
  • When using since and until, the since date data will be included in the first value returned.
  • Unique impression insights values are calculated independently.
    • Total page reach may not always be exactly equal to the sum of paid and non-paid unique values.
    • Total page reach may not always be exactly equal to the sum of viral_unique and organic_unique.
  • When an organic post is boosted, metrics for paid post impressions will include both organic and paid reach.
  • Demographic metrics, such as age, gender, and location, are only returned if there is data for 100 or more people.
  • Breakdown metrics for Page post and Page view insights will only return non-zero values.
  • Several video related metrics only return accurate values if the person requesting the metric is the Page video post creator.
  • If you reshare a video post of another Page and retrieve its insights, the metrics return a value of 0. Metrics that return 0 for resharers are denoted with "Returns 0 for reshared videos" in their description.
  • If you neglect to indicate a specific metric or metrics for the endpoint, you will receive an error response with code 3001, with subcode 1504028 and an error message that states: "No metric was specified to be fetched. Please specify one or more metrics to be fetched and try again."
  • Interactions on Reels are not included.

Requirements

TypeDescription

Access Tokens

A Page access token requested by a person who can perform the ANALYZE task on the Page.

Features

Not applicable.

Permissions

read_insights, pages_read_engagement

Page Tasks

ANALYZE

Example

Single Metric Sample Request

Graph API Explorer
GET v21.0/{object-id}/insights/{metric} 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(
    '{object-id}/insights/{metric}',
    '{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(
    "{object-id}/insights/{metric}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "{object-id}/insights/{metric}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"{object-id}/insights/{metric}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
如果你希望详细了解如何使用图谱 API，请阅读我们的图谱 API 指南。

Multiple Metric Sample Request

NOTE: If your request times out or some metrics are not returned, try reducing the number of metrics in your API request.

Graph API Explorer
GET v21.0/{object-id}/insights?metric={metric-1},{metric-2},{metric-3},... 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(
    '{object-id}/insights?metric={metric-1},{metric-2},{metric-3},...',
    '{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(
    "{object-id}/insights?metric={metric-1},{metric-2},{metric-3},...",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "{object-id}/insights?metric={metric-1},{metric-2},{metric-3},...",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"{object-id}/insights?metric={metric-1},{metric-2},{metric-3},..."
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
如果你希望详细了解如何使用图谱 API，请阅读我们的图谱 API 指南。

Metrics

Metric names indicate whether a metric is for a Page or a Page post.

SuffixDescription

_unique

Indicates that the metric shows the number of unique users who performed a specific action, for example page_impressions_unique. Metrics generated with the _unique suffix are approximate and may not be 100% accurate.

_login

Indicates whether a person was logged into Facebook, for example, page_tab_views_login_top.

_logout

Indicates whether a person is logged out of Facebook, for example page_views_logout.

_source

Indicates that the metric will be broken down into a list of referral sources, for example page_fans_by_like_source. External referrals are broken down by domain. Internal referrals are broken down by Facebook-specific features such as Profile, Search, Requests, Suggestions, Stream, etc. In these cases the value returned will be an object containing a series of key-value pairs where the key is the source name and the value is the metric for that source.

*

Indicates that a metric is refreshed several times during the day, for example page_impressions_unique*.

Page Content

Most of the metrics below can be retrieved using post_activity_by_action_type, post_clicks_by_type, and page_consumptions_by_consumption_type.

Metric Name Description Values for `period`
page_tab_views_login_top_unique

查看公共主页选项卡的 Facebook 登录用户人数。 (See possible types)

day, week

page_tab_views_login_top

Facebook 登录用户查看公共主页选项卡的次数。 (See possible types)

day, week

page_tab_views_logout_top

未登录 Facebook 的用户查看公共主页选项卡的次数。 (See possible types)

day

Tab Types

Tab types for Page content metrics.

Name Description
allactivity

Administrative tab

app

Custom created tab

info

About tab view

insights

Insights tab

likes

Likes tab

locations

Map tab

photos

Photos tab

photos_albums

Photos tab

photos_stream

Photos tab

profile

Pages timeline

profile_info

Info tab

profile_likes

Likes tab

profile_photos

Photos tab

timeline

Pages timeline

events

Events tab

videos

Videos tab

wall

Timeline

Page CTA Clicks

Metric Name Description Values for `period`
page_total_actions

主页联系方式和行动号召按钮的点击量。

day, week, days_28

Page Engagement

The "like" reaction counts include both "like" and "care" reactions.

Metric Name Description Values for `period`
page_post_engagements*

用户通过点赞、评论和分享等方式与帖子互动的次数。

day, week, days_28

page_fan_adds_by_paid_non_paid_unique

第一次为你的公共主页点赞的账户中心账户数量，细分依据是公共主页获赞归因于付费内容还是自然内容。这一指标是估计值。

day

page_lifetime_engaged_followers_unique*

关注你的主页并在过去 14 天采取过下列操作的用户：观看你主页中至少一个直播视频或录好的视频，且观看时长至少为 1 分钟，或者通过评论、分享、留下心情或点赞等方式与视频互动至少一次。

page_daily_follows*

在选定时间范围内，你的公共主页或个人主页获得的关注次数。

day

page_daily_follows_unique*

在选定时间范围内，关注你公共主页的账户中心账户数量。这一指标是估计值。

day, week, days_28

page_daily_unfollows_unique*

在所选时段内取关你公共主页的账户中心账户数量。这一指标是估计值。

day, week, days_28

page_follows*

你的 Facebook 公共主页或个人主页获得的粉丝人数。计算方式：Facebook 公共主页或个人主页史上关注次数减去取关次数。

day

Page Impressions

Metric Name Description Values for `period`
page_impressions*

你的任何公共主页内容或公共主页相关内容出现在用户设备屏幕中的次数。这包括公共主页上的帖子、快拍、广告，以及其他内容或信息。

day, week, days_28

page_impressions_unique*

设备屏幕中出现过你的任意主页内容或主页相关内容的用户人数。这包括帖子、签到、广告、与你主页互动的用户的社交信息等内容。这一指标是估计值。

day, week, days_28

page_impressions_paid*

通过付费展示（例如广告），你的任何公共主页帖子或快拍、或公共主页相关内容出现在用户设备屏幕中的次数。

day, week, days_28

page_impressions_paid_unique*

看到你的广告至少一次的账户中心账户数量。覆盖账户数量与展示次数不同，后者可能存在相同账户中心账户多次浏览广告的情况。这一指标是估计值。

day, week, days_28

page_impressions_viral*

你的任何公共主页内容或公共主页相关内容（包含社交信息）出现在用户设备屏幕中的次数。社交信息会在用户的好友与你的公共主页、帖子或快拍互动时显示，包括用户的好友赞或关注你的公共主页、与帖子互动、分享你的公共主页照片，以及在你的公共主页签到。这一指标仍在开发中。

day, week, days_28

page_impressions_viral_unique*

这一指标计算你的 Facebook 公共主页和公共主页内容与社交信息一起显示时，通过自然方式或付费传播获得的覆盖人数。社交信息会在用户与你的公共主页、帖子或快拍互动后，在动态中显示。如果通过自然方式和付费传播共同促成了一次覆盖，那么这仅算作一次覆盖。这一指标是估计值和仍在开发中。

day, week, days_28

page_impressions_nonviral*

你的 Facebook 公共主页和公共主页内容在屏幕上展示的次数，不包括与社交信息一起展示的情况。社交信息会在用户与你的公共主页、帖子或快拍互动后，在动态中显示。这一指标仍在开发中。

day, week, days_28

page_impressions_nonviral_unique*

这一指标计算你的 Facebook 公共主页和公共主页内容通过自然方式或付费传播获得的覆盖人数，不包括与社交信息一起展示的情况。社交信息会在用户与你的公共主页、帖子或快拍互动后，在动态中显示。如果通过自然方式和付费传播共同促成了一次覆盖，那么这仅算作一次覆盖。这一指标是估计值和仍在开发中。

day, week, days_28

Page Posts

Metric Name Description Values for `period`
page_posts_impressions*

你的主页帖出现在用户设备屏幕中的次数。包括状态、照片、链接、视频等类型的帖子。

day, week, days_28

page_posts_impressions_unique*

设备屏幕中出现过你的任意主页帖的用户人数。包括状态、照片、链接、视频等类型的帖子。

day, week, days_28

page_posts_impressions_paid*

广告带来的，你的 Facebook 公共主页和公共主页内容在屏幕上展示的次数。

day, week, days_28

page_posts_impressions_paid_unique*

由于你的广告而看过来自你公共主页任何帖子至少一次的账户中心账户数量。

day, week, days_28

page_posts_impressions_organic_unique*

通过非付费展示，设备屏幕中出现过你的任意主页帖的用户人数。

day, week, days_28

page_posts_served_impressions_organic_unique

在动态中看到你的公共主页帖的用户人数，不论帖子是否在用户设备屏幕上展示。包括状态、照片、链接、视频等类型的帖子。

day, week, days_28

page_posts_impressions_viral*

你的公共主页帖子（包含社交信息）出现在用户设备屏幕中的次数。社交信息会在用户的好友与你的公共主页或帖子互动时显示，包括用户的好友点赞或关注你的公共主页、与帖子互动、分享你的公共主页照片和在你的公共主页签到。

day, week, days_28

page_posts_impressions_viral_unique*

设备屏幕中出现过你的任意公共主页帖（包含社交信息）的用户人数。社交信息会在用户的好友与你的公共主页或帖子互动时自然展示，包括用户的好友点赞或关注你的公共主页、与帖子互动、分享你的公共主页照片和在你的公共主页签到。

day, week, days_28

page_posts_impressions_nonviral*

你的公共主页帖（不包括围绕你公共主页生成的带有社交信息的内容）出现在用户设备屏幕中的次数。社交信息会在用户的好友与你的公共主页或帖子互动时显示，包括用户的好友点赞或关注你的公共主页、与帖子互动、分享你的公共主页照片和在你的主页签到。

day, week, days_28

page_posts_impressions_nonviral_unique*

设备屏幕中出现过你的任意公共主页帖（不包括围绕你公共主页生成的带有社交信息的内容）的用户人数。社交信息会在用户的好友与你的公共主页或帖子互动时自然展示，包括用户的好友点赞或关注你的公共主页、与帖子互动、分享你的公共主页照片和在你的公共主页签到。

day, week, days_28

Page Post Engagement

Metric Name Description Values for `period`
post_clicks*

用户点击帖子任意位置，但未生成动态的次数。

lifetime

post_clicks_by_type*

用户点击帖子任意位置，但未生成动态的次数，按内容使用类型细分。

lifetime

Negative Feedback Types

Negative feedback types for page_negative_feedback_by_type metrics.

Name Description
hide_clicks

Hide this story

hide_all_clicks

Hide all posts from this page

report_spam_clicks

Report an object as a spam

unlike_page_clicks

Unlike a page

Page Post Impressions

Metric Name Description Values for `period`
post_impressions*

你的主页帖出现在用户设备屏幕中的次数。包括状态、照片、链接、视频等类型的帖子。

lifetime

post_impressions_unique*

设备屏幕中出现过你主页帖的用户人数。包括状态、照片、链接、视频等类型的帖子。这一指标是估计值。

lifetime

post_impressions_paid*

广告带来的，你的公共主页内容在屏幕上展示的次数。

lifetime

post_impressions_paid_unique*

由于你的广告而看过你帖子至少一次的账户中心账户数量。这一指标是估计值。

lifetime

post_impressions_fan*

你的公共主页内容在屏幕上对已关注或赞你公共主页的帐户展示的次数。

lifetime

post_impressions_fan_unique*

关注或赞你的公共主页的账户中心账户数量。这一指标是估计值。

lifetime

post_impressions_organic*

通过自然传播方式，你的帖子在屏幕上展示的次数。

lifetime

post_impressions_organic_unique*

这一指标计算你的 Facebook 公共主页内容通过自然传播获得的覆盖人数。公共主页内容包括帖子、快拍和广告。通过分享获得的覆盖人数仅计入自然内容。这包括你的内容以快拍或转发形式分享的情况。这一指标是估计值。

lifetime

post_impressions_viral*

你的公共主页内容在屏幕上与社交信息一起展示的次数。社交信息会在用户与你的公共主页、帖子或快拍互动后，在动态中显示。这一指标仍在开发中。

lifetime

post_impressions_viral_unique*

这项指标计算你的 Facebook 内容作为转发帖或快拍分享时获得的覆盖人数。通过分享获得的覆盖人数仅计入自然传播。这一指标是估计值和仍在开发中。

lifetime

post_impressions_nonviral*

你的公共主页内容在屏幕上展示的次数，不包括内容与社交信息一起展示的情况。社交信息会在用户与你的公共主页、帖子或快拍互动后，在动态中显示。这一指标仍在开发中。

lifetime

post_impressions_nonviral_unique*

这一指标计算你的公共主页内容通过自然方式或付费传播获得的覆盖人数，不包括内容与社交信息一起展示的情况。社交信息会在用户与你的公共主页、帖子或快拍互动后，在动态中显示。如果通过自然方式和付费传播共同促成了一次覆盖，那么这仅算作一次覆盖。这一指标是估计值和仍在开发中。

lifetime

Page Post Reactions

The "like" reaction counts include both "like" and "care" reactions.

Metric Name Description Values for `period`
post_reactions_like_total

帖子收到心情“赞”的总数。

lifetime

post_reactions_love_total

帖子收到心情“大爱”的总数。

lifetime

post_reactions_wow_total

帖子收到心情“哇”的总数。

lifetime

post_reactions_haha_total

帖子收到心情“笑趴”的总数。

lifetime

post_reactions_sorry_total

帖子收到心情“心碎”的总数。

lifetime

post_reactions_anger_total

帖子收到心情“怒”的总数。

lifetime

post_reactions_by_type_total

按类型显示帖子获得的心情总数。

lifetime

Page Reactions

The "like" reaction counts include both "like" and "care" reactions.

Metric Name Description Values for `period`
page_actions_post_reactions_like_total*

公共主页帖子每天获得“赞”的总次数。

day, week, days_28

page_actions_post_reactions_love_total*

公共主页帖每天获得“大爱”的总次数。

day, week, days_28

page_actions_post_reactions_wow_total*

公共主页帖子每天获得“哇”的总次数。

day, week, days_28

page_actions_post_reactions_haha_total*

公共主页帖每天获得“笑趴”的总次数。

day, week, days_28

page_actions_post_reactions_sorry_total*

公共主页帖子每天获得“心碎”的总次数。

day, week, days_28

page_actions_post_reactions_anger_total*

公共主页帖子每天获得“怒”的总次数。

day, week, days_28

page_actions_post_reactions_total

公共主页帖每天获得的心情总数，按类型细分。

day

Page User Demographics

Metric Name Description Values for `period`
page_fans

赞过你公共主页的总人数。

day

page_fans_locale

你的主页点赞用户语言数据汇总，根据访问 Facebook 时选择的默认语言设置统计。

day

page_fans_city

对公共主页点赞的 Facebook 用户地区数据汇总，按城市细分。

day

page_fans_country

公共主页点赞用户人数，按国家/地区统计。系统只显示公共主页点赞人数最多的 45 个国家/地区。

day

page_fan_adds

公共主页的新增点赞人数。

day

page_fan_adds_unique

首次给你的公共主页点赞的账户中心账户数量。这一指标是估计值。

day, week, days_28

page_fan_removes

用户取消公共主页赞的次数。

day

page_fan_removes_unique*

用户取消公共主页赞的次数。

day, week, days_28

Page Like Sources

Source types for page_fans_by_like_source and page_fans_by_like_source_unique metrics.

Name Description
Ads

Page likes that came from people who saw your Page or post in an ad.

News Feed

Page likes that came from people who saw content posted by your Page or about your Page in News Feed.

Page Suggestions

Page likes that came from people saw your Page in a list of suggested Pages.

Restored Likes from Reactivated Accounts

Page likes that came from people who reactivated their Facebook profile.

Search

Page likes that came from people who saw you Page or post in search.

Your Page

Page likes that came from people who visited your Page.

Page Video Views

Metric Name Description Values for `period`
page_video_views

播放主页视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_by_uploaded_hosted*

公共主页层级的每日视频观看量，按公共主页上传的所有版本和公共主页托管的所有版本细分。

day, week, days_28

page_video_views_paid

播放主页推广视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。

day, week, days_28

page_video_views_organic

播放主页视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数，按自然覆盖人数细分。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_by_paid_non_paid*

播放主页视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数，按总数、付费和自然细分。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_autoplayed

自动播放主页视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_click_to_play

用户点击播放后，播放主页视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_unique

观看主页视频至少满 3 秒或几乎完整观看（如果视频总时长不足 3 秒）的用户人数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_repeat_views

重播主页视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。

day, week, days_28

page_video_complete_views_30s

播放主页视频至少满 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_complete_views_30s_paid

播放主页推广视频至少满 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。

day, week, days_28

page_video_complete_views_30s_organic

播放主页视频至少满 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数，按自然覆盖人数细分。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_complete_views_30s_autoplayed

播放主页自动播放视频至少满 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_complete_views_30s_click_to_play

用户点击播放后，播放主页视频至少满 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_complete_views_30s_unique

观看主页视频至少满 30 秒或几乎完整观看（如果视频总时长不足 30 秒）的用户人数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_complete_views_30s_repeat_views

主页视频的重播时间至少达到 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数。

day, week, days_28

post_video_complete_views_30s_autoplayed

自动播放视频至少满 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。重复分享的视频记为 0。

lifetime

post_video_complete_views_30s_clicked_to_play

用户点击播放后，播放视频至少满 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。重复分享的视频记为 0。

lifetime

post_video_complete_views_30s_organic

播放视频至少满 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数，按自然覆盖人数细分。对于每次视频播放，我们不会计算任何视频重播时间。重复分享的视频记为 0。

lifetime

post_video_complete_views_30s_paid

播放推广视频至少满 30 秒或几乎完整播放（如果视频总时长不足 30 秒）的次数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。重复分享的视频记为 0。

lifetime

post_video_complete_views_30s_unique

观看视频至少满 30 秒或几乎完整观看（如果视频总时长不足 30 秒）的用户人数。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

page_video_views_10s

已弃用图谱 API 18 以上版本：播放公共主页视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_10s_paid

已弃用图谱 API 18 以上版本：播放公共主页推广视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。

day, week, days_28

page_video_views_10s_organic

已弃用图谱 API 18 以上版本：播放公共主页视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数，按自然覆盖人数细分。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_10s_autoplayed

已弃用图谱 API 18 以上版本：自动播放公共主页视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_10s_click_to_play

已弃用图谱 API 18 以上版本：用户点击播放后，播放公共主页视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_10s_unique

已弃用图谱 API 18 以上版本：观看公共主页视频至少满 10 秒或几乎完整观看（如果视频总时长不足 10 秒）的用户人数。对于每次视频播放，我们不会计算任何视频重播时间。

day, week, days_28

page_video_views_10s_repeat

已弃用图谱 API 18 以上版本：重播公共主页视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。

day, week, days_28

page_video_view_time

用户观看主页视频的总时长（毫秒）。

day

page_uploaded_3s_to_15s_views_rate*

观看率（3 秒至 15 秒）。衡量所有上传的视频素材，包括主页帖/交叉发布帖或其分享帖的动态。

page_uploaded_views_15s_count*

用户观看主页视频至少 15 秒的总次数。

page_uploaded_views_60s_excludes_shorter_unique_count_by_is_60s_returning_viewer*

Daily video 60-second unique views on a page for uploaded videos by 60-second returning viewers. This metric counts only for videos that are 60 seconds or longer. 60-second returning viewers are the users who had 60-second view last week and a 60-second view this week.

Page Views

Metric Name Description Values for `period`
page_views_total*

登录和未登录用户查看主页的次数。

day, week, days_28

Page Video Posts

Metric Name Description Values for `period`
post_video_avg_time_watched

用户观看视频的平均时长（毫秒）。只适用于 2016 年 8 月 25 日以后创建的视频。重复分享的视频记为 0。

lifetime

post_video_complete_views_organic

从视频开头播放到至少 97% 进度的次数，按自然覆盖人数细分。对于每次视频播放，我们不会计算任何视频重播时间。重复分享的视频记为 0。

lifetime

post_video_complete_views_organic_unique

从视频开头观看到至少 97% 进度的用户人数，按自然覆盖人数细分。对于每次视频播放，我们不会计算任何视频重播时间。重复分享的视频记为 0。

lifetime

post_video_complete_views_paid

从推广视频开头播放到至少 97% 进度的次数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。重复分享的视频记为 0。

lifetime

post_video_complete_views_paid_unique

从推广视频开头观看到至少 97% 进度的用户人数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。

lifetime

post_video_retention_graph*

视频在各时段的播放量占总观看量的百分比。视频被均分为 40 个时段。这项指标不计算视频直播时的展示次数。留存率图表可能会显示视频后段的展示次数多于开头的展示次数。可能的原因如下：1. 用户从视频中间开始播放；2. 快进；3. 保存进度，然后从该时间点重新观看；4. 其他类似行为。

lifetime

post_video_retention_graph_clicked_to_play

用户点击播放后，各时段的视频播放量占总观看量的百分比。视频被均分为 40 个时段。这项指标不计算视频直播时的展示次数。留存率图表可能会显示视频后段的展示次数多于开头的展示次数。可能的原因如下：1. 用户从视频中间开始播放；2. 快进；3. 保存进度，然后从该时间点重新观看；4. 其他类似行为。

lifetime

post_video_retention_graph_autoplayed

视频在各时段的自动播放量占总自动观看量的百分比。视频被均分为 40 个时段。这项指标不计算视频直播时的展示次数。留存率图表可能会显示视频后段的展示次数多于开头的展示次数。可能的原因如下：1. 用户从视频中间开始播放；2. 快进；3. 保存进度，然后从该时间点重新观看；4. 其他类似行为。

lifetime

post_video_views_organic

播放视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数，按自然覆盖人数细分。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime, day

post_video_views_organic_unique

观看视频至少满 3 秒或几乎完整观看（如果视频总时长不足 3 秒）的用户人数，按自然覆盖人数细分。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

post_video_views_paid

播放推广视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。

lifetime, day

post_video_views_paid_unique

观看推广视频至少满 3 秒或几乎完整观看（如果视频总时长不足 3 秒）的用户人数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。

lifetime

post_video_length

视频帖的时长（毫秒）。

lifetime

post_video_views

视频播放满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。这包括直播视频。

lifetime, day

post_video_views_unique

观看视频至少满 3 秒或几乎完整观看（如果视频总时长不足 3 秒）的用户人数。对于每次视频播放，我们不会计算任何视频重播时间。

day, lifetime

post_video_views_autoplayed

自动播放视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

post_video_views_clicked_to_play

用户点击播放后，播放视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

post_video_views_15s*

播放视频达 15 秒或几乎完整播放（如果视频总时长不足 15 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

post_video_views_60s_excludes_shorter*

观看视频达 60 秒的用户人数。这项指标的计算只适用于时长至少为 60 秒的视频。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime, day

post_video_views_10s

已弃用图谱 API 18 以上版本：播放视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime, day

post_video_views_10s_unique

已弃用图谱 API 18 以上版本：观看视频至少满 10 秒或几乎完整观看（如果视频总时长不足 10 秒）的用户人数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。

lifetime

post_video_views_10s_autoplayed

已弃用图谱 API 18 以上版本：自动播放视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

post_video_views_10s_clicked_to_play

已弃用图谱 API 18 以上版本：用户点击播放后，播放视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

post_video_views_10s_organic

已弃用图谱 API 18 以上版本：播放视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数，按自然覆盖人数细分。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

post_video_views_10s_paid

已弃用图谱 API 18 以上版本：播放推广视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。每一次视频展示均单独统计时长达标的观看量，且不计算任何视频重播时间。

lifetime, day

post_video_views_10s_sound_on

已弃用图谱 API 18 以上版本：有声播放视频至少满 10 秒或几乎完整播放（如果视频总时长不足 10 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

post_video_views_sound_on

有声播放视频至少满 3 秒或几乎完整播放（如果视频总时长不足 3 秒）的次数。对于每次视频播放，我们不会计算任何视频重播时间。

lifetime

post_video_view_time

视频播放的总时长（毫秒），包括重播和播放时长不足 3 秒的情况。重复分享的视频记为 0。

lifetime, day

post_video_view_time_organic

自然覆盖的用户播放视频的总时长（毫秒）。重复分享的视频记为 0。

lifetime, day

post_video_view_time_by_age_bucket_and_gender

最优质受众播放视频的总时长（毫秒），按年龄和性别细分。

lifetime

post_video_view_time_by_region_id

视频在最热门的 45 个地区（地区 - 国家）的总播放时长（毫秒）。

lifetime, day

post_video_views_by_distribution_type

视频播放次数，按传播渠道类型（主页所有/共享）细分。

lifetime

post_video_view_time_by_distribution_type

视频播放总时长（毫秒），按传播渠道类型（主页所有/共享）细分。

lifetime

post_video_view_time_by_country_id

视频在最热门的 45 个地区（国家）的总播放时间（单位：分钟）。

lifetime

post_video_views_live*

广告发布期间，直播时观看你的视频超过 3 秒的用户人数。

lifetime

post_video_social_actions_count_unique*

独立用户在视频帖上的社交操作（留下心情、评论、分享）次数。

lifetime, day

post_video_live_current_viewers*

正在观看直播视频的观众人数。这项指标仅传回直播帖的数据。对于已结束直播的直播帖，显示 0。

post_video_15s_to_60s_excludes_shorter_views_rate*

视频观看时长在 15 秒到 60 秒的比率。这项指标只适用于不短于 60 秒的视频。

post_video_views_by_live_status*

Lifetime 3S Video Views broken down by live status: live or VOD

Stories

Page and Post Stories and "People talking about this".

Metric Name Description Values for `period`
post_activity_by_action_type*

围绕公共主页帖子而创建的动态数量，按操作类型细分。

lifetime

post_activity_by_action_type_unique*

为公共主页帖创建动态的用户人数，按操作类型细分。

lifetime

Page Story Types

Name Description
checkin

Page checkins

coupon

Offer claims

event

RSVPing to event

fan

Page likes

mention

Page mentions

page post

Posts by a Page

question

Question answers

user post

Posts by people on a Page

other

Other types

Video Ad Breaks

Metric Name Description Values for period

page_daily_video_ad_break_ad_impressions_by_crosspost_status

The total number of times an ad was shown during ad breaks in crossposted videos.

day

page_daily_video_ad_break_cpm_by_crosspost_status

The average amount paid by advertisers for 1,000 of impressions of their ads in a crossposted videos. This is a gross number and includes the amount paid to Facebook.

day

page_daily_video_ad_break_earnings_by_crosspost_status

An estimate of the amount you earned from ad breaks in a crossposted videos, based on the number of impressions and CPM of ads shown. Actual payments may differ if there are content ownership claims or other adjustments.

day

post_video_ad_break_ad_impressions

The total number of times an ad was shown during ad breaks in your videos.

day, lifetime

post_video_ad_break_earnings

An estimate of the amount you earned from ad breaks in your videos, based on the number of impressions and CPM of ads shown. Actual payments may differ if there are content ownership claims or other adjustments.

day, lifetime

post_video_ad_break_ad_cpm

The average amount paid by advertisers for 1,000 impressions of their ads in your videos. This number also includes the amount paid to Facebook.

day, lifetime

creator_monetization_qualified_views

The number of views of your videos that will receive a payout. To qualify for payout, your Page or profile must generate ad revenue in the current earning period. You must also be following the Partner Monetization Policies and Content Monetization Policies. There are additional factors which may disqualify a view for payout.

day,lifetime

参数

参数描述
breakdown
list<A valid breakdown for an insights endpoint>

breakdown for marketing messages metrics. This is currently in development.

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}

Preset a date range, like lastweek, yesterday. If since or until presents, it does not work.

metric
list<A valid metric for an insights endpoint>

The list of metrics that needs to be fetched

period
enum {day, week, days_28, month, lifetime, total_over_range}

The aggregation period

show_description_from_api_doc
boolean
默认值：false

If set to true, then an additional description of the metric, retrieved from the API doc(https://developers.facebook.com/docs/graph-api/reference/insights) will be included in the returned data

since
datetime

Lower bound of the time range to consider

until
datetime

Upper bound of the time range to consider

字段

从这条连线读取将返回一个 JSON 格式的结果：

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

data

InsightsResult 节点列表。

paging

详细了解分页功能，请见图谱 API 指南。

错误代码

错误描述
100Invalid parameter
190Invalid OAuth 2.0 Access Token
200Permissions error
80001There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
3001Invalid query
104Incorrect signature
368The action attempted has been deemed abusive or is otherwise disallowed

创建

你无法在此端点执行该操作。

更新

你无法在此端点执行该操作。

删除

你无法在此端点执行该操作。

See Also