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:
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
