How do I pull Meta ads data from the API for a report?

Create a Meta developer app with the Marketing API product, get a token with ads_read, then call GET /act_ /insights with a level, fields and a time_range. For large pulls, start an async job with POST and read the results from the report_run_id.

Meta Marketing API Insights: Pull Ads Data for Reports

Last updated: October 2026. Checked against Marketing API v26.0.

TL;DR

The Meta Marketing API Insights endpoint, often called the Ads Insights API, is the read side of the Meta ads API. It returns performance rows for an ad account, campaign, ad set or ad through GET /{object-id}/insights, needs the ads_read permission, and defaults to the last 30 days. The limit that shapes every reporting build is rate limiting, which Meta applies at the ad account level, so one heavy pull can throttle that account.

Quick answer

You call /act_<AD_ACCOUNT_ID>/insights or the /insights edge of a campaign, ad set or ad, and the level parameter sets how granular the rows are.
Each request combines parameters (dates, level, attribution windows), fields (the metrics) and breakdowns (the segments).
Without dates, Meta uses last_30d and returns one row for the whole period.
Rate limits are scored per ad account, with a ceiling of 60 points on Limited access and 9,000 on Full access.
Large or slow reports should run as async jobs, which Meta says can take up to an hour.

This guide is for technical marketers and developers who want the numbers behind a Meta ads report straight from the source. It covers the data interface, meaning where the report gets its numbers. For the workflow that turns those numbers into a weekly report with AI, see our guide to AI Facebook ads reporting.

Drowning in Meta Ads?

Let Nova run your campaigns, approval-first.

What is the Meta Marketing API Insights endpoint?

The Insights endpoint is the part of Meta's Marketing API that reads aggregated ad performance: spend, impressions, clicks, conversions, video metrics and delivery data. It does not change anything in the account. Meta's permissions reference describes ads_read as the permission that "allows your app to access the Ads Insights API to pull Ads report information" for ad accounts you own or have been granted access to (Meta for Developers, Permissions Reference).

It is often confused with the Conversions API because both sit under the Marketing API. They move data in opposite directions.

Aspect	Conversions API (CAPI)	Ads Insights API
Direction	Writes events to Meta	Reads performance from Meta
Typical data	Server-side purchases, leads, add-to-carts	Spend, impressions, clicks, actions, action values
Who builds it	Engineering or tracking teams	Analysts, BI tools, reporting pipelines
How they relate	Sends server-side events that Meta may match and attribute, alongside the Pixel and other signals	Returns aggregated delivery data and attributed results under the selected reporting settings

If conversion counts look unexpectedly low, check event ingestion first, then compare attribution settings, date range, time zone, filters and reporting latency. Our Meta Conversions API guide covers the ingestion side.

Facebook Ads API getting started: what do you need before the first call?

To call the raw Facebook Ads API (now the Meta Marketing API) you need three things:

A Meta developer app with the Marketing API product added. Meta says apps start on development access by default (Meta for Developers, Marketing API Rate Limiting).
An access token for a user or system user with access to the ad account.
The ads_read permission on that token. Writes need ads_management, which Meta describes as allowing your app "to both read and manage" the ad account (Meta for Developers, Permissions Reference).

Meta has renamed its access tiers, and its docs still use both naming systems, so this map helps when reading them:

Older technical label	Current Marketing API Access Tier label	Max score	Block when the score is hit
Development (development_access)	Limited access	60	300 seconds
Standard (standard_access)	Full access	9,000	60 seconds

Source: Meta for Developers, Marketing API Rate Limiting. In App Review, Limited and Full access were previously called Standard Access and Advanced Access, so older guides may use those names.

Meta's same page lists the upgrade requirement for Full access as 500 or more Marketing API calls in the past 15 days with an error rate below 15 percent over the last 500 calls. Our guide to Meta App Review for MCP explains who needs App Review and what the upgrade involves.

How do you make a Meta Marketing API Insights request?

