Graph API Version

Reach and Frequency Prediction

For reach and frequency ads buying, see Reach and Frequency.

Reading

You can reach all Reach Frequency Prediction objects from one ad account, or reach a Reach Frequency Prediction object from a Reach Frequency Prediction ID. Specify the fields you wish to retrieve. Only the id is returned by default.

Limitations

stop_time must be no greater than 8 weeks ahead of the current time and should end after 6AM on the last day in ad account time zone

Examples

To read a reachfrequencyprediction object based on the reachfrequencyprediction ID, make an HTTP GET call to

https://graph.facebook.com/<API_VERSION>/<RF_PREDICTION_ID>

To read all predictions of an ad account, make an HTTP GET call to

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/reachfrequencypredictions

You can retrieve frequency_distribution_map_agg which is similar to frequency_distribution_map. It contains a list of key-value pairs where each key is a predictable number of people reached by your ad. Each value is a list of 10 numbers, each representing the number of people reached greater than or equal to 1 time, 2 times and so on. The last number represents the number of people reached greater than or equal to 10 times.

We calculate it from frequency_distribution_map. For example, when the key is 300000, and the corresponding value in frequency_distribution_map is [0.4, 0.3, 0.2, 0.1], then the corresponding value in frequency_distribution_map_agg is:

[300000, 180000, 90000, 30000, 0, 0, 0, 0, 0, 0]

Where:

300000 = 300000 * (0.4 + 0.3 + 0.2 + 0.1)
180000 = 300000 * (0.3 + 0.2 + 0.1)
90000 = 300000 * (0.2 + 0.1)
30000 = 300000 * 0.1
0 = 300000 * 0

A sample results looks like this:

