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.

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.

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.

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.

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.