Here is a minimal, copyable request that most reporting builds start from: ad-level rows, daily, for September 2026.

# Load the token from your secrets store or .env file,
# so it is not pasted into every command.
export META_ACCESS_TOKEN="<ACCESS_TOKEN>"

curl -G "https://graph.facebook.com/v26.0/act_<AD_ACCOUNT_ID>/insights" \
  --data-urlencode "level=ad" \
  --data-urlencode "fields=campaign_name,adset_name,ad_name,spend,impressions,clicks,ctr,cpm,actions,action_values" \
  --data-urlencode 'time_range={"since":"2026-09-01","until":"2026-09-30"}' \
  --data-urlencode "time_increment=1" \
  --data-urlencode "access_token=${META_ACCESS_TOKEN}"

bash

Meta's own examples pass the token as the access_token query parameter (Meta for Developers, Graph API Overview), so the token ends up in the request URL. Keep request URLs out of logs, tickets and chat.

Every Insights request is built from the same three parts.

1. Parameters decide which rows you get. level sets the grain (account, campaign, adset or ad). time_range takes explicit dates, and date_preset takes named ranges like last_7d or this_month. If you send neither, Meta's reference lists last_30d as the default for date_preset, and all_days as the default for time_increment, which returns one row for the whole period (Meta for Developers, Ad Account Insights reference). time_increment=1 returns daily rows. action_attribution_windows controls which conversion windows come back.

2. fields decides which metrics you get. Ask only for what the report uses. actions and action_values come back as lists of objects, each tagged with an action_type, so a purchase count sits inside actions rather than in its own column.

3. breakdowns decides how each row is segmented, for example breakdowns=age,gender or breakdowns=publisher_platform. The breakdowns section below covers where this goes wrong.

Pin the API version. The example uses v26.0, which Meta released on July 29, 2026 (Meta for Developers blog). Put the version in every call, store it with the report data, and test before upgrading. We log version changes in our Meta ads updates log.

Which level should you query in the Meta Marketing API Insights endpoint?

Pick the level that matches the decision the report supports. Querying a parent with a lower level (for example the account with level=ad) returns one row per child and handles the aggregation for you (Meta for Developers, Insights API).

Level	Call	Best for	Watch out for
account	act_<ID>/insights?level=account	Total spend, blended CPA and ROAS, daily trend lines	Hides which campaign moved the number
campaign	?level=campaign	Objective-level reporting, budget pacing	Campaigns with different objectives do not share a conversion event
adset	?level=adset	Audience, placement and budget tests	The ad set's attribution setting drives the reported conversion value
ad	?level=ad	Creative performance and CPA per ad	Most rows per call; large accounts tend to need async jobs

One trap: Meta says stats for deleted or archived ads appear when you query their parents, but once you add filtering, status filtering defaults to active objects only (Meta for Developers, Insights API). A filtered ad-level pull can therefore come back lower than the campaign total for the same dates. To include those ads, add the extra filtering parameter Meta documents, or filter on ad.effective_status.

Why do breakdowns make Meta Insights totals disagree?

Additive metrics such as spend, impressions and clicks should roughly add up across breakdown rows. Unique metrics such as reach and frequency do not. This is the most common double-counting mistake in Meta ads API reporting.

The reason is how reach is counted. Reach is deduplicated people. A person who saw your ad on both Facebook and Instagram counts once in the campaign's reach but appears once in each row of a publisher_platform breakdown. Sum those rows and that person is counted twice. Frequency inherits the problem because it is impressions divided by reach.

Expert note

Never use one API pull for both additive metrics and unique-person metrics when breakdowns are involved. Pull spend, impressions and clicks by segment, and pull reach and frequency separately at the level you report them.

Other breakdown behavior to plan for, all from Meta for Developers, Insights Breakdowns:

