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]
}
]

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription
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

audience_size_lower_bound
unsigned integer

audience_size_lower_bound

audience_size_upper_bound
unsigned integer

audience_size_upper_bound

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 viewsraw_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 truncationraw_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_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_story: Instagram Stories
ig_others: Other Instagram placements
audience_network: Audience network
instant_articles: Instant articles
instream_videos: In-stream videos
suggested_videos: Suggested videos

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_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 Codes

ErrorDescription
100Invalid parameter
368The action attempted has been deemed abusive or is otherwise disallowed
80004There 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'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.