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.

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.

Recommended use of Synchronous vs Asynchronous endpoints

We highly recommend to do the greater majority of your analytics syncing with the asynchronous endpoints. The endpoint would give more stability and throughput to your system, as well as being the only way to fetch metrics split up by segmentation.

The synchronous endpoint should never be used for syncing large amounts of data in a process like onboarding a new account.

Synchronous Endpoint:

  • May be used for real-time optimization based upon changes to metrics within the last 5 to 15 minutes.
  • The endpoint can only be called with whole hours, so any deltas in metrics minute over minute have to be determined by the calling platform.
  • It as critical to follow best practices, and consider it a limited resource to make effective use for real-time optimization.

Asynchronous Endpoint:

  • May be used to sync data in large quantities.
  • The asynchronous endpoint can be used for rendering dashboards and other UI elements if data is synced with a backend process.
  • Your implementation should avoid having to call the asynchronous endpoint to fulfill a user interface request, instead a page where a user can view the status would be recommended as an alternative.
  • You must still implement a retry logic upon the asynchronous endpoint for the cases where a job may timeout (estimated to time out approximately 1 hour after beginning to process). If the job is timing out persistently, please reduce the amount of data being requested or contact the community forum with details.
  • If a job is stuck in the PROCESSING state, use the DELETE stats/jobs/accounts/:account_id/:job_id to cancel the job, and retry

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

There is currently a 100 concurrent job limit which is scoped to the account. In other words, only 100 jobs for a given ads account can be in a processing state at any given time.

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.

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.