Meta Ads - Lightdash

The Meta Ads live data source reads one Meta ad account. Lightdash turns each query into a Marketing API Insights request and shows the results Meta returns. Ad data stays in Meta. It’s a level 3 integration: its API returns reports.

Before you start

Live data sources enabled for your organization. See Live data sources.
Admin role in the Lightdash project.
Your ad account ID: the number after act= in your Ads Manager URL.
A system user access token with only the ads_read permission. To create one:
1. In Meta Business settings, add a system user and assign it your ad account with View performance access.
2. In Meta for Developers, create a Business app in the same business portfolio and add the Marketing API product.
3. On the system user, click Generate new token, choose the app, select ads_read, and set the token to never expire.

Connect Meta Ads

On the nav bar, click Browse → Semantic Layer.
In the sidebar, select Live data sources, then click Add.
Select Meta Ads.
Enter a Name, such as Meta Ads. People see this name in Explore and agents use it to refer to the source.
Enter the Ad account ID and Access token, then click Test connection.
Click Add source.

Lightdash adds an Insights table to Explore.

Dimensions

Dimension	Notes
Date, Date month	In the ad account’s time zone
Campaign ID, Campaign name, Campaign objective
Ad set ID, Ad set name
Ad ID, Ad name
Age, Gender	Can be used together
Country, Region	One at a time
Platform, Placement	Add Platform whenever you add Placement

Age and gender, location, and placement can’t be combined in one query. Meta doesn’t report those breakdowns together.

Metrics

Metric	Notes
Spend	In the ad account’s currency
Impressions, Clicks (all), Link clicks
Reach, Frequency	Deduplicated by Meta for each row, so don’t add rows together
Click-through rate (all), Cost per click (all), Cost per 1,000 impressions
Purchases, Purchase value, Purchase ROAS
Leads, Landing page views, Adds to cart, Checkouts initiated, Registrations completed

Conversion metrics use Meta’s default attribution: 7-day click and 1-day view. This can differ from an ad set’s own attribution setting, so numbers can differ from Ads Manager. A blank value means Meta reported nothing for that row.

Supported features

Feature	Available
Filters on campaign, ad set and ad names and IDs	Yes
Filters on age, gender, location, platform or placement	No
Filters on metrics	No
OR filters and nested filter groups	No
Table calculations, custom metrics and custom dimensions	No
Period-over-period comparisons, pivots and date zoom	No

To filter by a campaign, ad set or ad, include that field or a finer one in the query. For example, add Campaign name before you filter by it.

Limits

Limit	Value
Default date range	Last 30 days, when the query has no filter on Date
History	37 months. Reach and frequency with a breakdown: 13 months
Most rows per query	5,000
Timeout	60 seconds per request
Queries at once	3 per source
Calls per minute	60 per source
Calls per hour	1,000 per source

When a query has more than 5,000 rows, Lightdash shows an error rather than a partial result. Narrow the date range, add a filter or remove a dimension.

Example questions

“Spend and purchases by campaign over the last 30 days.”
“Top 10 ads by spend this month.”
“Impressions and link clicks by age and gender last week.”

Troubleshooting

Meta rejected the access token. Generate a new system user token with ads_read and update the source. Meta denied access to the ad account. Check that the system user is assigned to this ad account and that the token includes ads_read. Numbers don’t match Ads Manager. Check the date range and time zone first. For conversions, compare against the 7-day click and 1-day view attribution setting in Ads Manager.

​Before you start

​Connect Meta Ads

​Dimensions

​Metrics

​Supported features

​Limits

​Example questions

​Troubleshooting