Hourly breakdowns zero out reach. reach and frequency return 0 when hourly breakdowns are in use.
Some breakdowns need opt-in. For impression_device, frequency_value and hourly_stats_aggregated_by_audience_time_zone, Meta says the account administrator can opt in via Ads Manager. Without that, expect empty results.
Some fields refuse breakdowns entirely, including app_store_clicks, newsfeed_clicks and newsfeed_impressions.
Not every combination works. Meta publishes a matrix of which breakdowns can be combined, so check it before assuming four breakdowns will run together.

How do Meta Marketing API rate limits work?

For reporting pipelines, the two limits that usually matter most are a short-term score per ad account and an hourly Business Use Case budget per ad account. We call this the two-meter model. It is not the only limit: Meta also rate-limits the Ads Insights platform at the application level, and when that happens "all Ads Insights API calls for the app are limited" (Meta for Developers, Marketing API Rate Limiting). Marketing API requests fall under Business Use Case limits rather than the general Graph API platform limits, and a single request that lists several object IDs still counts each ID as one API call (Meta for Developers, Graph API Rate Limiting).

Aspect	Meter 1: score	Meter 2: hourly Business Use Case budget
Scope	Per ad account ("Rate limiting is at the ad account level")	Per ad account, per one-hour period
Limited access (Development)	Max score 60, blocked 300 s when reached	ads_insights: 600 + 400 × active ads − 0.001 × user errors; ads_management: 300 + 40 × active ads
Full access (Standard)	Max score 9,000, blocked 60 s when reached	ads_insights: 190,000 + 400 × active ads − 0.001 × user errors; ads_management: 100,000 + 40 × active ads
Cost	Read call = 1 point, write call = 3 points	Points consumed per call against the hourly budget
Recovery	Score decays over 300 seconds	estimated_time_to_regain_access in the usage header

Source for every figure in this table: Meta for Developers, Marketing API Rate Limiting, checked October 2026.

What are the Meta Marketing API free tier limitations?

Meta's documentation describes access tiers, not paid plans, so the Meta Marketing API free tier usually means Limited access. With reads at 1 point against a ceiling of 60, a burst of around 60 calls at one ad account can trigger a 300-second block. In practice, small accounts on Limited access tend to hit this score long before the hourly ads_insights budget.

Which usage header should you read?

Header	What it tells you
X-Business-Use-Case-Usage	call_count, total_cputime and total_time as percentages of the hourly budget, plus estimated_time_to_regain_access in minutes
X-Ad-Account-Usage	Ad-account utilization, reset time and access tier
X-FB-Ads-Insights-Throttle	Insights-specific app and account utilization

Sources: Meta, Graph API Rate Limiting for the first header and Meta, Marketing API Rate Limiting for the other two.

Practical recommendation: when a call is throttled, match the error code to its limit in the troubleshooting table below, read that header, then decide between waiting, shrinking the request or upgrading the tier. A common practitioner heuristic, not a Meta figure, is to slow down once call_count passes about 75 percent.

When should you use sync or async Insights reports?

Use a synchronous GET for small, bounded reports, and an asynchronous job once a request times out or grows large. Meta notes that GET requests can fail with out-of-memory or timeout errors, and its guidance for the timeout error 100 / 1504018 is to "try a smaller date range, fetch less data, or use async jobs" (Meta for Developers, Ads Insights API Error Codes).

An async report runs in three steps:

Start the job. Send the same parameters as a POST to /act_<AD_ACCOUNT_ID>/insights. The response contains a report_run_id.
Poll the job. Request /<REPORT_RUN_ID> and read async_status and async_percent_completion until the status reads Job Completed and completion reaches 100 (Meta for Developers, Insights Best Practices), with backoff between polls. Meta says async requests can take up to an hour including retries (Meta for Developers, Insights API).
Read and page the results. Request /<REPORT_RUN_ID>/insights and follow the paging cursors (after, or the next URL) until no further page comes back.

Practical recommendation: in most reporting pipelines, one async job per account, date range and breakdown set is the easiest pattern to debug and retry.

Why did my Meta Insights request fail?

Start from the symptom, then match it to the cause.

