Facebook Ads (Meta) Connector Reference

The attribution window for the actions. For example, 28d_click means the API returns all actions that happened 28 days after someone clicked on the ad. The 'default' option means ["7d_click","1d_view"]. Relates to action_attribution_windows parameter in Facebook Insights API.

When this parameter is set to true, your ads results will be shown using unified attribution settings defined at ad set level and parameter use_account_attribution_setting will be ignored.

Filter the ad account activity (change history) log by category. Only applies to Activities fields. When empty, activities of all categories are returned.

When set to true, the ad account activity (change history) log also includes activities of child objects. Only applies to Activities fields.

When enabled, the response also includes campaigns, ad sets or ads (whichever level the query resolves to) that existed in the account but had no insights (impressions/spend) in the requested date range. These rows carry the requested identifier, name and status fields; metric fields are null.

Activate a paused Meta Ads campaign (Facebook or Instagram). Reversible via pause_campaign.

Pause an active Meta Ads campaign (Facebook or Instagram). Reversible via enable_campaign.

Activate a paused Meta Ads ad set (Facebook or Instagram). Reversible via pause_adset.

Pause an active Meta Ads ad set (Facebook or Instagram). Reversible via enable_adset.

Activate a paused Meta Ads ad (Facebook or Instagram). Reversible via pause_ad.

Pause an active Meta Ads ad (Facebook or Instagram). Reversible via enable_ad.

Set the daily or lifetime budget of a Meta Ads campaign (Facebook or Instagram). The amount is in the account currency minor unit (e.g. cents: 5000 means 50.00). Only one budget type applies at a time; setting one replaces the other. Meta rejects frequent budget changes on the same campaign; space out repeated changes instead of adjusting in rapid succession.

Set the daily or lifetime budget of a Meta Ads ad set (Facebook or Instagram). The amount is in the account currency minor unit (e.g. cents: 5000 means 50.00). Only one budget type applies at a time; setting one replaces the other. Meta allows at most 4 budget changes per ad set per hour; further changes are rejected until the hour passes.

Set or update the automated welcome message (greeting / ice breaker) shown when a user opens the conversation from a Meta Ads Click-to-Message ad (Messenger or Instagram, OUTCOME_ENGAGEMENT / CONVERSATIONS). The welcome message lives on the ad creative, which Meta treats as immutable, so this builds a new creative that copies the ad's existing creative and only swaps the welcome message, then re-points the ad at it. Provide ad_id plus either welcome_message (plain greeting text, the common case) or welcome_message_spec (a full page_welcome_message structure for ice breakers / quick replies), not both. The change is verified by reading the new creative back; the action fails if Meta did not persist the value.

Create a new Meta Ads campaign (Facebook or Instagram). Created paused by default so it does not spend until enabled. objective is a Meta campaign objective (e.g. OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_SALES). special_ad_categories must list any regulated categories the ads fall under (e.g. HOUSING, EMPLOYMENT, CREDIT) or be empty. Setting a campaign budget enables campaign budget optimization; amounts are in the account currency minor unit (e.g. cents: 5000 means 50.00). Provide at most one of daily_budget or lifetime_budget. When no campaign budget is set, some accounts require is_adset_budget_sharing_enabled to be specified.

Create a new ad set in an existing Meta Ads campaign (Facebook or Instagram). Created paused by default so it does not spend until enabled. Budget amounts are in the account currency minor unit (e.g. cents: 5000 means 50.00). Provide at most one of daily_budget or lifetime_budget; omit both only when the campaign uses campaign budget optimization. lifetime_budget requires end_time. Some optimization goals require promoted_object, a Meta spec naming what is optimized (e.g. {"pixel_id": "<id>", "custom_event_type": "PURCHASE"} for conversions, or {"page_id": "<id>"} for page likes). destination_type sets where the ad sends people; for boosting an existing post (boost_post) use ON_POST with optimization_goal POST_ENGAGEMENT to keep engagement on the post (no call to action needed). A website or undefined destination instead makes Meta require a website URL and call to action in the creative.

Create a new ad in an existing Meta Ads ad set (Facebook or Instagram). Created paused by default so it does not spend until enabled. The simplest way is to provide page_id and link plus optional text (message, headline, description), image_url and call_to_action_type; these build a single-image link ad creative automatically. For a Click-to-Message ad, set messaging_destination (MESSENGER or INSTAGRAM_DIRECT) instead of link; the message opens a conversation with the page. For a video ad, upload the video first with create_ad_video and pass its video_id here with page_id and a required thumbnail image_url; message becomes the primary text, headline the title, description the caption, and call_to_action_type (with link) adds a button. For advanced cases, pass a full Meta creative spec via creative instead (e.g. {"creative_id": "<id>"} to reuse an existing creative, or {"object_story_spec": {...}}). Provide either the individual creative fields or creative, not both.

