Analytics Best Practices

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

The overall cost of API queries for analytics (“stats”) data is dependent upon the amount of data to be fetched per request, not the volume of calls made.
A shared overall cost per-rate-limit window is applied across all analytics endpoints.
Any single query that would cost more than 5,000 will be rejected with a REQUEST_TOO_COMPLEX error response.

x-cost-rate-limit-limit: The total cost limit shared across all analytics endpoints, per window, per user
x-cost-rate-limit-remaining: The cost limit remaining for this window
x-cost-rate-limit-reset: The time (epoch) that this window will reset. Note that this could be different from the existing X-Rate-Limit-Reset timestamp, but they should generally be consistent
x-request-cost: The cost of the request being returned

On queries that are rate limited (those that return an HTTP 429 status code), you must inspect the x-cost-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.
Specify the metrics you care about. If the metrics parameter is not set in your request, the default set of metrics will be returned.
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.

Sample

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