Ad Statistics

Ad Statistics are available via the Ads API through the Ad Statistics Query. Statistics can be retrieved at the adaccount, adcampaign, adgroup level.

---

Query Result Fields

The Ad Statistics query result has the following fields.

Name	Description	Permissions	Returns
id	The statistic ID	ads_management	string
account_id	The ID of the object the statistics refer to, this may also be adcampaign_id or adgroup_id	ads_management	long
start_time	A timestamp of the start of the statistics period	ads_management	string
end_time	A timestamp of the end of the statistics period	ads_management	string
impressions	The total number of times your adverts have been shown on the site.	ads_management	int
clicks	The number of clicks the Sponsored Story or advert has received. If you're promoting a Page, event or application, clicks will also include Page likes, event RSVPs or installation of applications directly from the Sponsored Story or advert.	ads_management	int
spent	The amount spent during the selected time period.	ads_management	int
social_impressions	Impressions that were shown social context.	ads_management	int
social_clicks	Clicks on adverts that were shown with social context.	ads_management	int
social_spent	The amount spent during the selected time period on ads with social context.	ads_management	int
actions	A JSON object including number of actions for each action type that was specified using conversion spec. Each number is the sum of actions that resulted from either clicking or viewing an ad. The click through and view through attribution windows can be specified as described below. The default attribution windows are 28 days for click through and 1 day for view through. That is each number is the sum of conversions resulting from either 28 day click through or 1 day view through attributions.	ads_management	JSON object
unique_impressions	The number of individuals this ad was shown to on the site	ads_management	int
unique_clicks	The number of individuals who clicked this ad.	ads_management	int
social_unique_impressions	The number of individuals this ad was shown to with social context	ads_management	int
social_unique_clicks	The number of individuals who clicked this ad while it had social context	ads_management	int
newsfeed_position	Array with statistics about impressions, clicks and average position for your ads and sponsored stories in the news feed. newsfeed_impressions - Number of impressions in the news feed newsfeed_clicks - Number of clicks when the ad or sponsored story was shown in the news feed newsfeed_average_position - Average position where the ad or sponsored story was shown in the news feed. Note: You must supply a date range for this value to be returned in the stats. These stats are only available at the Ad group level.	ads_management	Array

Querying Statistics

Querying statistics by Ad Account

To query the statistics of an account, query the stats connection of the Ad account object:

act_AccountID/stats

This returns a single set of statistics across all adgroups in the account.

{
 "id": "act_12345/stats/0/1346797110",
 "impressions": 9613039,
 "clicks": 2519,
 "spent": 145298,
 "social_impressions": 1306061,
 "social_clicks": 291,
 "social_spent": 10078,
 "unique_impressions": 0,
 "social_unique_impressions": 0,
 "unique_clicks": 0,
 "social_unique_clicks": 0,
 "actions": {
   "like": 139,
   "post_like": 3,
   "comment": 1
 },
 "events": {
   "title_clicks": 378,
   "fans": 456,
   "rsvp_yes": 0,
   "rsvp_maybe": 0,
   "inline_like": 4,
   "inline_comment": 0,
   "photo_view": 2,
   "link_open": 232,
   "video_play": 0,
   "question_vote": 0
 },
 "account_id": 12345,
 "start_time": null,
 "end_time": "2012-09-04T22:18:30+0000"
}

Querying statistics by Ad Campaigns

To query the statistics for each campaign in the account, query the adcampaignstats connection of the Ad account object:

act_AccountID/adcampaignstats

To retrieve stats for specific Ad campaign in an Ad account you can also specify campaign_ids as part of the call:

act_AccountID/adcampaignstats?campaign_ids=[JSON-encoded array of campaign IDs]

If you are querying stats for a large number of Ad campaigns (e.g. >20) it is highly recommended that you use the Graph API Batch Request approach. This allows you to group together multiple requests into a single HTTP call for more efficient processing.

To retrieve stats for one specific Ad campaign in the Ad account, query the stats connection of the Ad campaign object:

{campaign-id}/stats

Querying statistics by Ad Groups