Symptom or error	Likely cause	First action
2 / 1504041 Invalid Breakdowns	Unsupported metric and breakdown combination	Remove one breakdown and check Meta's combination matrix
100 / 1504018 or 2 / 1504038 timeout, or an out-of-memory error	Too much data in one synchronous request	Shorten the date range, drop fields, or switch to async
-3 / 1504045 Report Too Large	The async job itself is too big	Split the job, usually by date range
4 / 1504022 or 4 / 1504039	Ads Insights app-level limit	Wait, then reduce call volume across the app
17 / 2446079 or 613 / 1487742	User or ad-account call limit reached	Read X-Ad-Account-Usage and wait for the reset
80000, 80003, 80004 or 80014	Business Use Case budget exhausted (meter 2)	Read X-Business-Use-Case-Usage and wait for estimated_time_to_regain_access
100 / 3191001 Permission Error	Token lacks access or permission	Check ads_read and the user's role on the ad account
Totals do not match Ads Manager	Attribution setting, filters, time zone or status scope differ	Compare request settings with the Ads Manager view
Reach does not add up	Unique people appear in several breakdown rows	Pull reach separately, without the breakdown

Sources: Meta, Ads Insights API Error Codes and Meta, Marketing API Rate Limiting.

How do attribution windows work in the Insights API?

The action_attribution_windows parameter sets which click and view windows come back with each action, for example ["7d_click","1d_view"]. Meta documents two rules that are easy to conflate (Meta for Developers, Insights API):

The fallback. "If you do not provide action_attribution_windows we use 7d_click and provide it under value."
Ads Manager parity. Since June 10, 2025, to reduce discrepancies with Ads Manager, attributed values are based on ad-set-level attribution settings, and actions use mixed reporting time: impression time for on-Meta actions such as link clicks, conversion time for off-Meta actions such as web purchases.

If your API numbers disagree with Ads Manager, compare the ad sets' attribution settings and the windows you requested first. Meta has also retired the longer view-through windows, so 1d_view is the view window to request.

For what each window means, see AdAdvisor's attribution window definition. For why Meta and GA4 disagree and which number to use for which decision, see our Meta ads attribution guide. The view-window retirement and what it does to old scheduled pulls are covered in our AI Facebook ads reporting guide.

When should you use an MCP server instead of the raw API?

If you want answers about your account rather than a data pipeline, you may not need to build against the Ads Insights API at all. An MCP server wraps the same Marketing API endpoints so Claude, ChatGPT or Cursor can call them as tools. Our Facebook Ads MCP guide explains how this works, and our ranking of the best Meta Ads MCP servers compares the official server with third-party options.

MCP servers still inherit Meta's rate limits and permission model; they take the app, token and retry work off your plate. AdAdvisor MCP, for example, connects through Meta's approved Marketing API pathway and reads your AOV, break-even ROAS and target CPL when you connect, so answers come back against your own targets instead of raw columns. The raw API remains the better fit when you need a warehouse table, a custom dashboard or full control over every field.

Frequently asked questions

Create a Meta developer app with the Marketing API product, get a token with ads_read, then call GET /act_<AD_ACCOUNT_ID>/insights with a level, fields and a time_range. For large pulls, start an async job with POST and read the results from the report_run_id.

Meta scores calls per ad account: up to 60 points on Limited access or 9,000 on Full access, with reads costing 1 point and writes 3, decaying over 300 seconds. An hourly Business Use Case budget per ad account sits on top, and Ads Insights also has an app-level limit. The X-Business-Use-Case-Usage header shows your hourly usage.

The Conversions API sends server-side events such as purchases and leads to Meta. The Ads Insights API reads aggregated delivery data and attributed results out of Meta. Many setups use both: CAPI on the tracking side, Insights on the reporting side.

Yes, for the raw API: an app, an access token and ads_read, even for an account you own. New apps start on Limited access, which is usually enough to read your own account at low volume. A hosted MCP server or connector can handle the app and token for you, on the same permission model.

Generally up to about 37 months. Meta's Ad Account Insights reference says date_preset=maximum "returns a maximum of 37 months of data" and replaced the old lifetime preset in Graph API v10.0. Some fields and breakdowns may have shorter history, so test the oldest date range your backfill needs with the exact fields and breakdowns you plan to use.

Use sync GET requests for small, recent, lightly broken-down reports. Switch to async jobs for ad-level, account-wide or multi-month pulls, or as soon as you see timeouts. Async jobs can take up to an hour but tend to fail far less often on large queries.

Reach counts unique people, and one person can appear in several placement, platform, device or impression-time rows, so summing those rows counts them more than once. Pull reach and frequency without breakdowns. With hourly breakdowns, Meta returns 0 for reach.

Summary

The Meta Marketing API Insights endpoint is Meta's primary programmatic source for aggregated ad performance data. A working request combines parameters, fields and breakdowns, defaults to the last 30 days, and should pin an API version. Keep reach and frequency out of breakdown sums, plan around the two-meter model of rate limits, and move large pulls to async jobs. When you want answers rather than a pipeline, an MCP server on the same API is likely the faster route. AdAdvisor brings more than 8 years in media buying, over $60M in managed ad spend and an ex-Meta engineer on the team to that layer.

Connect your Meta account to AdAdvisor MCP

Sources

Meta for Developers, Insights API
Meta for Developers, Ad Account Insights reference
Meta for Developers, Insights Breakdowns
Meta for Developers, Marketing API Rate Limiting
Meta for Developers, Graph API Rate Limiting
Meta for Developers, Ads Insights API Error Codes
Meta for Developers, Permissions Reference
Meta for Developers, Graph API Overview
Meta for Developers blog, Introducing Graph API v26 and Marketing API v26 (July 29, 2026)
Meta for Developers, Graph API Ad Account Insights reference (37-month maximum preset)
Meta for Developers, Insights Best Practices (async jobs)

AI & Automation

Facebook Ads MCP: The Complete Guide (2026)

A complete guide to the Facebook Ads MCP: what it is, the official Meta server versus third-party options, how to connect AI to your ad account, and where to fix errors.

Analytics & Reporting

AI Facebook Ads Reporting: Automate Your Reports (2026)

How to automate a recurring Facebook ads report with AI without shipping wrong numbers: a six-block report skeleton, the Lock-Then-Narrate workflow, a QA checklist and a worked example.

AI & Automation

Best Meta Ads MCP Servers in 2026: Ranked and Compared

Compare the best Meta Ads MCP servers in 2026, including Meta's official MCP (launched April 2026), AdAdvisor, Pipeboard, Ryze, and more. Find the right one for your workflow.

Meta Marketing API Insights: How to Pull Ads Data for Reporting

TL;DR

Drowning in Meta Ads?

What is the Meta Marketing API Insights endpoint?

Facebook Ads API getting started: what do you need before the first call?

How do you make a Meta Marketing API Insights request?

Which level should you query in the Meta Marketing API Insights endpoint?

Why do breakdowns make Meta Insights totals disagree?

Expert note

How do Meta Marketing API rate limits work?

What are the Meta Marketing API free tier limitations?

Which usage header should you read?

When should you use sync or async Insights reports?

Why did my Meta Insights request fail?

How do attribution windows work in the Insights API?

When should you use an MCP server instead of the raw API?

Frequently asked questions

Summary

Sources

Facebook Ads MCP: The Complete Guide (2026)

AI Facebook Ads Reporting: Automate Your Reports (2026)

Best Meta Ads MCP Servers in 2026: Ranked and Compared

Tarek Kekhia

Related from the desk

Meta's Native Multi-Touch Attribution Tool Is Gone: What to Use Instead (2026)

AI Incrementality Testing for Meta Ads: How to Measure True Lift (2026)

AI Facebook Ads Reporting: Automate Your Reports (2026)