Upload a video to a Meta Ads ad account from a public URL so it can be used in a video ad. Meta fetches the file from video_url and transcodes it; the action waits until the video is ready and returns its video_id. Pass that video_id to create_ad together with page_id and a thumbnail image_url to build the video ad. The upload cannot be undone via an action.

Boost (promote) an existing organic Facebook or Instagram post by creating a paid ad for it in an existing Meta Ads ad set. Provide the full post id (in '{page_id}_{post_id}' form, as it appears in the connector data) and the ad set to place the ad in. The ad reuses the published post as its creative via object_story_id, so no new copy or media is created. The target ad set MUST belong to an engagement campaign (objective OUTCOME_ENGAGEMENT) and name the post's page in its promoted_object; build it with create_campaign and create_adset first if needed. Two ad set shapes work: an ON_POST destination with optimization_goal POST_ENGAGEMENT (engagement on the post itself, no call-to-action needed), or a FACEBOOK_PAGE destination with optimization_goal PROFILE_AND_PAGE_ENGAGEMENT, which additionally requires a call-to-action button on the ad — pass call_to_action_type (e.g. VISIT_PROFILE) for that case, otherwise Meta rejects the ad with a 'call-to-action required' error. The page promoted by the ad set and the post's page must match, and the access token must have ads permission on that page. Created paused by default so it does not spend until enabled; use enable_ad to activate it.

Update editable attributes of a Meta Ads campaign (Facebook or Instagram). Provide only the fields to change; at least one is required. spend_cap is a lifetime spend limit in the account currency minor unit (e.g. cents: 5000 means 50.00). special_ad_categories lists the regulated categories the ads fall under (e.g. HOUSING, EMPLOYMENT, CREDIT) or is empty. Use pause_campaign/enable_campaign to change status and set_campaign_budget to change the budget. objective is fixed at creation and cannot be updated.

Update editable attributes of a Meta Ads ad set (Facebook or Instagram). Provide only the fields to change; at least one is required. bid_amount is in the account currency minor unit (e.g. cents: 500 means 5.00). Switching bid_strategy to a capped strategy (LOWEST_COST_WITH_BID_CAP or COST_CAP) requires bid_amount in the same call. end_time is an ISO 8601 timestamp less than one year ahead (e.g. 2027-01-01T00:00:00-0800). Use pause_adset/enable_adset to change status and set_adset_budget to change the budget.

Update editable attributes of a Meta Ads ad (Facebook or Instagram). Provide only the fields to change; at least one is required. creative swaps the ad to a different creative and is a Meta creative reference (e.g. {"creative_id": "<id>"}). conversion_domain is the registrable domain the ad drives conversions to (e.g. example.com), used for conversion attribution. display_sequence orders the ad within a sequenced campaign. Use pause_ad/enable_ad to change status.

Edit the creative of an existing Meta Ads ad (Facebook or Instagram): ad copy (message), headline, description, destination link, image, call-to-action button, URL tracking tags and Advantage+ enhancement settings. Meta treats ad creatives as immutable, so this copies the ad's current creative (keeping its name, url_tags and degrees_of_freedom_spec), applies the changes, creates the result as a new creative and re-points the ad at it; the ad keeps its id, but the returned creative id is new. Provide ad_id plus at least one field to change. Editable content fields depend on the creative's media type: link ads support all of them; video ads support message, headline, description, image_url (thumbnail), link and call_to_action_type (the link lives on the button, so adding a link to a video ad without a button also requires call_to_action_type); photo ads only message (the caption) and image_url; text ads only message. For carousel ads (link ads with cards), message edits the text above the cards; headline, description, link, image_url and call_to_action_type live on the cards, so also pass card_index (0-based) to edit one specific card. url_tags (e.g. 'utm_source=x&utm_medium=y') and degrees_of_freedom_spec (a raw Meta spec) can be edited on any creative, including ads that promote an existing organic post (e.g. boosted posts) — but content fields on those ads cannot be edited; edit the post itself instead. Dynamic/catalog creatives cannot be edited at all. Omitted fields keep their current values; to clear url_tags pass an empty string, and to reset degrees_of_freedom_spec to Meta's default enhancement behavior pass an empty object. To swap the ad to a different existing creative, use update_ad instead.