For reach and frequency ads buying, see Reach and Frequency.
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.
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
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] } ]
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
}];
Field | Description |
---|---|
id numeric string | The ID of this reach frequency prediction |
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. |
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 |
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: |
prediction_mode unsigned int32 | The prediction mode, |
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. |
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 |
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. |
reachfrequencypredictions
edge from the following paths: 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 |
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 |
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 If the |
end_time int64 | Same as |
frequency_cap int64 | If However when you read the values back, this represents the lifetime frequency cap for the campaign duration. A separate read-only field called If |
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 |
num_curve_points int64 | How many grid points to return from the curve. |
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: |
prediction_mode int64 | Set |
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: You cannot create video ads if you set this flag to |
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: Website Custom Audiences and |
id
in the return type.id
: numeric string, 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. |