Marketing API Version

Ad Report Run

Reading

An Ad Report Run is the result of an async job for fetching ad insights.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • ads_read
Page management Apps
No data
Other Apps
No data
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

id

numeric string

ID of this report run

account_id

numeric string

ID for the ad account this Ad Report Run belongs to

async_percent_completion

unsigned int32

Completion percent of async job for this report run

async_status

string

The status of async job for this report run

date_start

string

Earliest date in the time range of the report generated by this Ad Report Run

date_stop

string

Latest date in the time range of the report generated by this Ad Report Run

emails

list<string>

Recipients to send the finished report to

friendly_name

string

Friendly name for this Ad Report Run

is_bookmarked

bool

Whether this Ad Report Run is bookmarked

is_running

bool

Whether this Ad Report Run is still runing

schedule_id

id

ID for the schedule that determines this Ad Report Run's execution

time_completed

unsigned int32

Time when this Ad Report Run was completed

time_ref

unsigned int32

Time when this Ad Report Run was created

Edges

EdgeDescription

insights

Insights results of this Ad Report Run

Validation Rules

ErrorDescription
100Invalid parameter

Creating

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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
Permissions are not usually requested.
Page management Apps
No data
Other Apps
No data

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, this_month, last_month, this_quarter, lifetime, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year}
Default value: last_30d

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 impressions and spend.

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.

Return Type

Struct {
report_run_id: numeric string,
}
You can make a POST request to insights edge from the following paths:
When posting to this edge, an AdReportRun will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
Permissions are not usually requested.
Page management Apps
No data
Other Apps
No data

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, this_month, last_month, this_quarter, lifetime, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year}
Default value: last_30d

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 impressions and spend.

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.

Return Type

Struct {
report_run_id: numeric string,
}
You can make a POST request to insights edge from the following paths:
When posting to this edge, an AdReportRun will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
Permissions are not usually requested.
Page management Apps
No data
Other Apps
No data

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, this_month, last_month, this_quarter, lifetime, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year}
Default value: last_30d

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 impressions and spend.

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.

Return Type

Struct {
report_run_id: numeric string,
}
You can make a POST request to insights edge from the following paths:
When posting to this edge, an AdReportRun will be created.

Permissions

Developers usually request these permissions for this endpoint:

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

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, this_month, last_month, this_quarter, lifetime, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year}
Default value: last_30d

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 impressions and spend.

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.

Return Type

Struct {
report_run_id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter

Updating

You can't perform this operation on this endpoint.

Deleting

You can delete an AdReportRun by making a DELETE request to /{ad_report_run_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter