> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Ads

> Query Facebook and Instagram ad performance for a Meta ad account live from Explore and AI agents

The Meta Ads [live data source](https://docs.lightdash.com/integrations/live-data-sources) 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](https://docs.lightdash.com/integrations/live-data-sources#integration-levels) integration: its API returns reports.

## Before you start

* **Live data sources enabled** for your organization. See [Live data sources](https://docs.lightdash.com/integrations/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](https://business.facebook.com/settings/system-users), add a system user and assign it your ad account with **View performance** access.
  2. In [Meta for Developers](https://developers.facebook.com/apps/creation/), 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

1. On the nav bar, click **Browse** → **Semantic Layer**.
2. In the sidebar, select **Live data sources**, then click **Add**.
3. Select **Meta Ads**.
4. Enter a **Name**, such as `Meta Ads`. People see this name in Explore and agents use it to refer to the source.
5. Enter the **Ad account ID** and **Access token**, then click **Test connection**.
6. 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.