English
Deutsch
PolskiMeta Insights API: Checking Breakdown Availability and Completeness
Contents
A successful Insights API response does not prove that a breakdown is available or complete. Since 6 August 2026, Meta has restricted certain breakdowns on some ad accounts until the relevant feature is enabled. Empty results therefore need an explicit diagnosis instead of automatic conversion to zero.
Which breakdowns are affected?
Meta’s announcement names impression_device, hourly_stats_aggregated_by_audience_time_zone and frequency_value. The device restriction also affects combinations containing that dimension. This is not a general restriction on every breakdown or every ad account. The advertiser-time-zone breakdown is a different dimension.
Other compatibility rules still apply. For example, frequency_value is used with reach for Reservation campaigns. Hourly breakdowns do not support unique metrics, reach or frequency; documented zero values for unsupported metrics are not evidence of zero activity. Hourly data also has a 13-month history limit. Certain off-Meta action metrics are unavailable with particular breakdowns.
Feature status, effective date and historical data
The read-only endpoint GET /act_<ID>/insights/feature-settings/list-features lists available features. GET /act_<ID>/insights/feature-settings lists enabled features. The relevant feature names include impression_device, time_of_day_viewer_tz and frequency_value. These names are not identical to every corresponding breakdown parameter.
An absent entry in a complete, authorized enabled-feature response indicates a disabled feature. A failed request, incomplete pagination or missing permission does not provide that evidence. Where returned, insights_effective_date identifies the first available date. An absent effective date is documented as availability for all dates, subject to the applicable history and metric restrictions.
Meta documents enablement through Ads Manager and the feature-settings API. The API enable operation changes account configuration, has no corresponding disable operation and can take about 24 hours to become effective. A successful enable response alone does not verify data availability; the subsequent feature status and actual report results matter.
The official documentation contains differing wording about asynchronous requests. Availability notices on the breakdown page present an asynchronous request as an alternative to administrator enablement. The more specific out-of-cycle announcement dated 8 May, effective 6 August, says that both synchronous and asynchronous requests can return no results without enablement. That announcement describes historical asynchronous retrieval after enablement, with a daily quota of min(10, number_of_ad_groups). An asynchronous job is therefore not a guaranteed bypass. Feature status, effective date, permitted history and actual job results need validation for the account.
A reconciliation is an alarm, not a completeness certificate
In an example, a comparable account total contains 184,300 impressions and the retrieved breakdown contains 121,940. The difference is 62,360, or approximately 33.8% of the total. For a supported, mutually exclusive and exhaustive partition of an additive metric, that discrepancy warrants investigation. The percentage does not identify the cause or prove that enablement is missing.
Reconciliation requires the same account, reporting level, dates, time zone, filters, metric definition and effective attribution settings. Results fetched at different times can also differ because reporting data changes. Permissions, API version, unsupported combinations, missing pages and incomplete asynchronous jobs remain possible causes.
Not every metric is additive. Reach can count the same person in several groups: two groups with reach 80 and 70 can have a combined reach of 100. Summing all action types can also double-count hierarchical categories. Ratios and averages require appropriate denominators. Meta additionally describes breakdown values as estimates, so an appropriate tolerance depends on the metric and documented behavior.
Even exact equality is insufficient. Expected rows A=60 and B=40 have the same total as incorrect rows A=40 and B=60. Duplicate rows can compensate for omitted rows. A total comparison cannot establish correct allocation, unique keys or the presence of every requested dimension.
A practical validation sequence
- Request contract: account access, permissions, API version, supported fields and breakdown combinations, feature status and available period are recorded.
- Transport and job status: errors are retained. For asynchronous reports, both completed job status and 100% completion are checked before results are fetched.
- All pages: every
paging.nextlink is followed. An empty page can still contain a next link; page length alone is not an end condition. - Rows and schema: required fields, requested dimensions, unique row keys and missing values are checked. Missing data stays distinct from a measured zero.
- Eligible reconciliation: only compatible additive metrics are compared with a separately retrieved total. A mismatch raises an investigation; equality supplements the other checks.
A failed or unexplained empty extract should not overwrite a previously valid partition with zeros. The pipeline can retain the last valid snapshot with a visible age and error status. Validated empty results can be stored as empty only when the requested scope and availability are understood. Historical reprocessing follows the verified available period and quotas, rather than assuming that enablement makes all past data retrievable.
Frequently asked questions
Does HTTP 200 establish data completeness?
No. It establishes successful handling at the HTTP level. Feature availability, metric support, pagination and row validation remain separate checks.
Does an extra total request solve the problem?
No. It adds a useful comparison for eligible metrics, with additional quota and maintenance costs. It cannot replace feature checks or row-level validation.
Does missing enablement always produce an empty success response?
No universal response pattern is guaranteed here. The announcement describes possible missing results for affected accounts; other errors and causes must remain visible.
Sources
Related articles
