Graph API Version

App Insights

This edge represents a single Facebook Insights metric for a particular app. Each app has multiple available metrics to query, which are listed below in this doc.

Reading

Insights for this app

The endpoint used is determined by the metric that is being looked up. All available metrics are listed below.

Permissions

  • Any valid access token can be used for publicly available metrics.
  • An app access token can retrieve all metrics for that app.
  • A user access token with read_insights permission can retrieve metrics for all apps owned by this user.

Metric Name

You must pass the name of a metric you're interested in via the last part of the path after app_insights. Please see the full list of metrics below for what you can query.

For example:

/* make the API call */
FB.api(
    "/{app-id}/app_insights/{metric-name}",
    {
        "period": "monthly",
        "breakdowns[0]": "client"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
GET /v2.8/{app-id}/app_insights/{metric-name}?period=monthly&breakdowns%5B0%5D=client HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{app-id}/app_insights/{metric-name}',
  array (
    'period' => 'monthly',
    'breakdowns[0]' => 'client',
  )
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
Bundle params = new Bundle();
params.putString("period", "monthly");
params.putString("breakdowns[0]", "client");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{app-id}/app_insights/{metric-name}",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"period": @"monthly",
  @"breakdowns[0]": @"client",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{app-id}/app_insights/{metric-name}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Parameters

This edge can also take additional parameters to control what kinds of metrics you're interested in.

NameDescriptionType

aggregateBy

How to aggregate the data, values include:

  • COUNT - count of events
  • USERS - unique users (only available for some metrics)
  • TOPK - highest count combinations of breakdowns

These values are unique to app events:

  • SUM - sum of a metric with a value, such as payments
  • USD_SUM - sum of a metric with a currency value converted to USD
  • UNKNOWN_USERS - unique non-Facebook-connected users

enum{COUNT, USERS, TOPK, SUM, USD_SUM, UNKNOWN_USERS}

breakdowns[n]

Breaks down this metric by different values. Each breakdown should be supplied as an array key as shown in the example below. A full list of breakdowns is shown below

enum{client, auth_state}

event_name

Required if you select app_event as your metric name: the name of the app event to query.

string

period

Change the period (from now) over which the metric has been collected. Valid values for each metric are listed below. range is a sum over a date range specified by since and until.

enum{daily, days_28, hourly, monthly, weekly, lifetime, range}

since

A start point for a specified date range.

datetime

until

An end point for a specified date range.

datetime

intervals_to_aggregate

The number of time intervals aggregated per data point returned.

enum{1, 7, 28}

Available Metrics

NameDescriptionValues for period

api_avg_request_time

Average time for API requests from your app in milliseconds

count, daily, range

api_calls

Total API calls from your app

count, daily, range

api_calls_by_method

Sampled API calls from your app

count, daily

api_error_rate_by_method

Sampled average number of errors per API request from your app

count, daily

api_errors

Total API errors from your app

count, daily, range

api_errors_by_method

Sampled API errors from your app

count, daily

app_blocks

Blocks of your app

count, daily, range

app_center_initial_permission_grants

App Center Accepts

count, daily, hourly, range

app_center_initial_permission_requests

App Center Impressons

count, daily, hourly, range

app_event

Custom Events logged for your app - requires event_name be specified

count, daily, hourly, range

app_notification_clicks

Clicks on notifications sent by App to User

count, daily, hourly, range

app_notification_hide_rate

App To User notifications hidden per 10k impressions

count, daily, hourly, range

app_notification_hides

Hides on notifications sent by App to User

count, daily, hourly, range

app_notification_impressions

Impressions for notifications sent by App to User

count, daily, hourly, range

app_notification_sends

App to User Notifications Published

count, daily, hourly, range

app_notification_spam_rate

App To User notifications marked as spam per 10k impressions

count, daily, hourly, range

app_notification_spam_reports

Spam reports on notifications sent by App to User

count, daily, hourly, range

app_notification_total_accepts

App to User Notification Total Accepts explicit and implicit

count, daily, hourly, range

app_notification_unhides

Unhides of previously hidden App To User notifications

count, daily, hourly, range

facebook_features_monthly_active_users

daily counts of users who have engaged with your app or viewed your app during past 30 days

daily

facebook_features_weekly_active_users

daily counts of users who have engaged with your app or viewed your app during past 7 days

daily

facebook_features_daily_active_users

daily counts of users who have engaged with your app or viewed your app

daily

facebook_login_total_users

Total accepts of your app terms of service or connections to your Connect app

count, lifetime

initial_permission_grants

Total accepts from all sources

count, daily, range

login_dialog_additional_permission_grants

Login Dialog Accepts

count, daily, hourly, range

login_dialog_additional_permission_requests

Login Dialog Impressions

count, daily, hourly, range

login_dialog_initial_permission_grants

Login Dialog Accepts

count, daily, hourly, range

login_dialog_initial_permission_requests

Login Dialog Impressions

count, daily, hourly, range

login_dialog_publish_permission_grants

Publish Permission Request Grants

count, daily, hourly, range

login_dialog_publish_permission_requests

Publish Permission Request Impressions

count, daily, hourly, range

mobile_referral_installs

New mobile referral installations of your app. Follows first use of your application on a mobile device.

count, daily, hourly, range

mobile_referrals

App Launches from Facebook on Mobile

count, daily, hourly, range

payments_daily_chargebacks

Chargeback amount

count, daily, range

payments_daily_refunds

Refund amount

count, daily, range

payments_daily_spend

Spend amount

count, daily, range

permission_revocations

Users removed premissions for your app or connections to your Connect site.

count, daily, hourly, range

request_accepts

Number of requests from your app accepted by your users' friends

count, daily, range

request_blocks

Blocked Requests from App

count, daily, hourly, range

request_impressions

Number of times a user has seen a request from your app

count, daily, range

request_sends

Number of requests from your app sent by your users to their friends

count, daily, hourly, range

request_spam_rate

User To User notifications marked as spam per 10k impressions

count, daily, hourly, range

story_clicks

The number of clicks on an Open Graph Story from a selected Action.

count, daily, hourly, range

story_comments

The number of comments on an Open Graph Story from a selected Action.

count, daily, hourly, range

story_impressions

The number of impressions of an Open Graph Story from a selected Action.

count, daily, hourly, range

story_likes

The number of likes on an Open Graph Story from a selected Action.

count, daily, hourly, range

story_publishes

The number of Open Graph Actions created by this application.

count, daily, hourly, range

story_spam_rate

Story spam reports per 10000 impressions of an Open Graph story

count, daily, hourly, range

structured_request_accepts

Number of requests from your app accepted by your users' friends

count, daily, range

structured_request_impressions

Number of times a user has seen a request from your app

count, daily, range

structured_request_sends

Number of requests from your app sent by your users to their friends

count, daily, range

total_referrals

App Launches from Facebook

count, daily, hourly, range

Available Breakdowns

All breakdowns are shown below, though not every breakdown will be available for each metric.

Breakdown TypeDescription

age

Actor age range (gender and age should be used together)

gender

The gender of the actor. (gender and age should be used together)

auth_state

How has user the connected to your application?, 0 has not connected, 1 is Facebook Login.

client

Device type on which the events occurred

country

The country code of the actor

locale

Actor's locale

action_type

Open Graph action type identifier

destination

The destination of a click event

object_type

Open Graph Object type

sponsored

Indicates whether the event resulted from any type of Facebook ad

acquisition_source

Indicates whether an app install was acquired from a Facebook ad, Instagram ad, Audience Network, Facebook organic, or other

acquisition_source_l1

campaign ID that drove the install. Only use with aggregateBy=COUNT

acquisition_source_l2

ad set ID that drove the install. Only use with aggregateBy=COUNT

acquisition_source_l3

ad ID that drove the install. Only use with aggregateBy=COUNT

ref

Developer specified ref parameter. Up to 100 will be returned for any given day

label_cohort

A label which is assigned automatically at first login (e.g. by source: Ad Set ID, Organic Stories, App Center, etc.), but can also be set via the ref parameter in the Login Dialog or the user node.

app_event_parameter1

Developer specified parameter

app_event_parameter2

Developer specified parameter

app_event_parameter3

Developer specified parameter

app_event_parameter4

Developer specified parameter

app_event_parameter5

Developer specified parameter

app_event_parameter6

Developer specified parameter

app_event_parameter7

Developer specified parameter

app_event_parameter8

Developer specified parameter

app_event_parameter9

Developer specified parameter

app_event_parameter10

Developer specified parameter

short_version_code

Bundled version ID of the app (not necessarily unique)

ui_element

Class name of the UI element on top when the event is logged

sdk_version

The version of the Facebook SDK used to log the event

device_model

The model of the device on which the events occurred

device_os

The operating system of the device on which the events occurred

app_name

Bundled name of the app

app_version

Bundled version ID of the app (unique across all versions)

Graph API Explorer
GET /v2.8/{application-id}/app_insights HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{application-id}/app_insights'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{application-id}/app_insights",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{application-id}/app_insights",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{application-id}/app_insights"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Parameters

NameDescription
aggregateBy
enum {COUNT, USERS, TOPK, SUM, USD_SUM, UNKNOWN_USERS, SCORE, MEDIAN_VALUE, DAU, WAU, MAU}

Which aggregation method to use.

breakdowns
list<string>
Default value: Array

breakdowns

ecosystem
enum {GAME, NON_GAME}

Is this for ecosystem data.

event_name
string

The custom event to query if specified.

intervals_to_aggregate
integer

How many interval periods to aggregate.

metric_key
string

metric key

Required
period
enum{mins_15, hourly, daily, weekly, monthly, lifetime, days_28, range}

period

since
datetime

since

until
datetime

until

Fields

Reading from this edge will return a JSON formatted result:

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

data

A list of InsightsQueryResult nodes.

paging

For more details about pagination, see the Graph API guide.

summary

Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=name).

FieldDescription

name

string

Name of the metric of the returned data set

period

string

Time duration of one data point in returned data set

since

datetime

The start time of the returned data set

until

datetime

The end time of the returned data set

messages

list<string>

Information about the returned data

Validation Rules

ErrorDescription
3000Reading Insights of a Page/App/Domain/Event Source Group not owned by the querying user or application
100Invalid parameter
3001Invalid query
3003Metric requires app admin privileges

Creating

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.