Meta Ads

Meta Ads

This connector reads Facebook and Instagram advertising through the Meta Marketing API (Graph API https://graph.facebook.com/v26.0): ad accounts, campaigns, ad sets, ads, creatives, custom audiences, change history and insights (spend, reach, clicks, conversions) at every level with periods and breakdowns. It can also pause or activate campaigns, ad sets and ads and change budgets. It creates nothing.

Setup (about 10 minutes)

1. Open https://developers.facebook.com/apps/creation/ and create an app with the use case Create & manage ads with Marketing API (connect it to your business portfolio). This adds the permissions ads_read, ads_management and business_management.
2. Recommended, a token that does not expire: in Business Settings (https://business.facebook.com/settings) open Users → System users, add a system user (role Admin, or Employee for read-only), then Assign assets → your ad account (Manage campaigns, or View performance for read-only). Click Generate token, pick the app, choose Never as expiry and tick ads_read (plus ads_management for status and budget changes; business_management helps to list the business's accounts). Meta can ask you to verify the business portfolio (Business Settings → Security Center) before a system user may generate a token; until that is done, use the user token of step 3.
3. Alternative, a user token: the Graph API Explorer (https://developers.facebook.com/tools/explorer/), your app, User Token with ads_read and ads_management. That token lasts one or two hours. Set META_APP_ID and META_APP_SECRET (the app's App settings, Basic) and AnythingMCP exchanges it for a long-lived token (about 60 days) on its first call and renews it once fewer than 10 days remain. Without them, extend it yourself in the Access Token Debugger (https://developers.facebook.com/tools/debug/accesstoken, Extend Access Token) and replace it before the 60 days run out; the connector page warns ahead of time.
4. Paste the token into META_ADS_ACCESS_TOKEN. Put the ad account id into META_ADS_ACCOUNT_ID with the act_ prefix (act_1234567890); Ads Manager shows the number in the address bar (act=1234567890), and meta_ads_list_ad_accounts lists every account the token can reach.
5. Install and run meta_ads_list_ad_accounts.

Access level: a new app has Limited access (formerly Standard), enough for ad accounts of your own business but heavily rate limited. Ad accounts of other businesses need Full access (formerly Advanced) through App Review. Tokens can be checked at https://developers.facebook.com/tools/debug/accesstoken. If the app has Require App Secret switched on (App settings → Advanced), calls without an appsecret_proof are refused; leave it off for this connector.

Changes spend money: confirm first. meta_ads_update_status (ACTIVE starts spending, PAUSED stops delivery) and meta_ads_update_budget act at once. State the object (name and id), the current and the new value, and wait for the user's yes. An ad delivers only when the ad, its ad set and its campaign are all ACTIVE.

Money: budgets, bids, amount_spent, balance and spend_cap are integers in the minor unit of the account currency (2000 = 20.00 EUR); JPY, KRW, HUF, CLP, COP, CRC, IDR, ISK, PYG, TWD and VND have none. In insights, spend, cpc and cpm are already decimal amounts.

Insights

• meta_ads_get_account_insights for the whole account, meta_ads_get_insights for one campaign, ad set or ad.
• Period: date_preset (default last_30d; also yesterday, last_7d, this_month, last_month, maximum and more) or since + until (YYYY-MM-DD, at most 37 months back).
• level gives one row per campaign, ad set or ad (add campaign_name, adset_name or ad_name to fields); time_increment 1 gives daily rows; breakdowns splits by age, gender, country, region, publisher_platform, platform_position, device_platform (only some combinations work).
• actions and cost_per_action_type list conversions by action_type (e.g. link_click, purchase, lead, offsite_conversion.fb_pixel_purchase).
• Attribution defaults to 7-day click and 1-day view; use_unified_attribution_setting true matches Ads Manager. Large requests can fail with code 100, subcode 1487534: shorten the period or drop breakdowns.

Lists and ids: lists return data[] and paging.cursors.after; pass it as after for the next page (no paging.next means the last page). Without effective_status, deleted and archived objects are left out. Ids are long numbers: pass them as strings. Every list and read returns only the fields in fields (each tool has a useful default).

Common errors (in error.code)

• 190: the token is invalid or expired; create a new one. With subcode 467 (logged out), 460 (password changed) or 458 (app removed) the session is over for good: the connector stops sending the token and answers at once until a new one is saved.
• 10, 200 to 299: a permission is missing (294 means ads_management) or the token has no access to this ad account.
• 100: a parameter or field is wrong; error.message names it.
• 4, 17, 613, 80000, 80004: rate limits; wait a few minutes. Limited access is throttled hardest.

Out of scope here: creating or editing campaigns, ad sets, ads, creatives and audiences, uploading media, lead forms, pixels and the Conversions API.