META ADS
Meta Ads API Insights Endpoint — Campaigns Impressions Clicks Spend Leads Complete 2026 Guide
The Meta Ads API insights endpoint campaigns impressions clicks spend leads data extraction system handles 70+ metrics across campaign, ad set, and ad levels. Master breakdowns, date ranges, async reporting, and rate limits for automated performance dashboards that pull real-time data from Facebook and Instagram advertising infrastructure.
Contents
Autonomous Marketing
Grow your business faster with AI agents
- ✓Automates Google, Meta + 5 more platforms
- ✓Handles your SEO end to end
- ✓Upgrades your website to convert better
What is the Meta Ads API insights endpoint?
The Meta Ads API insights endpoint campaigns impressions clicks spend leads system is the reporting backbone of Facebook's Marketing API. Unlike the core API that manages ad creation and targeting, the insights endpoint exclusively handles performance data extraction — pulling metrics like impressions, clicks, spend, conversions, and lead generation data from your Meta advertising campaigns.
This endpoint operates as an "edge" within Meta's Graph API infrastructure, designed for asynchronous reporting at scale. When you request campaign data, Meta processes it in the background and returns structured JSON responses containing up to 70+ different performance metrics. The insights endpoint handles data aggregation across Facebook, Instagram, Messenger, and Audience Network placements — providing unified reporting regardless of where your ads appeared.
According to Meta's official documentation, the insights endpoint processes over 100 billion data points daily from advertisers worldwide. This makes it critical for performance marketers who need real-time visibility into campaign effectiveness, especially when managing budgets exceeding $10K/month where daily optimization can save 15-25% in wasted spend.
The endpoint structure follows a hierarchical model: you can query insights at the ad account level (all campaigns), campaign level (all ad sets within a campaign), ad set level (all ads within an ad set), or individual ad level. This granularity is essential when you need to identify which specific creative, audience, or placement is driving your best results — or worst performance.
1,000+ Marketers Use Ryze
Automating hundreds of agencies
★★★★★4.9/5
How is the insights endpoint structured across campaign levels?
The Meta Ads API insights endpoint follows a hierarchical structure that mirrors your ad account organization. Each level provides different granularity of data, from broad account-wide metrics down to individual ad performance. Understanding this structure is crucial for building efficient queries that pull exactly the data you need without unnecessary API calls.
| Endpoint Level | URL Structure | Data Scope | Best Use Case |
|---|---|---|---|
| Ad Account | /act_{account-id}/insights | All campaigns aggregated | Executive dashboards |
| Campaign | /{campaign-id}/insights | Campaign-specific metrics | Campaign performance analysis |
| Ad Set | /{adset-id}/insights | Audience/targeting metrics | Audience optimization |
| Ad | /{ad-id}/insights | Creative-specific data | Creative testing & fatigue detection |
Account-level insights aggregate data across all active campaigns, making them ideal for high-level reporting and trend analysis. Use this when building executive dashboards or monthly performance reports. The query processes faster since Meta pre-aggregates much of this data.
Campaign-level insights show performance for specific campaigns, which is essential for budget allocation decisions. If you have separate campaigns for prospecting vs. retargeting, campaign-level data helps you understand which strategy drives better ROAS and deserves more budget.
Ad set-level insights reveal how different audiences, placements, or targeting parameters perform. This is where you identify audience fatigue, discover which demographics convert best, and optimize your targeting parameters for lower CPAs.
Ad-level insights show individual creative performance — essential for creative testing and fatigue detection. Since the average Meta ad hits creative fatigue after 3-5 days, ad-level monitoring helps you catch declining CTR and rising frequency before it impacts your overall campaign performance.
What are the 70+ available metrics in the insights endpoint?
The Meta Ads API provides access to 70+ performance metrics through the insights endpoint, organized into six main categories. Understanding which metrics to request is crucial — including unnecessary fields increases API response time and counts against your rate limits. Here are the essential metrics every performance marketer should track:
Delivery & Reach Metrics
Core Delivery
- •
impressions— Total ad displays - •
reach— Unique users reached - •
frequency— Average times per user
Advanced Reach
- •
unique_clicks— Distinct clickers - •
unique_ctr— Unique click-through rate - •
social_spend— Social proof spend
Engagement & Click Metrics
Click Data
- •
clicks— Total clicks (all types) - •
link_clicks— Destination clicks - •
ctr— Click-through rate
Engagement
- •
post_engagement— Total interactions - •
page_engagement— Page interactions - •
engagement_rate— Engagement percentage
Spend & Cost Metrics
Spend Data
- •
spend— Total spend (USD) - •
cpm— Cost per 1,000 impressions - •
cpc— Cost per click
Action Costs
- •
cost_per_action_type— Cost per conversion - •
cost_per_unique_click— Cost per unique clicker - •
cpp— Cost per page like
Conversion & Lead Metrics
Conversion Data
- •
actions— All conversion events - •
action_values— Conversion values - •
conversions— Total conversions
Lead Generation
- •
leads— Lead form submissions - •
cost_per_lead— Cost per lead - •
lead_conversion_rate— Lead conversion %
Pro tip: Always include these core metrics in your API calls: impressions,reach,frequency,clicks,link_clicks,ctr,spend,cpm,cpc,actions,action_values. This combination gives you enough data to calculate ROAS, detect creative fatigue (frequency > 3.0), and identify cost anomalies (CPM spikes).
Ryze AI — Autonomous Marketing
Skip the API calls — let AI pull your Meta data 24/7
- ✓Automates Google, Meta + 5 more platforms
- ✓Handles your SEO end to end
- ✓Upgrades your website to convert better
2,000+
Marketers
$500M+
Ad spend
23
Countries
How to pull campaign impressions, clicks, spend, and leads data?
Extracting campaign data from the Meta Ads API insights endpoint campaigns impressions clicks spend leads requires proper URL construction, field specification, and date range parameters. Here's the step-by-step process for building API calls that return exactly the data you need.
Basic Campaign-Level Query
The simplest campaign insights query pulls basic metrics for a specific date range. Replace {campaign-id} with your actual campaign ID and {access-token} with your valid access token:
This returns 7 days of data with campaign name, impressions, clicks, total spend, and all action types (including leads, purchases, and other conversions).
Lead-Specific Data Extraction
For lead generation campaigns, you need to filter actions to show only lead-related conversions. Meta tracks leads through the lead action type:
The filtering parameter restricts results to lead actions only. Attribution windows specify whether you want 1-day or 7-day post-click conversions.
Multi-Campaign Account Query
To pull data for all campaigns in an ad account, use the account-level endpoint with the level=campaign parameter:
This returns yesterday's performance for up to 100 campaigns. Increase the limit or use pagination for accounts with more campaigns.
Custom Date Ranges
For specific date ranges beyond Meta's presets, use the time_range parameter instead of date_preset:
The time_increment=1 parameter returns daily breakdowns instead of aggregated totals, useful for trend analysis and day-of-week performance patterns.
What breakdowns and filtering options are available?
The insights endpoint supports 20+ breakdown dimensions that segment your impressions, clicks, spend, and leads data by demographics, devices, placements, and time periods. Proper use of breakdowns reveals which audience segments, ad placements, or creative formats drive your best performance.
Demographic Breakdowns
Understanding which age groups, genders, and geographic regions convert best is essential for audience optimization:
This returns data segmented by age groups (18-24, 25-34, etc.), gender (male, female, unknown), and country. Useful for identifying high-value demographic segments.
Device & Placement Breakdowns
Performance varies significantly across mobile vs. desktop and different Meta placements (Feed vs. Stories vs. Reels):
Device platform shows mobile vs. desktop performance. Publisher platform separates Facebook, Instagram, Messenger, and Audience Network. Placement reveals Feed, Stories, Reels, and Search results.
Time-Based Analysis
Hourly and day-of-week breakdowns help optimize ad scheduling and budget allocation:
Returns performance data broken down by hour of day across the specified date range. Identifies peak conversion times for ad scheduling optimization.
Advanced Filtering Examples
Filtering lets you analyze specific subsets of your data without pulling the entire dataset:
How do rate limits affect API usage?
Meta's API enforces multiple rate limit types that can block your insights requests if you exceed thresholds. The insights endpoint is particularly sensitive because it processes large datasets. Understanding these limits is crucial for building reliable automation scripts.
| Rate Limit Type | Limit | Reset Period | Best Practice |
|---|---|---|---|
| Application-level | 200 calls/hour per app | Rolling hour | Space calls 18 seconds apart |
| User-level | 25 calls/hour per user | Rolling hour | Batch requests when possible |
| Ad Account | 5 insights/minute | Per minute | Use async requests for large queries |
| Insights Job | 5 concurrent/account | Concurrent | Queue jobs, don't parallelize |
The 5-insights-per-minute ad account limit is the most restrictive for reporting automation. If you need hourly updates for 10 campaigns, that requires 10 API calls — which takes 2 minutes minimum. Plan automation schedules accordingly.
Async insights jobs help with large data pulls. Instead of waiting for the API response, you submit a job and poll for completion. Useful when pulling 30+ days of data with multiple breakdowns:
Error code 80004 means you've hit rate limits. Your script should catch this error, wait for the specified retry-after period, then resubmit. Most production systems implement exponential backoff: wait 1 minute after first failure, 2 minutes after second, 4 minutes after third, etc.
What automation workflows can you build with insights data?
The insights endpoint enables powerful automation workflows that eliminate manual reporting and catch performance issues before they damage your ROI. Here are five workflows that save 10+ hours per week for busy performance marketers:
Daily Performance Alerting
Pull yesterday's campaign data every morning and compare against 7-day averages. Alert when spend > 150% of normal, CTR < 50% of normal, or CPA > 200% of target. This catches account issues within 24 hours instead of weekly reviews.
Example Alert Logic:
- • If CPM increases > 30% day-over-day → Check for creative fatigue
- • If CTR drops > 20% → Pause ad and test new creative
- • If spend = $0 → Check campaign status and budget
- • If conversions = 0 with > $100 spend → Verify pixel firing
Automated Creative Fatigue Detection
Query ad-level insights with frequency and CTR data. Flag any ad where frequency > 3.0 and CTR declined > 25% from its 7-day peak. Creative fatigue costs advertisers an estimated 20-30% of budget when left unchecked for more than a week.
Implementation Steps:
- • Pull last 14 days of ad-level data with CTR and frequency
- • Calculate peak CTR for each ad in days 1-7
- • Compare current CTR (days 8-14) against peak
- • Flag ads with > 25% decline and frequency > 3.0
- • Export flagged ads to CSV for creative team review
Budget Reallocation Recommendations
Calculate marginal ROAS for each campaign by pulling 30-day insights data. Campaigns with ROAS > target should get more budget. Campaigns with ROAS < 50% of target should be paused or restructured. This analysis typically reveals 15-25% efficiency improvements.
Budget Reallocation Matrix:
- • ROAS > 4.0x → Increase budget by 25-50%
- • ROAS 2.5-4.0x → Maintain current budget
- • ROAS 1.5-2.5x → Decrease budget by 25%
- • ROAS < 1.5x → Pause and restructure
Audience Saturation Monitoring
Track reach and frequency trends by ad set to identify audience saturation before it inflates CPMs. When reach growth plateaus while frequency climbs above 4.0, the audience is saturated and needs expansion or refresh.
Saturation Indicators:
- • Reach growth < 5% week-over-week
- • Frequency > 4.0 with declining CTR
- • CPM increasing > 20% without external factors
- • Impression share > 90% in target demographics
Executive Reporting Automation
Generate weekly executive reports by pulling account-level insights and calculating key KPIs. Format the data into charts and email automatically. This replaces 2-3 hours of manual work with a 5-minute automated process.
Report Components:
- • Total spend, impressions, clicks, conversions
- • Week-over-week percentage changes
- • Top 5 performing campaigns by ROAS
- • Campaign budget utilization percentages
- • Upcoming optimization recommendations
Sarah K.
Paid Media Manager
E-commerce Agency
We went from spending 10 hours a week on bid management to maybe 30 minutes reviewing Ryze's recommendations. Our ROAS went from 2.4x to 4.1x in six weeks."
4.1x
ROAS achieved
6 weeks
Time to result
95%
Less manual work
What are common troubleshooting issues with the insights API?
The Meta Ads API insights endpoint can fail in several ways that aren't immediately obvious. Understanding these common issues saves hours of debugging when your automated reports suddenly stop working or return incomplete data.
Error Code 100: Invalid Parameter
This generic error usually means you've requested an incompatible combination of fields, breakdowns, or date ranges. Common causes include requesting video metrics for non-video campaigns or using breakdowns that don't apply to your campaign objective.
Common Invalid Combinations:
- • Video metrics (video_play_actions) on non-video ads
- • Lead-specific metrics on traffic campaigns
- • Carousel metrics on single-image ads
- • Offline conversion data without proper setup
Error Code 190: Access Token Issues
Access tokens expire after 60 days (long-lived tokens) or when users change passwords. Your automation scripts need token refresh logic to handle expiration gracefully.
Token Management Best Practices:
- • Check token expiry before making API calls
- • Implement automatic token refresh workflows
- • Store refresh tokens securely
- • Log token refresh events for debugging
Error Code 200: Permission Denied
This occurs when your app lacks proper permissions for the requested data. Ad insights require ads_read permission minimum. Conversion data may require additional ads_management permissions.
Empty or Incomplete Data
When API calls succeed but return no data, check these common causes:
- • Date range includes only non-delivery days
- • Campaign was paused during requested period
- • Conversion window extends beyond data availability
- • Attribution settings exclude desired conversion events
- • Account timezone mismatch causing date confusion
Async Job Failures
Large insights requests may fail silently when submitted as async jobs. Always check the job status and error details before assuming the request succeeded:
Meta Graph API ad account insights fields: the /act_<id>/insights call and the four parameters that shape it
Every report on this page is one call: GET https://graph.facebook.com/v21.0/act_<id>/insights. The ad account is the right entry point for reporting because the same request can return account totals, one row per campaign, or one row per ad, depending on level. Leave level out and you get a single aggregated row; set level=campaign, adset or ad and the rows carry the matching ids and names so you can join them to anything else. The Meta Graph API ad account insights fields you ask for go in fields as a comma list, and the list is the same at every level.
The parameters that do the work: date_preset (today, yesterday, last_7d, last_30d, this_month, last_month, maximum) or time_range with explicit since and until; time_increment, where 1 means one row per day, monthly means one per month, and all_days (the default) collapses the range; and breakdowns for age, gender, country, publisher_platform, platform_position and device_platform. Combining a fine time_increment with two breakdowns multiplies the row count fast, which is when the async report path from the rate-limits section above starts to matter.
A field list that covers most dashboards: campaign_name,adset_name,ad_name,impressions,reach,frequency,clicks,inline_link_clicks,ctr,cpc,cpm,spend,actions,action_values,cost_per_action_type,purchase_roas. Note that clicks counts every click on the unit and inline_link_clicks counts the ones that left for your destination, so CTR from the former looks better than it is.
Meta Ads API insights report in Python: a short requests script that pages through results and writes a CSV
You do not need the facebook-business SDK for a Meta Ads API insights report in Python. Plain requests handles it, and the only part people get wrong is pagination: the response carries a paging.next URL that already includes your fields, level, date preset and token, so the loop has to stop passing params after the first request or the query string gets doubled.
Two things to adjust before you run it on a real account. actions and cost_per_action_type come back as lists of objects, one per action_type, so the CSV cell will hold the raw list; flatten the ones you care about (for example lead and purchase) into their own columns before handing the file to anyone in a spreadsheet. And put the token in an environment variable rather than the file, because a long-lived system user token that leaks through a repo is a full read of every account it can see.
Facebook ad account insights and advanced read fields: ads_read versus ads_management, and what App Review actually gates
The permission you need to read insights is ads_read. ads_management includes read access and adds writes (creating campaigns, changing budgets, pausing ads), so a reporting-only integration should ask for ads_read and nothing else; reviewers reject over-scoped apps, and a stolen token with ads_management can spend money. There is no separate list of Facebook ad account insights and advanced read fields. The fields are identical whichever permission you hold. What changes is whose accounts your token is allowed to read.
That is where “advanced access” comes in. An app in development mode, or one with only standard access to ads_read, can read the ad accounts of people who hold a role on the app (admin, developer, tester) and accounts owned by the app’s own business. That covers internal reporting completely: create a system user in Business Manager, assign it the ad accounts, generate a token with ads_read, and you never go through review. Advanced access for ads_read or ads_management is required the moment you read accounts belonging to people outside the app, which is every agency dashboard and every SaaS reporting product. That path means App Review plus business verification for the company that owns the app, and it can take weeks.
Meta Marketing API insights official documentation for spend, actions and cost_per_action_type, and how to read the arrays
spend is a plain string number in the ad account currency. actions and cost_per_action_type are arrays of objects, each with an action_type and a value; add action_attribution_windows to the request and every object also carries keys like 1d_click and 7d_click so you can see which window produced the number. Cost per lead is not a separate metric in the response: it is the object in cost_per_action_type whose action_type is lead. The v19 field names for ctr and cost_per_action_type are unchanged in later versions, so a Facebook Ads API v19 insights query for CTR and cost per lead runs as-is against v21 with the version number swapped.
The action_type keys that matter for most accounts, and the trap in them: lead is the combined total; onsite_conversion.lead_grouped is instant-form leads captured on Facebook and Instagram; offsite_conversion.fb_pixel_lead is the website Lead event from the pixel or Conversions API. Summing all three double counts. The same pattern applies to purchases (purchase and omni_purchase versus offsite_conversion.fb_pixel_purchase).
The Meta Marketing API insights official documentation is the place to confirm any of this before you build on it, since action types change between versions: the Insights API overview, the ad account insights reference for level, breakdowns and date handling, and the AdsActionStats reference for the full action_type list and the attribution keys.
Frequently asked questions
Q: How often can I pull insights data from Meta Ads API?
The insights endpoint has a limit of 5 requests per minute per ad account. For accounts with multiple campaigns, use account-level queries with level=campaign to get all data in one call. Large data requests should use async jobs.
Q: What's the difference between clicks and link_clicks in Meta insights?
'Clicks' includes all clicks on your ad (likes, comments, shares, profile clicks). 'Link_clicks' only counts clicks that send users to your website/landing page. For traffic campaigns, use link_clicks for accurate performance measurement.
Q: How far back can I retrieve historical insights data?
Meta stores insights data for 37 months. However, some metrics like detailed breakdowns may only be available for the last 12 months. Always pull and store important data locally for unlimited historical access.
Q: Why do insights numbers differ from Ads Manager?
Differences occur due to attribution windows, timezone settings, or data processing delays. API data uses advertiser timezone while Ads Manager may show user timezone. Ensure consistent attribution windows and timezone parameters.
Q: Can I get real-time insights data through the API?
Insights data typically has a 15-30 minute delay from actual ad delivery. For near real-time monitoring, query hourly or use yesterday's complete data for daily reports. Async jobs provide the most current available data.
Q: How do I track lead generation specifically through insights API?
Filter the 'actions' field for action_type='lead' or use the dedicated 'leads' field. Include action_values to get lead value data. For lead ads, also track 'cost_per_lead' and 'lead_conversion_rate' metrics.
Ryze AI — Autonomous Marketing
Skip the API complexity — get automated Meta insights
- ✓Automates Google, Meta + 5 more platforms
- ✓Handles your SEO end to end
- ✓Upgrades your website to convert better
2,000+
Marketers
$500M+
Ad spend
23
Countries
