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 429status code), you must inspect the
x-rate-limit-resetheader 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-afterheader 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_micrometric 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
- Do not pull data for any entities older than 7 days.
- Do request data (ideally) with
HOURgranularity, as you can always aggregate and roll metrics up to get
- Do request data (ideally) at the
promoted_tweetslevel, 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
INTERESTScan 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
- 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.