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

# Meta Ads (Facebook) setup

Configview reads your Meta Business Manager (the account that owns your Facebook and Instagram ad accounts and Pages) through the **Meta Graph API** (`https://graph.facebook.com/v25.0`: the Marketing API and the Business Management API), using a **system user access token**. Configview sends only `GET` requests. It never creates, changes, pauses or deletes anything in Meta.

You will end up with **2 required secrets** (`META_ADS_ACCESS_TOKEN` and `META_ADS_BUSINESS_ID`) in Configview when setup is complete.

> **Scope of this integration today.** Configview answers "who can spend our Meta ad budget and who else has access": Business Manager users and roles, system users, pending invitations, every owned and client ad account (status, currency, time zone, spend cap, lifetime spend, created date), who is assigned to each ad account and Page and with which tasks, partner agencies and clients, connected apps, campaign names with status and objective, daily account-level spend for the last 30 days, and the ad account activity log. It does **not** read ad creatives, ads or ad sets, audiences, pixels and conversion events, product catalogs, payment methods, invoices, per-ad results or Page posts and messages.

***

## What you need

* A Meta Business Manager and an **admin** of it
* A Meta **business app** (developers.facebook.com) that the business owns, with the **Marketing API** product added. A Business-type app gets Standard Access to `ads_read` automatically.
* A **system user** in Business Settings (an *Employee* system user is enough)

***

## Step 1: Open the Meta Ads page in Configview

Open Configview in a second browser tab and leave it open:

`https://{companyname}.configview.com/admin/integrations/meta-ads`

***

## Step 2: Create the system user and token

1. In Meta **Business Settings > Users > System users**, click **Add** and create a system user with the **Employee** role (not Admin)
2. Click **Add assets** and give it access to every ad account and Page you want Configview to see, with the lowest tasks: **View performance** on ad accounts and **Analyze** on Pages. Partial control is enough; Configview never writes.
3. Click **Generate new token**, choose your business app, and tick only **`ads_read`** and **`business_management`**
4. Choose the longest expiry offered (*Never* if available). Copy the token; it is shown once.
5. Copy the numeric **Business ID** from **Business Settings > Business info**
6. In the Configview tab paste them into `META_ADS_ACCESS_TOKEN` and `META_ADS_BUSINESS_ID` under **Credentials** and save

***

## Step 3: Connect and verify

1. Click **Connect**. Configview creates its tables and schedules every collector at your default run time:

| Script | Notes |
| - | - |
| **Business** | The Business Manager: verification status and whether two-factor is required. |
| **Business users** | Everyone in the business: email, name, title, role. |
| **System users** | Service accounts holding API tokens. |
| **Pending invites** | Invitations not yet accepted. |
| **Ad accounts** | Owned and client ad accounts: status, currency, spend cap, lifetime spend. |
| **Ad account users** | Who is assigned to which ad account, with tasks. |
| **Pages / Page users** | Owned and client Pages and who is assigned to each. |
| **Partner businesses** | Agencies with access and clients you serve. |
| **Connected apps** | Apps the business owns or can use. |
| **Campaigns** | Campaign name, status, objective and dates. |
| **Daily account spend** | Spend, impressions and clicks per ad account per day, last 30 days. |
| **Ad account activity log** | Who changed what, last 30 days. |

2. Click **Verify now**. The health check reads both secrets, then reads your Business Manager.

If a check fails:

* **Graph error 190.** The token expired, was revoked, or a person who generated it left the business. Generate a new one.
* **Graph error 200 or 10.** The token is missing `ads_read` or `business_management`, or the system user has not been assigned to that asset.

***

## Data Tables

Each table has a `run_at` column and keeps only the newest run.

| Table | Source | Key Columns |
| - | - | - |
| `meta_ads_businesses` | `GET /{business-id}` | business\_id, name, verification\_status, two\_factor\_type |
| `meta_ads_business_users` | `GET /{business-id}/business_users` | user\_id, email, name, title, role |
| `meta_ads_system_users` | `GET /{business-id}/system_users` | system\_user\_id, name, role, created\_time |
| `meta_ads_pending_users` | `GET /{business-id}/pending_users` | pending\_id, email, role, status |
| `meta_ads_ad_accounts` | `GET /{business-id}/owned_ad_accounts`, `client_ad_accounts` | relationship, ad\_account\_id, name, account\_status, currency, spend\_cap, spend\_cap\_set, amount\_spent, created\_time |
| `meta_ads_ad_account_users` | `GET /act_{id}/assigned_users` | ad\_account\_id, user\_id, name, tasks |
| `meta_ads_pages` | `GET /{business-id}/owned_pages`, `client_pages` | relationship, page\_id, name, category, verification\_status |
| `meta_ads_page_users` | `GET /{page-id}/assigned_users` | page\_id, user\_id, name, tasks |
| `meta_ads_partner_businesses` | `GET /{business-id}/agencies`, `clients` | relationship, partner\_id, partner\_name, verification\_status |
| `meta_ads_apps` | `GET /{business-id}/owned_apps`, `client_apps` | relationship, app\_id, name |
| `meta_ads_campaigns` | `GET /act_{id}/campaigns` | ad\_account\_id, campaign\_id, name, status, effective\_status, objective |
| `meta_ads_account_daily_spend` | `GET /act_{id}/insights` (level=account) | ad\_account\_id, spend\_date, spend, impressions, clicks |
| `meta_ads_audit_logs` | `GET /act_{id}/activities` | ad\_account\_id, actor\_name, event\_time, event\_type, object\_type, object\_name |

***

## Things worth knowing

**App review.** For a business reading its **own** assets, Standard Access to `ads_read` is enough and needs no App Review. Meta's documentation says the business users list (`business_users`) requires **Advanced Access** to `business_management`, which does need App Review. If that call fails with a permission error, the people list will be empty until Advanced Access is granted (or your app's roles cover it). Everything else works at Standard Access, but Standard Access has lower rate limits.

**Token expiry.** System user tokens can be set to never expire, but Meta also lets an admin revoke them, and they stop working if the app is removed from the business. A token that stops working shows up as Graph error 190 in the health check.

**Money.** `spend_cap` and `amount_spent` are in minor currency units (cents). A `spend_cap` of 0 means no cap. Daily `spend` in the spend table is in the account currency in normal units.

**Account status.** `account_status` is a code: 1 active, 2 disabled, 3 unsettled, 7 pending risk review, 8 pending settlement, 9 in grace period, 100 pending closure, 101 closed. Closed accounts are not queried for users, campaigns or spend.

**Rate limit.** Meta limits calls per ad account over a rolling hour (Standard Access: roughly 300 plus 40 per active ad for management calls, and 600 plus 400 per active ad for insights). Limits are reported as HTTP 400 with error code 4, 17, 32, 613, 80000 or 80004, not 429. Configview paces itself at 30 requests a minute and waits as long as Meta's usage header asks. Per-account collectors make one request per ad account (or Page).

## Known gaps

* Business users' last-active date and two-factor status per person are not collected (not confirmed available)
* Which assets each partner agency can reach, and token metadata (scopes, last used) are not collected
* Page assigned users may need a Page-level permission and are skipped for Pages the token cannot read
* Payment methods, billing and invoices are deliberately not read

## What isn't collected

* Ad creatives, copy, images and videos, ads and ad sets, and landing page URLs
* Audience members and customer lists, pixels and conversion events, product catalogs and lead forms
* Per-ad, per-ad-set and per-campaign performance, and any breakdowns (only account-level daily totals)
* Page posts, comments and messages
* Payment methods, funding sources and invoices
* Access tokens, app secrets and the old and new values inside activity log entries


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