To query the statistics for each Ad group in an Ad account, query the adgroupstats connection of the Ad account object:

specify adgroupstats:

act_AccountID/adgroupstats

To retrieve stats for specific Ad groups in the Ad account you can specify adgroup_ids as part of the call:

act_AccountID/adgroupstats?adgroup_ids=[JSON-encoded array of ad group IDs]

If you are querying stats for a large number of Ad groups (e.g. >20) it is highly recommended that you use the Graph API Batch Request approach. This allows you to group together multiple requests into a single HTTP call for more efficient processing.

To retrieve stats for one specific Ad group in an Ad account, query the stats connection of the Ad group object:

{adgroup-id}/stats

Statistics Dates and Times

Ad Statistics should be retrieved in blocks of one or more days, where the start and end time of the day is defined by the Ad account's time zone. We store the statistics in the timezone of the ad account the statistics represent.

If you request, for example, a 25 hour period, or a 24 hour period which does not align with midnight-midnight in the account's timezone, we'll extend the time range requested until it represents a full day (or days) in the account's timezone. The time period covered in the API response will be clear from the values of the start_time and end_time values of the API response.

Querying Unique Stats

Unique stats are available for time ranges of 1, 7 or 28 days exactly. To receive the unique stats for a given day you must supply the start and end time for the timezone the Ad Account is in but you should express it in UTC. For example if your Ad account is UTC-8 and you want to query the stats for the 29th of November 2011 use the following time stamps:

Start time: 1322553600 (Tue, 29 Nov 2011 08:00:00 UTC) End time: 1322640000 (Wed, 30 Nov 2011 08:00:00 UTC)

As follows:

{adgroup-id}/stats/1322553600/1322640000?access_token=___

Time ranges may also be passed in date format using the start_time and end_time parameters

{adgroup-id}/stats?start_time=2011-11-29T08:00:00&end_time=2011-11-30T08:00:00

Unique stats are available at the ad campaign and adgroup level.

Note: As times are expressed in UTC you must manually adjust for daylight savings time in your request.

Filtering results

Filtering results by time range

To query statistics within a particular time windows, append a start and stop time in the UNIX timestamp to the URL path as follows:

act_AccountID/stats/1320451200/1321315200?access_token=___

Filtering results by deleted

Statistics requests can all be filtered to include or exclude deleted Ad groups and Ad campaigns. To include deleted Ad groups and Ad campaigns set include_deleted=true, to exclude deleted Ad groups and Ad campaigns set include_deleted=false.

act_AccountID/adgroupstats?include_deleted=true

Filtering results by stats mode

Statistics requests can all be filtered to include only Ad groups that have had delivery during this time period. To include Ad groups with delivery during a time period set stats_mode=with_delivery.

act_AccountID/adgroupstats?stats_mode=with_delivery

Specifying attribution window for actions

You can use the following two parameters to control view and click attribution windows for actions that are reported in the stats results. Remember that the reported number for each action is the sum of conversions for both click through and view track attribution windows.

name	Description	Valid values
action_attribution_days_after_click	Click through attribution window (in number of days). To read the number of actions that resulted from only viewing an ad, set action_attribution_days_after_click to 0.	0, 1, 7, and 28
action_attribution_days_after_imp	View through attribution window (in number of days). To read the number of actions that resulted from only clicking an ad, set action_attribution_days_after_imp to 0.	0, 1, 7, and 28

Hourly Stats

It is possible to approximate hourly stats in your own app by refreshing the current day's statistics once each hour, and storing the difference in the metrics between subsequent calls as the stats for the time between the calls.

For example, if your Ad account has a timezone of UTC + 8 hours and you want to query the stats for the 29th of November 2013 you would use the following time stamps:

  {adgroup-id}/stats?start_time=2013-11-29T08:00:00&end_time=2013-11-30T08:00:00

If you made that call on the 29th of November 2013 in the middle of the day, you would receive the stats for that day from the beginning of the day until the time the API call was made. You can then make such a request once per hour, store results and compare to the previous values to calculate how much the stats have changed in the last hour.