Analytics

We provide synchronous and asynchronous methods for retrieving detailed statistics on the performance of your campaigns. The synchronous endpoint returns smaller batches of data ideal for real-time campaign optimizations. The asynchronous endpoint is intended for larger queries of complex data, ideal for generating reporting or historical backfills. We have documented some general best practices for consuming our analytics that we recommend all developers read.

For information on analytics in version 0 of the Ads API, please see our deprecated Analytics Overview. For details and recommendations on migrating from version 0 to version 1, see our Migration Guide

Analytics Implementation Details

Synchronous vs Asynchronous Requests

The synchronous and asynchronous endpoint accept parameters and return data in similar ways, with a few notable exceptions:

  • The synchronous analytics endpoint returns up to 7 days of non-segmented analytics data.
  • The asynchronous analytics endpoint returns up to 90 days of non-segmented analytics data, or up to 45 days of segmented data.
  • The synchronous analytics endpoint returns analytics as uncompressed JSON data in the response.
  • The asynchronous analytics endpoint returns the processing state of the analytics query. After a query has completed and is successful, a URL will be returned where the results can be fetched.
  • Asynchronous result files are compressed (gzip) to optimize transfers, and must be uncompressed before access. Because of this, the Accept-encoding: gzip header is required for requests to the asynchronous analytics endpoint.

Additionally, asynchronous analytics queries are subject to the following limits:

  • A maximum of 100 concurrent (queued or processing) asynchronous job queries are permitted per advertiser account.
  • Result files expire 48 hours after the job is successful and the URL is returned.
  • Queries taking over 60 minutes to process with automatically time out.

Billed versus Estimates

The BILLING metrics group provides a real-time view into the estimated cost of a campaign. After three days, the official billed result will be available through the BILLING metric group’s billed_charge_local_micro and billed_engagements.

All billing stats are generally final within 3 days of the event (~99%), however we do process some spam filtering for up to 14 days from the date of the event.

Please note that spend metrics are not available for dates before 2013-10-10.

Metric groups

Metric groups are families of related metrics. A complete list of metrics contained within each metrics group is detailed on the Metrics and Segmentation page. Metrics must be fetched as a metrics group, and multiple metrics groups may be requested in an analytics query.

Determine the relevant metric groups for your analytics request based on the objectives. See the Metrics by Objective for a detailed breakdown.

Timelines

As soon as stats are available, you are able to retrieve them. The feedback on stats is real-time. These early results are estimates, the stats are finalized after 24 hours, except for spend metrics. Keep in mind that the API rate limit window is 1 minute long, and too-frequent requests against the stats API endpoints will trigger the rate limit. Partners should detect rate limiting and wait for rate limit windows to reset before retrying queries that were throttled.

Data Returned in Time Series

Data is returned for each metric in a time series based on your request of either HOUR (recommended), DAY or TOTAL granularity. If no data for a metric was collected during the requested time window or if a metric is invalid for the entity, a null value will be returned in place of a time series.

Rate Limiting

Synchronous Analytics Requests

Synchronous analytics utilize a query based rate limiting model for all endpoints, similar to our WRITE-based rate limiting. All rate limit windows for synchronous analytics are 15-minute windows.

Asynchronous Analytics Requests

Asynchronous analytics queries are subject to the Ads API WRITE-based rate limits.

Overly Complex Queries

Queries with a time range that is expected to take a significant amount of time to generate will be rejected with a HTTP 400 Bad Request error of the REQUEST_TOO_COMPLEX variety, with a message of This request is too expensive to compute, try a smaller time range.

{
  "errors": [
    {
      "code": "REQUEST_TOO_COMPLEX",
      "message": "This request is too expensive to compute, try a smaller time range"
    }
  ],
  "request": {
    "params": {
    }
  }
}

Specifying Time Ranges

Each of the stats endpoints has a start_time and end_time parameter which can be set to delineate a time range for the stats being requested. start_time must be aligned to the granularity value being requested.

  • TOTAL: start_time can be any value.
  • DAY: start_time must be midnight in the timezone of the account, relative to UTC. For example, if the timezone of the account is America/Los_Angeles during Pacific Time, then the start_date for June 16, 2013 must look like: 2013-06-16T07:00:00Z. It would also be acceptable to specify the timestamp as midnight with the correct offset, for example, 2013-06-16T00:00:00-07:00
  • HOUR: start_time must be an hour without minutes specified, in the timezone of the account relative to UTC. For example, if the timezone of the account is America/Los_Angeles during Pacific Time, then the start_date for 4:00pm, June 16, 2013 must look like: 2013-06-16T23:00:00Z (or equally acceptable, 2013-06-16T16:00:00-07:00.)

end_time, if unspecified, will default to the current time. Currently, end_time is not validated for a particular alignment as per start_time. When dealing with granularity DAY, any end_time that is between start_time+00:00:01 to start_time+24:00:00 will return one day of stats. Any end_time that is between start_time+24:00:01 to start_time+48:00:00 will return two days of stats. And so on. Likewise for granularity HOUR, on a per-hour basis.

Segmentation Reporting

Segmentation reporting allows the retrieval of metrics broken out by the values of a given targeting type. More details on segmentation options can be found at Metrics and Segmentation in Analytics.

Segmentation queries are subject to the same time limits (formerly complexity) as normal reporting. We suggest querying on a shorter time period if you encounter repeated 503 errors.