ads_read or ads_management; writes and managed ad-account webhooks use ads_management; Business portfolio inventory also uses business_management. Lead reads use ads_management, leads_retrieval, pages_manage_ads, pages_show_list, and pages_read_engagement; managed lead webhooks also use pages_manage_metadata.
Meta grants Limited Access to development apps. Production use and access to assets owned by another business generally require Business Verification, App Review, and Advanced Access for each permission. Verify access with disposable business, ad-account, Page, pixel, and lead-form resources before relying on a workflow.
The integration pins Graph and Marketing API v26.0. Version upgrades are explicit Automate.ax releases. API failures throw MetaAdsApiError with the HTTP status, Meta code and subcode, transient marker, trace ID, retry delay, and raw app, ad-account, and business-use-case usage headers. Back off when Meta reports quota pressure.
Managed triggers configure the app-level ad_account or page Webhooks subscription, attach the selected ad account or Page to the app, validate Meta’s GET challenge, and verify X-Hub-Signature-256 against the exact request body. Status-change events announce a change; read the object to obtain its current status. Filtered subscriptions events require a provider subscription created through the subscription actions.
Use getMetaAdsApi(account) inside a custom account-backed action for an uncovered Graph edge. Paths remain under https://graph.facebook.com/v26.0/, query and body keys use public camel case, nested bodies are converted to Meta wire keys, and every response requires a Zod schema. This is an authenticated helper, not a generic packaged action.
See Meta’s Marketing API authorization, Graph API versioning, Ads Webhooks, Lead Ads retrieval, and Conversions API.