[
{
"key": 1709356,
"value": [1709356, 228277, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 2895340,
"value": [2895340, 364337, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 4813219,
"value": [4813219, 578598, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 7100208,
"value": [7100208, 909735, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 9297083,
"value": [9297083, 1310776, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 11789412,
"value": [11789412, 1908920, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 16689431,
"value": [16689431, 3541420, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 22604943,
"value": [22604943, 6147670, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 28290359,
"value": [28290359, 9590814, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 33925018,
"value": [33925018, 13974507, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 39074602,
"value": [39074602, 18678920, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 45360719,
"value": [45360719, 24821231, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 49071193,
"value": [49071193, 28509962, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 51717935,
"value": [51717935, 31289564, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 53691761,
"value": [53691761, 33453257, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 55213522,
"value": [55213522, 35167178, 0, 0, 0, 0, 0, 0, 0, 0]
},
{
"key": 57123528,
"value": [57123528, 37726279, 0, 0, 0, 0, 0, 0, 0, 0]
}
]

Example

Graph API Explorer

GET /v5.0/{reach-frequency-prediction-id} 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(
    '/{reach-frequency-prediction-id}',
    '{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(
    "/{reach-frequency-prediction-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{reach-frequency-prediction-id}",
    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:@"/{reach-frequency-prediction-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

Field	Description
`id` numeric string	The ID of this reach frequency prediction Default
`account_id` integer	The ID of the Ad Account this reach frequency prediction belongs to
`campaign_group_id` integer	The id of the campaign which this prediction belongs to
`campaign_id` numeric string	The ID of the ad set to which this reach frequency prediction is assigned
`campaign_time_start` datetime	Unix timestamp of the ad set start time
`campaign_time_stop` datetime	Unix timestamp of the ad set stop time
`curve_budget_reach` ReachFrequencyEstimatesCurve	The curve for budget and reach. It is a string in JSON format representing a JSON object with these fields. `num_points`: the number of data points within the object. `reach`: Data contained at corresponding indices of each array form a single data point. The "reach" values are presented in ascending order with the final value containing the maximum available reach. In video view buying, this is the number of unique users with views`raw_reach`: Data contained at corresponding indices of each array form a single data point. In video view buying, reach representsunique view throughs and raw_reach represents unique views `budget`: Data contained at corresponding indices of each array form a single data point. Cent of accounts currency. `impression`: Data contained at corresponding indices of each array form a single data point. In video view buying, this is the number of view throughs (aka impression by conversion)`interpolated_reach`: Interpolated reach which is the original.value of reach without truncation`raw_impression`: Data contained at corresponding indices of each array form a single data point. In video view buying,impressions represents view throughs and raw_impressions representstotal number of views
`daily_impression_curve` list<float>	Daily Impression field represents a vector of predicted daily impressions for every single day. Measured from midnight to midnight in the advertiser timezone during the campaign duration.
`destination_id` id	The ID of the Page or the ID of the app which the ad promotes.
`expiration_time` datetime	Unix timestamp of the expiration time of prediction, if applicable
`external_budget` integer	Predicted budget in cents for the ad set, relevant if prediction mode is 0
`external_impression` unsigned int32	Predicted impressions for the ad set
`external_maximum_budget` integer	Maximum budget given the target, in cents
`external_maximum_impression` impressions	Maximum number of impressions given the target
`external_maximum_reach` unsigned int32	Maximum reach given the target
`external_minimum_budget` integer	Minimum budget given the target, in cents
`external_minimum_impression` unsigned int32	Minimum impressions given the target
`external_minimum_reach` unsigned int32	Minimum reach given the target
`external_reach` unsigned int32	Predicted reach for the ad set, relevant if prediction mode is 1
`frequency_cap` unsigned int32	Lifetime frequency cap per user, always relevant, 0 means no frequncy cap
`frequency_distribution` list<float>	A list of predicted percentages. The first value in the list represents the predicted percentage of people that will be reached once. The second value is the predicted percentage of people reached twice, and so on.
`frequency_distribution_map` list<KeyValue:unsigned int32,list<float>>	A list of key-value pairs. Each key is a predicted number of people reached by your ad and each value is a frequency_distribution associated with that reach.
`frequency_distribution_map_agg` list<KeyValue:unsigned integer,list<unsigned integer>>	A list of key-value pairs. Each key is a predicted number of people reached by your ad and each value is a list of 10 numbers associated with that reach. The first number represents the number of people reached which is greater than or equal to 1 time, 2 times and so on. The last number represents the number of people reached which is greater than or equal to 10 times.
`grp_dmas_audience_size` float	GRP: Audience size within DMAs based on Nielsen definition
`holdout_percentage` unsigned int32	Percent of users in holdout
`instagram_destination_id` id	The Instagram account id if `instagramstream` placement is used, except in the case of Mobile App Installs ads.
`interval_frequency_cap` unsigned int32	Interval frequency cap which is set for a custom period
`interval_frequency_cap_reset_period` unsigned int32	Custom reset period (hours) for interval frequency cap
`is_io` bool	Flag to indicate whether prediction is tied to an IO
`name` string	Prediction name.
`pause_periods` list<(struct with keys: pauseStartDay, startTimeOffset, pauseEndDay, endTimeOffset) or (null)>	A list of time periods the associated campaign has been paused.
`placement_breakdown` ReachFrequencyEstimatesPlacementBreakdown	Predicted impression distribution on different placements , including: `msite`: Facebook mobile sites `android`: Facebook android `ios`: Facebook ios `desktop`: Facebook desktop news feed and right hand column `ig_android`: Instagram android `ig_ios`: Instagram ios `ig_others`: Other Instagram placements
`prediction_mode` unsigned int32	The prediction mode, 0 = given reach, predict budget, 1 = given budget, predict reach
`prediction_progress` unsigned int32	Represents percentage value indicating the prediction progress (values 0-100). When 100 check status to indicate whether the prediction was successful.
`reservation_status` unsigned int32	Reservation status. 0 = Cancelled prediction, 1 = Reserved prediction, 2 = Prediction has been attached to a campaign
`status` unsigned int32	Represents the status of the prediction, refer to Response Status
`story_event_type` unsigned int32	Used to indicated the prediction is for video ads or not. If it is for video, the prediction will not include devices that cannot play video
`target_audience_size` unsigned int32	Unique 30-day active users for given targetting specs. Used as tip to indicate the maximum possible audience size if campaign length is increased
`target_spec` Targeting	A string in JSON format representing the targeting specs specified on creation.
`time_created` datetime	The time when this reach frequency prediction was created
`time_updated` datetime	Unix timestamp when the row is updated

Validation Rules

Error	Description
100	Invalid parameter
80004	There have been too many calls to 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.

Creating

You can make a POST request to reachfrequencypredictions edge from the following paths:

/act_{ad_account_id}/reachfrequencypredictions

When posting to this edge, a ReachFrequencyPrediction will be created.

Parameters

Parameter	Description
`budget` int64	Expected lifetime budget in cents in the currency for the ad account. Must be greater than the default budget limit.
`campaign_group_id` numeric string or integer	The ID of the campaign which this prediction belongs to.
`day_parting_schedule` list<Object>	Ad set schedule, representing a delivery schedule for a single day Example: `[{"start_minute":360,"end_minute":1440,"days":[0,1,2,3,4,5,6]}]` The day part should be same for all week days. There needs to be at least 3 hours of delivery each day.
`start_minute` int64	A 0 based minute of the day representing when the schedule starts Required
`end_minute` int64	A 0 based minute of the day representing when the schedule ends Required
`days` list<int64>	Array of ints representing which days the schedule is active. Valid values are 0-6 with 0 representing Sunday, 1 representing Monday, ... and 6 representing Saturday. Required
`timezone_type` enum {USER, ADVERTISER}	Default value: `USER`
`deal_id` numeric string or integer	The ID of the deal which this prediction belongs to.
`destination_id` int64	The ID of the Page or the ID of the app which the ad promotes. Using the correct advertiser Page or app ID makes your predictions more accurate. Reach and cost predictions for feed are specific to a given ID. They take into account other ads running from the same Page, as well as the past creative quality of ads from the Page, which impacts cost. If the ad set has `desktopfeed` or `mobilefeed` placement, specify `destination_id` or pass app or Page ID in `destination_ids` field. We recommend using `destination_ids`.
`destination_ids` list<numeric string or integer>	Array of ID's of the Facebook Page or App which the ad promotes. Also include the Instagram account ID if `instagramstream` placement is used. If the `objective` is `MOBILE_APP_INSTALLS`, provide only the app ID. In this case, do not provide Instagram account ID, even with `instagramstream` placement.
`end_time` int64	Same as `stop_time`.
`frequency_cap` int64	If `interval_frequency_cap_reset_ period` is specified, this field represents the frequency cap to be set for a custom period. For example: show ad 3 times per user every 48 hours. However when you read the values back, this represents the lifetime frequency cap for the campaign duration. A separate read-only field called `interval_frequency_cap` provides the frequency cap value originally set for the custom period. If `interval_frequency_cap_reset_period` is not specified, this field represents the lifetime frequency cap set for the campaign duration.
`instream_packages` array<enum {NORMAL, PREMIUM, SPORTS, ENTERTAINMENT, BEAUTY, FOOD, SPANISH, REGULAR_ANIMALS_PETS, REGULAR_FOOD, REGULAR_GAMES, REGULAR_POLITICS, REGULAR_SPORTS, REGULAR_STYLE, REGULAR_TV_MOVIES}>	Instream package of the campaign. Reserve buying campaigns and self-serve contextual package campaigns need to set the targeting packages here. Those campaigns will only deliver to pages included in the targeting packages
`interval_frequency_cap_reset_period` int64	Custom period to reset frequency cap. In hours. Expressed as multiples of 24. For example, to show ad no more than 3 times every 48 hours, reset period should be set to 48 (hours) and `frequency_cap` should be set to 3. Implemented using a rolling window.
`num_curve_points` int64	How many grid points to return from the curve. If the value is not specified, the default value (800) is used. If the value is larger than 800 then 800 will be used.
`objective` string	Default value: `REACH` Objective of your reach and frequency campaign. Facebook uses this to create an optimized bid based on your objective. This does not modify you objective set at the ad campaign level. Of all possible ad objectives, you can only use these values in Facebook Reach and Frequency campaigns: `BRAND_AWARENESS`, `LINK_CLICKS`, `POST_ENGAGEMENT`, `MOBILE_APP_INSTALLS`, `WEBSITE_CONVERSIONS`, `REACH`, and `VIDEO_VIEWS`.
`prediction_mode` int64	Set `0` to create a prediction of budget based on expected reach. `reach` value must be provided. Set `1` to create a prediction of reach based on expected budget. `budget` value must be provided.
`reach` int64	The desired reach of the set, must be at least the minimum reach for the target country. This number is 1,000,000, in most cases.
`rf_prediction_id_to_share` numeric string or integer	ID of a previously created prediction. The new prediction will also use the audience from the given prediction.
`start_time` int64	Unix timestamp for the set start time.
`stop_time` int64	Unix timestamp for the set stop time. Must be no greater than 8 weeks ahead of the current time. It should end after 6AM on the last day, in the ad account's timezone.
`story_event_type` int64	Whether or not to include mobile devices that cannot display different ad formats: - Use `256`, to run canvas ads - Use `128` to run video ads - Use `0` if you do not include video or canvas ads - Use `384` (256 + 128), to include both canvas and video. You cannot create video ads if you set this flag to `0` during prediction. You can create non-video ads if the flag is set to `128`. This field is required if you target all mobile devices. You cannot create canvas ads if this flag is set to `0` during prediction. However, you can create non-canvas ads even the flag is set to `256`.
`target_spec` Targeting object	Targeting spec for reach and frequency prediction. The length of JSON serialized API targeting spec should not exceed 65000 characters after internal reformatting. You cannot: - Use `rightcolumn` together with any feed for placement. - Specify more than one country. - Provide minimal iOS version for `user_os`. Website Custom Audiences and `friends_of_connection` are not supported.

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

}

Validation Rules

Error	Description
2627	You do not have permission to run a reach and frequency campaign.
80004	There have been too many calls to 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.
2625	The request for a reach frequency campaign is invalid.
100	Invalid parameter
2628	There is an error in updating the state for the given prediction.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.