Ads API •References / estimates / Estimate audience

Estimate audience

Returns audience estimates based on specific ad set parameters.

Request

POST

/estimates/audience

ad_account_id
string [uuid]
Required
A unique identifier for the entity.
Example value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
start_date
string [date-time]
Required
Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
Example value: "2023-09-23T04:56:07Z"
end_date
string [date-time]
Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
Example value: "2023-09-23T04:56:07Z"
asset_format
string
Required
Format of the ad set.
Example value: "AUDIO"Allowed values: "AUDIO", "VIDEO"
objective
string
Required
Objective for a campaign (UNSET cannot be provided as an input)
Example value: "EVEN_IMPRESSION_DELIVERY"Default value: "EVEN_IMPRESSION_DELIVERY"Allowed values: "REACH", "EVEN_IMPRESSION_DELIVERY", "CLICKS", "UNSET"
bid_strategy
string
Required
Strategy for how bids will be applied in the auction. Allowed values:
- "MAX_BID": The bid_micro_amount will act as a bid cap, meaning the maximum amount paid per 1000 impressions.
Example value: "MAX_BID"Allowed values: "MAX_BID"
Required
Budget used for estimation.
Unique items
Specify maximum impressions per user over a given period of time. Will default to the maximum (5 per day, 35 per week, 50 per month) if not specified.
Array maximum length: 3
Required
The targets used during the creation of an ad set.

Response

Audience estimates response

The estimated audience size for daily or lifetime budget.
Array length between 1 and 3
- estimated_frequency_max
  number [double]
  The estimated maximum number of times each user will be served your ad over the lifetime of the campaign.
  Example value: 2.1Minimum value: 0
- estimated_frequency_min
  number [double]
  The estimated minimum number of times each user will be served your ad over the lifetime of the campaign.
  Example value: 1Minimum value: 0
- estimated_impressions_max
  integer [int64]
  The estimated maximum number of ads that will be served.
  Example value: 22000Minimum value: 0
- estimated_impressions_min
  integer [int64]
  The estimated minimum number of ads that will be served.
  Example value: 10000Minimum value: 0
- estimated_reach_max
  integer [int64]
  The estimated maximum number of unique users who will be served your ad at least once.
  Example value: 21000Minimum value: 0
- estimated_reach_min
  integer [int64]
  The estimated minimum number of unique users who will be served your ad at least once.
  Example value: 10000Minimum value: 0
- forecast_type
  string
  The time granularity of the forecast -- if a "LIFETIME" budget type is specified, the API will return a single "LIFETIME" forecast type and if a "DAILY" budget type is specified, the API will return "DAILY", "WEEKLY" and "MONTHLY" forecast types.
  Example value: "DAILY"Allowed values: "DAILY", "WEEKLY", "MONTHLY", "LIFETIME"
likely_to_deliver_budget
boolean
Indicates the likelihood of spending most of the budget.
Example value: true

Response sample

{  "audience_forecast": [    {      "estimated_frequency_max": 2.1,      "estimated_frequency_min": 1,      "estimated_impressions_max": 22000,      "estimated_impressions_min": 10000,      "estimated_reach_max": 21000,      "estimated_reach_min": 10000,      "forecast_type": "DAILY"    },    {      "estimated_frequency_max": 2.1,      "estimated_frequency_min": 1,      "estimated_impressions_max": 144000,      "estimated_impressions_min": 70000,      "estimated_reach_max": 142000,      "estimated_reach_min": 70000,      "forecast_type": "WEEKLY"    },    {      "estimated_frequency_max": 2.1,      "estimated_frequency_min": 1,      "estimated_impressions_max": 660000,      "estimated_impressions_min": 340000,      "estimated_reach_max": 650000,      "estimated_reach_min": 320000,      "forecast_type": "MONTHLY"    }  ],  "likely_to_deliver_budget": true}