Marketing API Version

Reach Frequency Prediction

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.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

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

FieldDescription

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

id

numeric string

The ID of this reach frequency prediction

curve_budget_reach

string

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)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

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

name

string

Prediction name.

pause_periods

string

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

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

Edges

No edges

Validation Rules

ErrorDescription
100Invalid parameter

Creating

You can make a POST request to reachfrequencypredictions edge from the following paths:
When posting to this edge, a ReachFrequencyPrediction will be created.

Parameters

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

- Day part should be same for all week days.
- 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
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 will make your predictions more accurate. Reach and cost predictions for feed are specific to a given ID, as 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, either specify destination_id or pass app or page id in destination_ids field. Using destination_ids is recommended.

destination_ids
list<numeric string or integer>

Array of ID's of the Facebook Page or App which the ad promotes. Also the Instagram account id if instagramstream placement is used. However, if the objective is MOBILE_APP_INSTALLS, only the app id is needed here. Do not provide Instagram account id even if instagramstream placement is used.

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, such as 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 and a separate read-only field, 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.

interval_frequency_cap_reset_period
int64

Custom period (in hours expressed as multiples of 24) to reset frequency cap. 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: POST_ENGAGEMENT

Objective of your reach and frequency campaign. This is used to better inform the optimized bid based on your objective. This will not modify the objective set at the ad campaign level. Of all possible ad objectives, only these values are allowed in Facebook R&F campaigns: BRAND_AWARENESS, POST_ENGAGEMENT, MOBILE_APP_INSTALLS, LINK_CLICKS, CONVERSIONS, and VIDEO_VIEWS. All of them except CONVERSIONS can be supported for R&F campaigns on Instagram.

prediction_mode
int64

0 to create a prediction of budget based on expected reach (reach value must be provided),
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, 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 and should end after 6AM on the last day in ad account 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

If you include both canvas and video, set to 384 (256 + 128).
Note: You can not 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. 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. Please note that
- You cannot use rightcolumn together with any feed for placement.
- You cannot specify more than one country.
- Providing minimal iOS version for user_os is not supported.
- The followings are not supported: friends_of_connection, Website Custom Audiences and Audience network.
- The length of JSON serialized API targeting spec should not exceed 75,000 characters.

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

ErrorDescription
100Invalid parameter

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.