Best Practices

Some best practices when collecting analytics data from the Ads API.

Rate Limiting and Retries

  • On queries that are rate limited (those that return an HTTP 429 status code), you must inspect the x-rate-limit-reset header and retry only at or after the time indicated.
  • On queries that result in an HTTP 503 Service Unavailable status code, you must inspect the retry-after header and retry only after the time indicated.
  • Applications that do not respect the times indicated for retries could have their access to the Ads API revoked or throttled without notice.

Analytics Metrics In a Nutshell

  • All analytics metrics are locked and will not change after 24 hours, with the exception of billed_charge_local_micro.
  • The billed_charge_local_micro metric is an estimate for up to 3 days after the data is returned.
  • After 24 hours, this metric can decrease due to credits for overspend (ads served after the given end_time) and for billable events that are determined to be junk. This metric changes minimally after 24 hours.
  • Please see Analytics for more information.

Fetching Real-time, Non-segmented Data

  • Always provide both a start_time and an end_time.
  • Do not pull data for any entities older than 7 days.
  • Do request data (ideally) with HOUR granularity, as you can always aggregate and roll metrics up to get DAY and TOTAL granularity.
  • Do request data (ideally) at the line_items and promoted_tweets level, as you can always aggregate and roll these metrics up to get totals across the entire ads entity hierarchy (i.e. for the campaign, funding instrument or account levels).
  • Save and store the values of analytics metrics on your side (locally).
  • Do not repeatedly query for data that is older than 30 days. This data will not change and should be stored locally.
  • All non-segmented data is real-time and data should be available within seconds of an event occurring.
  • Group conversion metrics and non-conversion metrics into separate requests.

Fetching Segmented Data

  • Refer to guidelines provided for “Fetching Real-time, Non-segmented Data” above. Additional advice provided below.
  • For most segmented data types, it is possible for data to not be complete for up to 1 hour at times. Data segmented by INTERESTS can be delayed for up to 12 hours.
  • Segmented data is not expected to roll-up 100% to the non-segmented data, due to how this information is derived.

Fetching Historical Data

  • When backfilling data (i.e. adding a new advertiser account), you may need make several requests in smaller start_time and end_time chunks.
  • Limit your fetches to 30-day date windows.
  • Throttle these requests and distribute over time so as not to exhaust your rate limits for these fetches.


You can find a sample script demonstrating some of these best practices (fetch_stats) on our ads-platform-tools github repository.