Insights

Parameters

These are the available parameters for reading insights from ad objects: (AdAccount, Campaign, AdSet, Ad).

Parameters

NameDescription
action_attribution_windows
list<enum{1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, default}>
Default value: default

The default option means ["1d_view","28d_click"].
Determines what is the attribution window for the actions. For example, 28d_click means the API returns all actions that happened 28 days after someone clicked on the ad.

action_breakdowns
list<enum{action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_device, action_link_click_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}>
Default value: Array

How to break down action results. Supports more than one breakdowns. Default value is ["action_type"].

action_report_time
enum{impression, conversion}
Default value: impression

Determines the report time of action stats. For example, if a person saw the ad on Jan 1st but converted on Jan 2nd, when you query the API with action_report_time=impression, you will see a conversion on Jan 1st. When you query the API with action_report_time=conversion, you will see a conversion on Jan 2nd.

breakdowns
list<enum{age, country, dma, gender, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, impression_device, place_page_id, publisher_platform, platform_position, device_platform, product_id, region}>

How to break down the result. For more than one breakdown, only certain combinations are available: See "Combining Breakdowns" in the Breakdowns page. The option impression_device cannot be used by itself.

date_preset
enum{today, yesterday, last_3_days, this_week, last_week, last_7_days, last_14_days, last_28_days, last_30_days, last_90_days, this_month, last_month, this_quarter, last_3_months, lifetime}
Default value: last_30_days

Represents a relative time range. This field is ignored if time_range or time_ranges is specified.

default_summary
boolean
Default value: false

Determine whether to return a summary. If summary is set, this param will be ignored; otherwise, a summary section with the same fields as specified by fields will be included in the summary section.

export_columns
list<string>

Select fields on the exporting report file. It is an optional param. Exporting columns will equals to the param fields if you leave this param blank

export_format
string

Set the format of exporting report file. If the export_format is set, Report file will be asyncrhonizely generated. It expects ["xls", "csv"].

export_name
string

Set the file name of the exporting report.

fields
list<string>

Fields to be retrieved. Default behavior is to return a list of most used fields.

filtering
list<Filter Object>
Default value: Array

Filters on the report data. This parameter is an array of filter objects.

field
string
Required
operator
enum {EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, STARTS_WITH, ANY, ALL, AFTER, BEFORE, NONE}
Required
value
string
Required
level
enum {ad, adset, campaign, account}

Represents the level of result.

product_id_limit
integer

Maximun number of product ids to be returned for each ad when breakdown by product_id

sort
list<string>
Default value: Array

Field to sort the result, and direction of sorting. You can specify sorting direction by appending "_ascending" or "_descending" to the sort field. For example, "reach_descending". For actions, you can sort by action type in form of "actions:<action_type>". For example, ["actions:link_click_ascending"]. This array supports no more than one element. By default, the sorting direction is ascending.

summary
list<string>

If this param is used, a summary section will be included, with the fields listed in this param.

summary_action_breakdowns
list<enum{action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_device, action_link_click_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type}>
Default value: Array

Similar to action_breakdowns, but applies to summary. Default value is ["action_type"].

time_increment
enum{monthly, all_days} or integer
Default value: all_days

If it is an integer, it is the number of days from 1 to 90. After you pick a reporting period by using time_range or date_preset, you may choose to have the results for the whole period, or have results for smaller time slices. If "all_days" is used, it means one result set for the whole period. If "monthly" is used, you will get one result set for each calendar month in the given period. Or you can have one result set for each N-day period specified by this param. This param is ignored if time_ranges is specified.

time_range
{'since':YYYY-MM-DD,'until':YYYY-MM-DD}

A single time range object. UNIX timestamp not supported. This param is ignored if time_ranges is provided.

since
datetime

A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.

until
datetime

A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.

time_ranges
list<{'since':YYYY-MM-DD,'until':YYYY-MM-DD}>

Array of time range objects. Time ranges can overlap, for example to return cumulative insights. Each time range will have one result set. You cannot have more granular results with time_increment setting in this case.If time_ranges is specified, date_preset, time_range and time_increment are ignored.

since
datetime

A date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.

until
datetime

A date in the format of "YYYY-MM-DD", which means to the beginning midnight of the following day.

Existing date_presets. These will be deprecated with the new Graph API version.

Preset Definition

today

Today, since 12:00 AM in your account's time zone.

yesterday

Yesterday, the 24-hour period between 12:00 AM and 11:59 PM in your account's time zone.

last_week

The complete 7-day period starting on the previous Monday and ending on the most recent Sunday.

last_month

The complete previous month, starting on the first day and ending on the last day of the month.

last_3_months

The complete previous 2 months, plus all complete days of the current month, not including today.

this_week

The current week, beginning on the most recent Monday and including today.

this_month

The current month, beginning on the first day and including today.

this_quarter

The current quarter, beginning on the first day of the first month of the calendar-year quarter and including today.

last_3_days

Last 2 days, including today.

last_7_days

Last 6 days, including today.

last_14_days

Last 13 days, including today.

last_28_days

Last 27 days, including today.

last_30_days

Last 29 days, including today.

last_90_days

Last 89 days, including today.

lifetime

From the start

Available new date_presets

Preset Definition

today

Today, since 12:00 AM in your account's time zone.

yesterday

Yesterday, the 24-hour period between 12:00 AM and 11:59 PM in your account's time zone.

this_week_sun_today

The current week, beginning on the most recent Sunday and including today.

this_week_mon_today

The current week, beginning on the most recent Monday and including today.

last_week_sun_sat

The complete 7-day period starting on the previous Sunday and ending on the most recent Saturday.

last_week_mon_sun

The complete 7-day period starting on the previous Monday and ending on the most recent Sunday.

this_month

The current month, beginning on the first day and including today.

last_month

The complete previous month, starting on the first day and ending on the last day of the month.

this_quarter

The current quarter, beginning on the first day of the first month of the calendar-year quarter and including today.

last_3d

The complete previous 3 days, ending at 11:59 PM last night and not including today.

last_7d

The complete previous 7 days, ending at 11:59 PM last night (in your account's time zone) and not including today.

last_14d

The complete previous 14 days, ending at 11:59 PM last night (in your account's time zone) and not including today.

last_28d

The complete previous 28 days, ending at 11:59 PM last night (in your account's time zone) and not including today.

last_30d

The complete previous 30 days, ending at 11:59 PM last night (in your account's time zone) and not including today.

last_90d

The complete previous 90 days, ending at 11:59 PM last night (in your account's time zone) and not including today.

this_year

The current year, beginning on January 1 and including today.

last_year

The complete previous year, starting on January 1 at 12:00 AM and ending on December 31 at 11:59 PM.

lifetime

From the start