Skip to content
All field notes
Measurement
Published
Nov 1, 2026
Reading time
11 min read

Meta Insights API vs Ads Manager: Audit the Report Contract

Reconcile Meta Insights API and Ads Manager totals by matching fields, dates, object scope and complete pages before changing attribution parameters.

AP
AdProof Research
Independent measurement desk
API response pages and a UI export align around a common reporting contract, while delivery receipts and dated action records remain separate.
Match the report contract and extraction completeness before treating unlike totals as a tracking defect. Conceptual illustration without account results.
In this guide (8 sections)

Match the report contract before trying another attribution parameter. An Insights API export and an Ads Manager table need the same metric, object population, dates, filters and extraction scope. First reconcile a small delivery-metric baseline and prove that every response page was processed. Then investigate action definitions and attribution behavior separately.

A conversion-date setting is not a general correction for a spend discrepancy. A parameter appearing in a reference or SDK is also not proof that a current endpoint honors it as an override. Preserve the request, response and UI export that disagree; change one comparison condition at a time.

The real questions behind this audit#

One public developer question about Meta UI and Graph API metrics describes lower API spend and says that changing action-reporting and attribution parameters did not reconcile it. The author also tried different reporting levels. The opened question has no rendered answer establishing a cause.

A separate question about aggregating ad-level metrics reports differences from account-level responses, including action metrics and impressions. Its author already distinguishes reach from additive counts. Merely replying “reach is unique” therefore leaves the reported problem unanswered.

These are older questions, not evidence of a new platform outage. This guide checks the practical task against current official references available on 1 November 2026. It does not reproduce either account's request or verify the cause of its difference. Store-order attribution remains a separate task in the Meta versus Shopify reconciliation guide.

For your campaign

Make the API and Ads Manager reports comparable

Match metrics, objects, dates, filters and extraction scope before changing attribution parameters. Discuss the report contract for your setup.

Discuss a measurement question

A short inquiry to scope relevant options; no campaign access is needed.

1. Write one reproducible report contract#

Start with one completed day, one account and one small, identifiable object population. Save the UI export rather than comparing a changing dashboard screenshot with an old warehouse table.

Contract fieldEvidence to retain
Surface and versionAds Manager report/export context, API version, endpoint and object ID
PopulationAccount, campaign, ad-set or ad level; selected IDs and exclusions
Metric identityExact API field, action type, window-specific value and UI column
CalendarAccount timezone, selected calendar dates and explicit boundaries
Query shapeFields, breakdowns, action breakdowns, filtering and time slices
ExtractionRequest time, UI export time, page completion and job outcome
TransformationRaw response, parser version, row identity and aggregation rule

Keep identifiers and access credentials in a private evidence packet. Redact tokens and credential-bearing pagination links from public tickets or screenshots. A public example should demonstrate the shape of a request without exposing a live account.

Meta's Insights API overview separates reporting levels and query selections. Treat every hidden extractor default as part of the contract. A function called “get account data” can still request ad-level rows, restrict objects or select an unexpected period. Inspect the serialized request that reached the API, not only a configuration form.

For a fixed historical comparison, explicit dates make the cohort reproducible. Relative presets can move when jobs run on different days. Record the returned dates too; do not assume the requested label proves the resulting slice.

2. Establish a delivery baseline before interpreting actions#

Request the minimum fields needed for the first comparison. Keep spend, impressions and the selected click definition separate from purchase actions. Remove unnecessary breakdowns initially and preserve the original more complex query for later comparison.

The current campaign Insights reference describes spend, impressions, clicks, reach and action fields separately. Reach concerns Accounts Center accounts seeing an ad at least once and is estimated; impressions can include repeat views. Spend is also described as estimated. An invoice, a delivery count and a conversion-action total are not interchangeable controls.

If spend already differs, inspect dates, currency, selected object IDs, filters, extraction completeness and transformation before explaining purchase attribution. An action-date parameter does not redefine which spend field was downloaded. Equally, matching spend does not prove that a particular purchase action is comparable.

Test one named metric at a time. “Clicks” might refer to a broad click field, a link-click field or an action entry. Record the exact mapping instead of renaming several inputs to the same warehouse column. Keep units alongside the value; a monetary amount, action count and ratio require different handling.

3. Check current guidance before copying legacy attribution knobs#

Meta's Limits and Best Practices page publishes a change beginning 10 June 2025: it says use_unified_attribution_setting and action_report_time will be disregarded, with ad-set attribution settings and mixed action reporting. In that description, on-Meta actions use impression-based reporting time, while off-Meta actions use conversion-based time.

The documentation is not perfectly consistent. The same page retains an older instruction to set the unified-attribution flag, while parameter references still describe selectable report-time values. Preserve that conflict in an escalation. Do not turn a listed enum into a promise that changing it will override the documented behavior.

Record the deployed API version, relevant account/report settings and actual response. If two otherwise identical authorized requests return the same result after a legacy flag changes, that observation alone does not prove a defect or establish why the flag had no effect. It is evidence to compare with the published guidance.

For a date-basis illustration, suppose an eligible ad exposure occurs on Monday and a purchase on Tuesday. An exposure-date action view and an outcome-date action view assign that purchase to different days. This is a hypothetical explanation of date cohorts, not a claim that your current endpoint lets you select either mode. It does not move Monday's spend into Tuesday or change the purchase into two orders.

