Meta Ads Insights API Structure

The Meta Marketing API is a Graph API — every object has an ID, and you navigate between objects by traversing edges. Understanding the hierarchy and the Insights “edge” is the foundation for building any reliable Meta Ads pipeline.

The Five-Level Object Hierarchy

Meta’s ad structure has five levels:

Business Manager
└── Ad Account
    └── Campaign
        └── Ad Set
            └── Ad

Business Manager is the top-level container. It holds ad accounts, pages, pixels, system users, and permissions. Most pipelines interact at the Ad Account level and below, but Business Manager is where you manage authentication.

Ad Account is the billing unit. All spend is tracked at this level. A single Business Manager can have dozens of ad accounts — each for a different brand, market, or client. If you’re building a multi-account pipeline, you need to know all account IDs upfront (the API doesn’t have a clean “list all ad accounts” endpoint with broad coverage).

Campaign controls the objective (awareness, traffic, conversions, leads). Budgets can live at campaign level (campaign budget optimization) or ad set level.

Ad Set controls targeting, placement, schedule, and budget. This is where audience targeting lives: demographics, interests, custom audiences, lookalikes.

Ad is the creative level — the actual image, video, copy, and call to action shown to users.

You can pull Insights at any level of this hierarchy by calling the Insights edge on the corresponding object ID.

The Insights API

Performance reporting comes entirely from the Insights API. It’s technically an “edge” of the Marketing API — you call it as:

GET /{object-id}/insights

Where {object-id} is the ID of a business, ad account, campaign, ad set, or ad. The response contains the metrics for that object and the time range you specify.

Key parameters

The most important request parameters to understand:

params = {
    'fields': 'impressions,clicks,spend,actions,action_values',
    'date_preset': 'last_28d',          # or use time_range
    'time_increment': 1,                 # 1 = daily breakdown
    'level': 'ad',                       # account|campaign|adset|ad
    'action_attribution_windows': ['7d_click', '1d_view'],  # required!
    'breakdowns': [],                    # optional: age, gender, country, etc.
}

If you don’t pass action_attribution_windows, Meta uses its defaults — which may not match what Ads Manager shows. Always specify attribution windows explicitly. This is the single most common cause of discrepancies between warehouse data and the platform UI.

The time_increment: 1 parameter requests daily breakdowns. Without it, you get aggregate totals for the entire date range. Daily data is almost always what you want for a warehouse pipeline.

Available fields

The Insights endpoint exposes 70+ fields. The core ones almost every pipeline needs:

The actions and action_values fields return nested JSON arrays rather than flat columns — this is where the primary engineering complexity lives. See Meta Ads Actions Array in BigQuery for the full treatment.

Breakdown restrictions

Not all breakdown combinations work. Some return API errors without clear documentation on which are invalid. The practical rules:

• Off-Meta action metrics (Conversions API events, Pixel events) can’t use regional, hourly, or several action-level breakdowns
• Data with breakdowns is only retained for 13 months (vs. 37 months for aggregate data without breakdowns)
• reach and frequency with breakdowns are retained for only 6 months
• Unique metrics like reach can’t be summed across breakdowns — they’re estimated counts and summing creates artificial inflation from audience overlap

The last point matters for storage design. If you’re requesting daily data with age breakdowns, the total reach across all age groups will exceed actual reach. Store these metrics carefully and document their non-additive nature.

Versioning

Meta releases about two major API versions per year, each supported for roughly two years. As of early 2026:

• v24.0 (current, October 2025)
• v22.0 (minimum supported)
• Anything older than v22.0: deprecated

Legacy Advantage+ Shopping and App Campaign APIs are fully deprecated by May 2026. The deprecation timeline is public, but Meta doesn’t give you a warning in API responses — you need to monitor the deprecation announcements yourself.

The operational implication: pin your pipeline to a specific version and plan upgrades at least six months before end-of-life. An unplanned API version migration is an emergency; a planned one is routine maintenance. The schema change challenge across platforms is particularly acute with Meta due to the quarterly cadence.

Authentication

Token options for production pipelines:

Personal and long-lived user tokens expire after roughly 60 days. When they expire, the pipeline stops silently — there’s no alert, the token just returns auth errors. If you’re not monitoring for this, you’ll discover the expiration when someone asks why the data stopped.

System User tokens don’t expire. Create them in Business Settings under System Users:

1. Create a System User (use Admin role)
2. Grant access to the specific ad accounts the pipeline needs
3. Generate the token with these permissions: ads_read, ads_management, business_management

The permission scope matters. ads_read is the minimum for read-only pipeline access. ads_management is needed if your pipeline writes anything back (most don’t). business_management is needed for business-level objects.

Rate Limits

The Marketing API has its own rate limit system, separate from the standard Graph API. Two tiers:

Read calls cost 1 point; write calls cost 3.

Business Use Case limits scale with account size. For ads_insights at Standard Access (Advanced Access tier):

190,000 + (400 × active_ads) - (0.001 × user_errors) per hour

The user_errors term is important: errors reduce your rate limit budget. A broken pipeline that’s hammering a bad endpoint makes the problem worse. Implement a circuit breaker that pauses extraction after consecutive failures.

Monitor three response headers to stay under limits:

• X-Ad-Account-Usage
• X-Business-Use-Case
• X-FB-Ads-Insights-Throttle

For large date ranges, use async reporting (async=true) instead of synchronous calls. The API submits a reporting job and returns a job ID; you poll for completion. Pair this with exponential backoff on 429 errors.

For Advanced Access (higher rate limits), submit for App Review with a screencast demonstration of your use case. Do this early — the review process takes time and you’ll want the higher limits before you’re depending on them in production.

What to Build vs. Buy

With this API surface, the build-vs-buy calculation for extraction is real. The main options:

• Fivetran: handles versioning, rate limits, lookback windows automatically; starts ~$500/month with native dbt packages
• Airbyte: open-source or cloud, configurable lookback; Advanced Access harder since you share Airbyte’s app credentials
• dlt: verified facebook_ads source with schema evolution; good for Python-native teams
• Custom Python: maximum control, maximum maintenance; you own rate limiting, versioning, pagination, error handling
• BigQuery DTS: free native connector but requires a 60-day refreshed user token — partially defeats the managed appeal

The lookback window is the critical configuration regardless of tool. Meta’s attribution data updates retroactively for 3-7 days. A 28-day lookback is the safe default. See Meta Ads Actions Array in BigQuery for what this means at the transformation layer.