Avoid universal claims that every Meta purchase always appears on the click date. Also avoid prescribing one waiting period or promising that delayed purchases will eventually close every gap. Retain comparable snapshots and classify what actually changes.

4. Prove that the extractor finished#

Inspect the response-processing boundary before replacing measurement tags. A valid first response is not proof that the complete result reached storage.

Meta's Graph API pagination guide says that a response can contain fewer rows than the requested limit and still have another page. Even an empty page may carry a next link. The stopping condition is the absence of that link, rather than a short or empty data array. Treat returned pagination links as sensitive when they carry credentials, and do not keep old cursors as durable report identifiers.

For each extraction, retain a private page receipt: page sequence, rows received, next-link presence, completion status and any error. Distinguish a deliberate empty result from a failed job or an interrupted traversal. Check that every page contributes to the output and that retrying a page cannot silently append its rows twice.

If using an asynchronous report, verify its successful completion before consuming its result, then check result pagination as well. Starting a job and receiving its ID does not demonstrate a completed export. On failure or throttling, preserve the response and use the documented paced retry path; do not repeatedly increase request size to chase a total.

5. Audit aggregation at the actual grain#

Keep the raw row identity before summing anything: object ID, calendar slice, requested breakdown values and action dimensions where applicable. A join can multiply rows even when the API response itself is correct. A parser can also drop rows whose action array is empty while those rows still contain delivery metrics.

The official Business SDK's generated Insights object keeps fields such as actions, action_values, spend and reach distinct. Its availability is useful for checking names and types; generated fields do not establish business equivalence or guarantee that every metric can be added across every dimension.

Do not sum every entry in an action array as “purchases.” First identify the exact action type and requested reporting window. Check whether totals and subcategories overlap before adding them. Keep missing, unavailable and explicit zero values distinguishable until the report's semantics justify a transformation.

Unique populations and rates need their own aggregation plan. One Accounts Center account may see several ads, so ad-level reach cannot simply become account reach by addition. For a ratio, keep compatible underlying counts and recompute the intended result rather than adding displayed percentages. When account-level and ad-level results still differ, retain both original requests instead of overwriting one with a forced total.

Hypothetical extraction example

Assume a constructed report with two disjoint ad rows, compatible definitions and no other reporting differences:

RowSpend in one currencyImpressions
First response page: ad A1201,200
Second response page: ad B80800
Complete constructed population2002,000

Stopping after page one understates both measures. Appending the second page twice yields 280 and 2,800. Neither arithmetic problem is repaired by changing an action-report-time flag. These invented values illustrate extractor acceptance tests; they do not diagnose either forum account or promise equality for an arbitrary real query.

6. Retest one boundary and preserve unresolved differences#

Change only the reproduced defect or comparison setting, then rerun the same small contract. Preserve before and after raw responses, extraction times and transformation versions. Check the row-level effect, not only whether the headline total became closer.

FindingNext discriminating action
First page matches, full export differsTrace page traversal, retries and writes
Delivery matches, one action differsInspect action identity, settings and date basis
Unbroken rows differ after a warehouse joinAudit join cardinality and row keys
Only unique or ratio metrics differCheck aggregation definitions and components
Same frozen request changes laterKeep both snapshots and investigate reporting revision
Minimal compatible queries still disagreeEscalate the exact contract and unaltered evidence

A useful escalation includes the smallest reproducing query, API version, timestamps, redacted UI export, private IDs and a precise statement of which fields disagree. Separate confirmed extraction defects from unresolved platform reporting differences. The documentation conflict about legacy parameters belongs in that packet; it is not evidence of an account-wide outage.

Use the broader independent-measurement workflow when comparing separate systems. The tracking QA checklist applies if controlled evidence identifies a collection defect. API report reconciliation alone does not establish incremental sales, invalid traffic or a billing adjustment.

For a separate campaign-delivery review, AdProof supports scoped event and report exports with dates, timezone and supported dimensions and filters. Bring those measured delivery records alongside the API contract, rather than treating them as a native Meta attribution repair. The anonymized fashion-retail delivery-quality case illustrates that delivery-evidence boundary. Discuss a scoped measurement review when that is the question your team needs to answer.

Frequently asked questions#

Will action_report_time fix a spend mismatch?

It concerns action reporting, not a general spend correction. First align the delivery report's dates, object population, fields and complete extraction. Current Meta best-practices guidance also says the legacy parameter is disregarded under its published change; retain version and observed behavior rather than assuming an override.

Can I stop paging when fewer rows than limit arrive?

No. Meta's pagination guidance says a short or even empty page can still have a next link. Continue according to the returned pagination state and distinguish a completed traversal from a failed or interrupted extraction.

Should adding ad rows reproduce every account metric?

No. Unique populations, rates, action definitions and requested breakdowns need compatible aggregation rules. For apparently additive fields, establish complete matching rows and transformations, then retain both minimal queries if a difference remains unexplained.

Does a closer total prove that the fix worked?

No. Missing and duplicated rows can offset, while unrelated settings can move a total. Verify the reproduced boundary with raw rows and a controlled comparison, then preserve any remaining reporting difference and its next check.

Your next step

Make the API and Ads Manager reports comparable

Match metrics, objects, dates, filters and extraction scope before changing attribution parameters. Discuss the report contract for your setup.

Discuss a measurement question

A short inquiry to scope relevant options; no campaign access is needed.

Back to all field notes