Create, edit and get insights from ads across Meta technologies, including Facebook, Instagram, Messenger, WhatsApp and more.
Create, edit and get insights from ads across Meta technologies, including Facebook, Instagram, Messenger, WhatsApp and more. On Nagent, Meta Ads is exposed as a fully-configurable ads & conversion integration that any agent can call — 52 actions, and OAUTH2, API_KEY authentication. No code is required to wire Meta Ads into your workflow — connect it once via the External Integrations panel and reuse it across every agent you build.
Agent builders use Meta Ads to automate the kinds of tasks ads & conversion teams previously handled manually. Concrete examples — each one is a single agent step in Nagent — include:
Every action and trigger is paired with a structured input/output schema (visible in the sections below), so when you wire Meta Ads into Helix — our agentic agent builder — the editor knows exactly what each step expects and produces. Configure once, deploy anywhere across your Nagent agents.
Every operation an agent can call against Meta Ads, with input parameters and output schema. Drop these into any step of an agent built in Helix.
METAADS_CREATE_ADCreate a new ad within an ad set using the Meta Marketing API. Supports various ad formats including image, video, carousel, and collection ads.
Input parameters
Name of the ad
Initial status of the ad
Creative specifications for the ad
ID of the ad set to create the ad in. The referenced ad set and its parent campaign must already exist.
Bid amount in cents (overrides ad set bid)
ID of the ad account (e.g. 'act_123456789'). Must start with 'act_'.
Tracking specifications for the ad
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_CREATE_AD_CREATIVECreate a new ad creative using the Meta Marketing API. Ad creatives are reusable visual and interactive elements that define how your ad looks and behaves: - Can be used in multiple ads - Support various formats (image, video, carousel) - Include text, media, and call-to-action buttons - Must follow Meta's ad policies
Input parameters
Name of your ad creative. Best practices: - Include the creative type (e.g., "Summer Sale - Image") - Add version if iterating (e.g., "v1") - Include target audience if specific - Keep it searchable and organized
The creative specifications for your ad. This defines: - What type of ad (image, video, carousel) - What it looks like (images, text) - How it behaves (links, buttons) See AdCreative model for details. Meta enforces strict asset specifications at creation time — image dimensions, aspect ratios, and text length must comply or the request will be rejected.
The ad account ID where you want to create the creative. Format: act_1234567890 Get this from your Meta Ads account settings. Must have proper permissions set up.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_CREATE_AD_SETCreate a new ad set within a campaign using the Meta Marketing API. Supports detailed targeting options, budgets, and optimization goals.
Input parameters
Name of the ad set
Initial status of the ad set
End time in ISO 8601 format
Targeting specifications for the ad set
ID of the ad account to create the ad set in
Bid amount in cents. Required when bid_strategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.
Start time in ISO 8601 format
ID of the campaign to create the ad set in
Bid strategy for the ad set. Required when using bid_amount with LOWEST_COST_WITH_BID_CAP or COST_CAP strategies.
Daily budget limit in account currency
The billing event for the ad set
Lifetime budget limit in account currency
The optimization goal for the ad set
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_CREATE_CAMPAIGNCreate a new advertising campaign using the Meta Marketing API. Supports various campaign objectives, budgets, and bidding strategies.
Input parameters
Name of the campaign
Initial status of the campaign
The objective of the campaign
The ID of the ad account to create the campaign in
Bidding strategy for the campaign
Daily budget limit in account currency. Mutually exclusive with lifetime_budget - provide one or the other, not both.
Lifetime budget limit in account currency. Mutually exclusive with daily_budget - provide one or the other, not both.
List of special ad categories that apply to this campaign
Ad set budget sharing allows up to 20% of your budget to be shared with other ad sets in the same campaign for improved performance. In v24.0+, this field is required when NO campaign budget is set AND budgets will be set at ad set level. Set to true to enable budget sharing optimization between ad sets (only applicable when budgets are set at ad set level). Should be false when using campaign-level budget (daily_budget or lifetime_budget).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_CREATE_CUSTOM_AUDIENCECreate a new custom audience using the Meta Marketing API. Supports various types of custom audiences including customer lists, website visitors, and app users.
Input parameters
Name of the custom audience
Rule for website/app custom audiences
Whether to prefill the audience with available data
Type of the custom audience
The ID of the ad account to create the custom audience in
Description of the custom audience
Content type for dynamic product catalog audiences.
Number of days to keep the audience data
Source of the customer file data
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_DELETE_CAMPAIGNDelete an advertising campaign using the Meta Marketing API. This marks the campaign as DELETED, which prevents it from delivering ads. Note that deleted campaigns are not permanently removed from Meta's systems and can still be viewed in reports.
Input parameters
ID of the campaign to delete
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_GET_AD_ACCOUNTSTool to retrieve all ad account IDs accessible to the authenticated user from Meta Ads. Use when you need to get a user's ad account information including account IDs, names, and other account details.
Input parameters
Maximum number of ad accounts to return (default 25)
Comma-separated list of fields to retrieve. Common fields: id, name, account_id, currency, timezone_name, account_status, business_name, business. The 'id' field returns the ad account ID prefixed with 'act_', while 'account_id' returns the numeric ID without prefix.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_GET_AD_CREATIVEGet Ad Creative
Input parameters
List of fields to include in the response.
The ID of the ad creative to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_GET_INSIGHTSGet insights data for a Meta Ads object (ad account, campaign, ad set, or ad) using the Meta Marketing API. Supports various metrics, breakdowns, and filtering options with flexible date ranges. Results are paginated; follow `paging.cursors.after` or `paging.next` to retrieve all rows. Missing metric values in results should not be assumed to be zero.
Input parameters
Fields to sort by with direction (_ascending or _descending suffix)
Level at which to aggregate the data Must match the type of object referenced by `object_id` (e.g., 'account' for 'act_...' IDs, 'campaign' for campaign IDs, 'adset' for ad set IDs, 'ad' for ad IDs); mismatches return empty or misleading metrics. Allowed values: 'account', 'campaign', 'adset', 'ad'.
List of metric fields to include in the response. Valid standalone fields include: impressions, clicks, spend, reach, cpc, cpm, ctr, frequency, account_name, account_id, campaign_name, campaign_id, adset_name, adset_id, ad_name, ad_id, objective, buying_type, date_start, date_stop. For conversion/action metrics: 'actions' (returns all action types with counts), 'action_values' (returns monetary values for all actions), 'conversions' (returns conversion-specific actions), 'conversion_values' (returns monetary values for conversions). Do NOT use 'conversion_value' (singular) as it is not a valid field - use 'action_values' or 'conversion_values' instead.
Filters to apply to the data
ID of the object to get insights for (ad account, campaign, ad set, or ad). For ad accounts, the ID must include the act_ prefix (e.g., act_123456789). Campaign, ad set, and ad IDs are numeric only.
List of breakdowns to apply to the data
Custom date range for the insights. If provided, date_preset should be set to null/None to use this custom range instead. Must be a dict with keys `since` and `until` in YYYY-MM-DD format (e.g., {'since': '2024-01-01', 'until': '2024-01-31'}). Never provide both time_range and date_preset simultaneously.
Predefined date range for the insights. Defaults to 'last_30d' if neither date_preset nor time_range is specified. Allowed values: 'today', 'yesterday', 'last_7d', 'last_30d', 'this_month', 'last_month', 'this_quarter'. Case-insensitive (e.g., 'LAST_30D' is normalized to 'last_30d'). Set to null/None only if you provide a custom time_range.
Internal field to track if date_preset was defaulted. Do not set this manually.
Internal field to track any field transformations made. Do not set this manually.
Attribution windows for conversion metrics. Defaults to `\[7d_click\]` to match Meta's unified attribution default; add `VIEW_1D`/`CLICK_28D`/etc. explicitly if you need legacy multi-window behavior. Different window values yield significantly different conversion counts; use consistent windows when comparing across campaigns or time periods.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_GET_OBJECTTool to retrieve data for any Meta Marketing API object by its ID. Use when you need to get information about a specific ad account, campaign, ad set, ad, ad creative, page, user, or other Meta object. Supports flexible field selection to retrieve only the data you need.
Input parameters
List of specific fields to retrieve from the object. If not specified, only basic fields (id, name) will be returned. Available fields depend on the object type. Common fields include: id, name, status, account_id, created_time, updated_time. For ads: campaign_id, adset_id, creative. For campaigns: objective, buying_type, daily_budget. For ad creatives: asset_feed_spec, object_story_spec, image_url, video_id, title, body, link_url, call_to_action_type. For users: email, first_name, last_name. Note: For ad account objects, use 'ad_account_promotable_objects' to retrieve promotable objects - the field name 'promotable_objects' (without prefix) is not valid for ad accounts.
The numeric ID of the Facebook Graph API object (e.g., '123456789012345'). Must be a numeric Facebook ID, not an image hash or other non-numeric identifier. Can be an ad account ID (with or without 'act_' prefix), campaign ID, ad set ID, ad ID, ad creative ID, page ID, user ID, or any other Meta Marketing API object ID. For user info, use 'me' as the object_id.
Custom date range for aggregating insights metrics.
Predefined date range options for aggregating insights metrics.
Unix timestamp to retrieve only objects updated since this time. Useful for incremental syncs and fetching recent changes.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_GET_PAGE_ACCOUNTSTool to retrieve permanent page access tokens for accounts managed by the user. Use when you need to get pages the user manages along with access tokens for each page.
Input parameters
Comma-separated list of fields to return for each page. Common fields: access_token (page access token), name (page name), id (page ID), tasks (array of permissions/tasks), category (page category), category_list (array of category objects with id and name).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_GET_USERTool to retrieve information about the authenticated user from Meta (Facebook) Graph API. Use when you need to get the current user's profile information such as name, email, or other user details.
Input parameters
Comma-separated list of fields to retrieve about the authenticated user. Common fields: id (user's unique identifier), name (full name), email (requires email permission), first_name, last_name, picture (profile picture object), age_range, birthday, gender, locale. By default returns id, name, and email.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_GET_VIDEODEPRECATED: Use METAADS_GET_OBJECT instead. Tool to retrieve video information from Meta's Graph API by video ID. Use when you need to get video details such as the source URL for playback/download, permalink URL to view on Facebook, or other video metadata like title, description, length, and thumbnails.
Input parameters
Comma-separated list of fields to retrieve from the video object. Common fields include: id (video ID), source (direct video URL for playback/download), permalink_url (permanent Facebook URL to view the video), created_time (when video was created), title (video title), description (video description), length (duration in seconds), thumbnails (thumbnail images object), format (list of available video formats). By default returns id, source, and permalink_url.
The ID of the video to retrieve from Meta's Graph API
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_AD_CREATIVESTool to list all ad creatives under an ad account. Use when you need to retrieve multiple ad creatives from a Meta Ads account to view, analyze, or manage creative assets.
Input parameters
Maximum number of ad creatives to return per page (default 25).
Comma-separated list of fields to return for each ad creative. Supported fields include: id, name, status, account_id, body, title, image_url, image_hash, video_id, thumbnail_url, link_url, call_to_action_type, object_type, object_id, object_story_spec, object_story_id, effective_object_story_id, asset_feed_spec, template_url, url_tags, adlabels, applink_treatment, authorization_category, effective_authorization_category, and others. Note: 'effective_status' is NOT supported for ad creatives (it's only available on Ads, Ad Sets, and Campaigns - use METAADS_LIST_ADS instead).
The ad account ID to list ad creatives from. Can be provided with or without the 'act_' prefix (e.g., 'act_123456789' or '123456789').
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_AD_NETWORK_ANALYTICSTool to retrieve ad network analytics for a Meta Business using the Meta Marketing API. Use when you need to get ad network performance metrics such as revenue or impressions.
Input parameters
The Business ID to query ad network analytics for
Maximum number of results to return per request (default 25, API default 2000)
Comma-separated list of metrics to retrieve. Example: fb_ad_network_revenue
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_AD_NETWORK_ANALYTICS_RESULTSTool to retrieve ad network analytics results for Facebook Audience Network. Use when you need to get performance data from ads displayed through Facebook Audience Network on third-party apps and websites for a specific business, app, or property.
Input parameters
Comma-separated list of fields to retrieve in the response. If not specified, returns default fields.
The query ID returned from a previous adnetworkanalytics request. Use this to retrieve the results of an asynchronous report generation. If not provided, returns all available results for the specified object ID.
Business ID, App ID, or Property ID that uses Facebook Audience Network. This is the identifier for the entity whose ad network analytics results you want to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_ADSTool to list all ads under an ad account using the Meta Marketing API. Use when you need to retrieve ads from a specific ad account with optional filtering by fields.
Input parameters
Maximum number of ads to return per page (default 25, max 100)
Comma-separated list of fields to return. Common fields: id, name, adset_id, campaign_id, status, effective_status, created_time, updated_time, creative, tracking_specs, conversion_specs, targeting, bid_amount, source_ad_id, preview_shareable_link.
The ad account ID (with or without 'act_' prefix, e.g., 'act_123456789' or '123456789')
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_AGENCIESTool to retrieve agencies associated with a Meta Business or Ad Account. Use when you need to get the list of agencies that have access to manage a specific business or ad account.
Input parameters
The ID of the Business or Ad Account to fetch agencies from. This can be a Business ID (numeric) or an Ad Account ID (with or without 'act_' prefix).
Maximum number of agencies to return (default 25)
Comma-separated list of fields to retrieve for each agency. Common fields: id, name. The 'id' field returns the agency ID, while 'name' returns the agency name.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_ASSIGNED_PAGESTool to retrieve Facebook Pages assigned to a business user via Meta Marketing API. Use when you need to get the list of pages a business user has access to.
Input parameters
The ID of the business user. Can be obtained from GET /{business_id}/business_users endpoint
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_ASSIGNED_USERSTool to list users assigned to a Facebook Page or Ad Account within a specific business context. Use when you need to retrieve the list of users who have access to a Page or Ad Account and their associated task permissions.
Input parameters
The ID of the Page or Ad Account to list assigned users for. For Ad Accounts, use the account ID with or without the 'act_' prefix (e.g., 'act_123456789' or '123456789'). For Pages, use the Page ID (e.g., '916958084834651').
Cursor for forward pagination.
Maximum number of results to return per page.
Cursor for backward pagination.
Comma-separated list of fields to retrieve for each assigned user. Available fields: id, name, tasks. Defaults to 'id,name,tasks' to retrieve all standard fields.
Business ID to filter assigned users by business context. This parameter is required when calling assigned_users on Page or AdAccount objects.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_BUSINESS_AD_ACCOUNTSTool to retrieve all ad accounts owned by a specific Business Manager. Use when you need to get ad account information for a business including account IDs, names, and status.
Input parameters
Maximum number of ad accounts to return (default 25)
Comma-separated list of fields to retrieve. Common fields: id, name, account_id, account_status, currency, timezone_name, business_name, business. The 'id' field returns the ad account ID prefixed with 'act_', while 'account_id' returns the numeric ID without prefix.
The ID of the business to retrieve owned ad accounts for
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_BUSINESS_INVOICESTool to retrieve business invoices from Meta Marketing API. Use when you need to fetch invoice data for a business including amounts, due dates, and payment status.
Input parameters
ID of the business to retrieve invoices for
Type of invoice from OmegaCustomerTrx.Type enum.
Cursor for forward pagination.
Maximum number of results to return per page.
Cursor for backward pagination.
Root ID for filtering invoices
End date for filtering invoices (YYYY-MM-DD format)
Specific invoice ID to retrieve
Start date for filtering invoices (YYYY-MM-DD format)
Issue end date for filtering invoices (YYYY-MM-DD format)
Issue start date for filtering invoices (YYYY-MM-DD format)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_CLIENT_AD_ACCOUNTSTool to list all client ad accounts accessible to a business from Meta Ads. Use when you need to retrieve ad accounts that have been shared with a Business Manager as clients.
Input parameters
Maximum number of ad accounts to return (default 25)
Comma-separated list of fields to retrieve. Common fields: id, name, account_id, currency, timezone_name, account_status, business_name, business. The 'id' field returns the ad account ID prefixed with 'act_', while 'account_id' returns the numeric ID without prefix.
The business ID to fetch client ad accounts from
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_CLIENT_APPSTool to retrieve client apps associated with a Meta Business using the Marketing API. Use when you need to get information about apps linked to a specific business.
Input parameters
Cursor for forward pagination.
Maximum number of results to return per page.
Cursor for backward pagination.
The ID of the Business object. Can be obtained from GET /me/businesses endpoint.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_CLIENT_INSTAGRAM_ASSETSTool to retrieve Instagram assets that are shared with a business as a client using the Meta Marketing API. Use when you need to fetch Instagram accounts or assets linked to a specific business ID.
Input parameters
Cursor for pagination. Use the 'after' cursor from the previous response to fetch the next page of results.
Maximum number of Instagram assets to return per page (default 25)
Comma-separated list of fields to retrieve for each Instagram asset. If not specified, default fields will be returned.
The business ID whose client Instagram assets to retrieve. Can be obtained from /me/businesses endpoint.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_CLIENT_OFFSITE_SIGNAL_CONTAINERSTool to retrieve client offsite signal container business objects for a business from Meta Marketing API. Use when you need to list all client offsite signal container business objects associated with a specific business ID.
Input parameters
Business ID - The ID of the business to query for client offsite signal container business objects
Maximum number of client offsite signal container business objects to return (default 25)
Comma-separated list of fields to retrieve from the client offsite signal container business objects. If not specified, default fields will be returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_CLIENT_PAGESTool to retrieve client pages associated with a Meta business. Use when you need to get the list of pages that a business manages on behalf of clients.
Input parameters
The ID of the business to retrieve client pages for. Can be obtained via GET /me/businesses endpoint.
Maximum number of client pages to return per request. Use this parameter to control pagination.
List of fields to retrieve for each client page. Common fields include: id, name, access_token, category, tasks. If not specified, default fields are returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_CLIENTSTool to retrieve client businesses associated with a Meta Business Manager. Use when you need to get the list of businesses that are clients of a specific Business Manager.
Input parameters
Business Manager ID to fetch client businesses from. Can be obtained from GET /me/businesses endpoint.
Maximum number of client businesses to return (default 25)
Comma-separated list of fields to retrieve for each client business. Common fields: id, name. The 'id' field returns the client business ID, while 'name' returns the client business name.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_COLLABORATIVE_ADS_COLLABORATION_REQUESTSTool to retrieve collaborative ads collaboration requests for a Meta Business using the Marketing API. Use when you need to get collaboration requests related to collaborative advertising partnerships for a specific business.
Input parameters
The Business ID to retrieve collaborative ads collaboration requests for. This is typically obtained from the /me/businesses endpoint.
Maximum number of collaboration requests to return per page (default 25)
Comma-separated list of fields to retrieve for each collaboration request. If not specified, default fields will be returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_COLLABORATIVE_ADS_SUGGESTED_PARTNERSTool to retrieve collaborative ads suggested partners for a business from Meta Marketing API. Use when you need to discover potential partnership opportunities for collaborative advertising campaigns.
Input parameters
Maximum number of suggested partners to return (default 25)
Comma-separated list of fields to retrieve for each suggested partner. If not specified, default fields will be returned.
Business ID to retrieve collaborative ads suggested partners for
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_INITIATED_AUDIENCE_SHARING_REQUESTSTool to retrieve initiated audience sharing requests for a business using the Meta Marketing API. Use when you need to get the list of audience sharing requests that have been initiated by a business.
Input parameters
Business ID to retrieve initiated audience sharing requests for. Can be obtained from the /me/businesses endpoint.
Cursor for pagination - use the 'after' cursor from the previous response to fetch the next page
Maximum number of sharing requests to return per page (default 25)
Comma-separated list of fields to retrieve for each sharing request. If not specified, default fields will be returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_MANAGED_PARTNER_ADS_FUNDING_SOURCE_DETAILSTool to retrieve managed partner ads funding source details for a Meta Business. Use when you need to get funding source information for managed partner ads associated with a specific business.
Input parameters
Business ID - The ID of the business to retrieve managed partner ads funding source details for. This should be a Business node ID, not a User ID or Ad Account ID.
Maximum number of results to return per request (default 25)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_OWNED_APPSTool to retrieve apps owned by a business from Meta Marketing API. Use when you need to get information about apps associated with a business account.
Input parameters
Maximum number of owned apps to return (default 25)
Comma-separated list of fields to retrieve. Available fields: id, name, link, category
The ID of the business to retrieve owned apps for
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_OWNED_BUSINESSESTool to retrieve businesses owned by a parent Business Manager from Meta Marketing API. Use when you need to list child businesses managed under a Business Manager account in a Tier-2 business hierarchy.
Input parameters
Maximum number of owned businesses to return (default 25)
Comma-separated list of fields to retrieve for each owned business. Common fields: id, name, created_time, link, timezone_id, vertical, verification_status
The ID of the parent Business Manager to retrieve owned businesses from
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_OWNED_INSTAGRAM_ASSETSTool to list Instagram accounts/assets owned by a Meta Business. Use when you need to retrieve the Instagram Business Accounts associated with a specific Meta Business.
Input parameters
Maximum number of Instagram assets to return (default 25)
Comma-separated list of fields to return for each Instagram asset (e.g., id,username). Common fields include: id, username, name, profile_picture_url, followers_count, follows_count, media_count, ig_id.
Business ID - can be obtained from /me/businesses endpoint. This is the Meta Business ID that owns the Instagram assets.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_OWNED_OFFSITE_SIGNAL_CONTAINER_BUSINESS_OBJECTSTool to retrieve owned offsite signal container business objects for a business from Meta Marketing API. Use when you need to list all owned offsite signal container business objects associated with a specific business ID.
Input parameters
Business ID - The ID of the business to query for owned offsite signal container business objects
Maximum number of owned offsite signal container business objects to return (default 25)
Comma-separated list of fields to retrieve from the owned offsite signal container business objects. If not specified, default fields will be returned.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_OWNED_PAGESTool to retrieve Pages owned by a Business Manager from Meta Marketing API. Use when you need to get a list of all Facebook Pages that a business owns or manages.
Input parameters
Maximum number of pages to return per request (default 25)
Comma-separated list of Page fields to return. Common fields include: id, name, category, access_token, category_list, tasks, fan_count, link, picture, verification_status. If not specified, only basic fields (id, name) are returned.
The ID of the Business Manager to list owned pages for
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_PENDING_CLIENT_AD_ACCOUNTSTool to retrieve pending client ad account access requests for a Business Manager from Meta Ads. Use when you need to get ad accounts that are awaiting approval to be added as clients to a business.
Input parameters
Maximum number of pending client ad accounts to return (default 25)
Comma-separated list of fields to retrieve. Available fields: id (ad account ID), name (ad account name), permitted_tasks (list of tasks permitted for this ad account).
The ID of the Business Manager to retrieve pending client ad account access requests from
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_PENDING_CLIENT_APPSTool to retrieve pending client apps for a Meta Business. Use when you need to list apps that are pending approval or connection to a business account.
Input parameters
Maximum number of pending client apps to return (default 25)
Comma-separated list of fields to retrieve for each pending client app. If not specified, default fields will be returned.
The Business ID to retrieve pending client apps for. Can be retrieved from /me?fields=businesses endpoint.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_PENDING_CLIENT_PAGESTool to retrieve pending client pages for a Business Manager using the Meta Marketing API. Use when you need to see which Facebook Pages have pending access requests from the business.
Input parameters
Maximum number of pages to return per request (default 25)
The Business Manager ID to retrieve pending client pages for. This is the numeric ID of the business.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_PENDING_OFFSITE_SIGNAL_CONTAINERSTool to retrieve pending shared offsite signal container business objects from Meta Marketing API. Use when you need to get information about pending shared offsite signal containers associated with a business account.
Input parameters
Business ID to retrieve pending shared offsite signal container business objects for
Maximum number of items to return (default 25)
Comma-separated list of fields to retrieve from the pending shared offsite signal container business objects
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_PENDING_OWNED_AD_ACCOUNTSTool to retrieve pending owned ad accounts for a Business Manager account from Meta Marketing API. Use when you need to list ad accounts with pending ownership status for a specific business.
Input parameters
Maximum number of pending ad accounts to return per page (default 25)
Comma-separated list of fields to retrieve for each pending ad account. Common fields: id, account_id, name, currency, timezone_name, account_status.
The Business ID to retrieve pending owned ad accounts for. This is the ID of the Business Manager account.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_PENDING_OWNED_PAGESTool to retrieve Pages with pending ownership status for a Business Manager from Meta Marketing API. Use when you need to get a list of Facebook Pages that are pending approval or verification for a business to own.
Input parameters
Maximum number of pages to return per request (default 25)
Comma-separated list of Page fields to return. Common fields include: id, name, category, access_token, category_list, tasks, fan_count, link, picture, verification_status. If not specified, only basic fields (id, name) are returned.
The ID of the Business Manager to list pending owned pages for. This should be the business ID, not a user ID.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_PENDING_USERSTool to retrieve pending users from a Business Manager in Meta Marketing API. Use when you need to get information about users with pending invitations to a Business Manager.
Input parameters
The Business Manager ID to retrieve pending users from
Maximum number of pending users to return per request (default 25)
Comma-separated list of fields to return. Common fields include: id, email, name, role. Specify the fields you want to retrieve in the response.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_RECEIVED_AUDIENCE_SHARING_REQUESTSTool to retrieve all received audience sharing requests for a business using the Meta Marketing API. Use when you need to see which other businesses have requested to share custom audiences with your business.
Input parameters
The Business ID to retrieve received audience sharing requests for. This is the ID of the business entity that has received sharing requests from other businesses.
Maximum number of audience sharing requests to return (default 25)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_SYSTEM_USERSTool to retrieve system users for a Meta Business Manager account. Use when you need to list all system users (non-human accounts used for API access) associated with a business.
Input parameters
Maximum number of system users to return per page (default 25)
Comma-separated list of fields to retrieve for each system user. Common fields include: id, name, role. The 'id' field returns the system user's unique identifier, 'name' returns the display name, and 'role' indicates the permission level.
The ID of the business to retrieve system users for. This is the Business Manager ID.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_LIST_TARGETING_SEARCHTool to search for targeting options in Meta Ads Marketing API. Use when you need to find interests, locations, demographics, schools, or employers for ad targeting purposes.
Input parameters
The search query string to find targeting options. For example, 'fitness' to find fitness-related interests, or 'New York' to find location-based targeting.
The targeting search type to query. Options: 'adinterest' (interests), 'adgeolocation' (locations), 'adTargetingCategory' (targeting categories), 'adeducationschool' (schools), 'adworkemployer' (employers).
The demographic class for refined searches. Common values: 'demographics', 'family_statuses', 'income', 'industries', 'life_events'. Use this to narrow down search results to specific demographic categories.
Maximum number of results to return. If not specified, the API will use its default limit.
For geolocation searches (type='adgeolocation'), specify location types to filter results. Common values: 'city', 'country', 'region', 'zip'.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_PREVIEW_AD_CREATIVEPreview Ad Creative
Input parameters
ID of the ad creative to preview. Get this from: - CreateAdCreative response - Existing ad creative lookup Format: 23842938523454
Width of the preview thumbnail in pixels. - Default: 150px - Min: 50px - Max: 1200px Larger sizes give better quality but load slower.
Height of the preview thumbnail in pixels. - Default: 120px - Min: 50px - Max: 1200px Choose based on your display needs.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_READ_ADSETSRetrieve ad sets from a Meta ad account using the Marketing API. Returns information about the ad sets including their status, targeting, and other properties.
Input parameters
Maximum number of adsets to return
Fields to return for each ad set. Select from the AdSetField enum values (e.g., name, id, status, daily_budget, targeting, campaign_id, effective_status). Defaults to name, id, and status if not specified.
Predefined date range used to aggregate insights metrics. Values are case-insensitive (e.g., 'this_year' or 'THIS_YEAR').
Filter adsets by completed status
ID of the ad account to fetch adsets from
Time since the Adset has been updated (in seconds)
Filter adsets by their effective status. Values are case-insensitive (e.g., 'active' or 'ACTIVE').
Start date in YYYY-MM-DD format for custom date range
End date in YYYY-MM-DD format for custom date range
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_UPDATE_AD_CREATIVEUpdate Ad Creative
Input parameters
New name for the ad creative. Use descriptive names to organize your creatives.
New status for the ad creative. ACTIVE enables the creative, PAUSED disables it temporarily, DELETED removes it, ARCHIVED stores it for reference.
The ID of the ad creative to update. You can get this from the create_ad_creative or get_ad_creative actions.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_UPDATE_CAMPAIGNUpdate an existing advertising campaign using the Meta Marketing API. Allows modification of campaign properties like name, status, budget, and bidding strategy. Only the fields that need to be updated should be included in the request.
Input parameters
New name for the campaign
Updated status of the campaign
Updated spend cap for the campaign in account currency (minimum value $100 USD)
ID of the campaign to update
Updated bidding strategy for the campaign
Updated daily budget limit in account currency Set only one of `daily_budget`, `lifetime_budget`, or `spend_cap` per request — they are mutually exclusive based on the campaign's buying type.
Updated lifetime budget limit in account currency
Updated list of special ad categories that apply to this campaign
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
METAADS_UPLOAD_AD_IMAGEUpload an image for use in Meta ad creatives using the Marketing API. The image can later be referenced by its hash when creating ad creatives.
Input parameters
Optional name for the image (max 100 characters)
Image file to upload. Supported formats: JPG, PNG, GIF, BMP, TIFF. Maximum file size: 30MB. Dimensions and aspect ratio are also enforced; invalid combinations are rejected at upload time.
ID of the ad account to upload the image to
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
No publicly available marketplace agent is found using this tool yet. There are 37 agents privately built on Nagent that already use Meta Ads.
Build on Nagent
Connect Meta Ads to any Nagent agent in minutes — no API key management, no boilerplate. Just configure and deploy.
The five questions agent builders ask before adopting a new integration.
Open the External Integrations panel inside Nagent (app.nagent.ai/externalIntegration), find Meta Ads, and click "Connect Now." You'll authenticate with OAUTH2, API_KEY — Nagent handles credential storage and refresh automatically. Once connected, Meta Ads is available to any agent in your workspace.
No. Nagent provides no-code integration for every tool. Once Meta Ads is connected, you configure its 52 actions directly in the agent builder UI — no API calls, no boilerplate, no schema management.
Helix — Nagent's agentic agent builder — lets you drop Meta Ads steps into any workflow visually. Pick an action (e.g., one of those listed above), fill in the inputs (Helix knows the required vs. optional schema for each parameter), and connect it to upstream/downstream steps. Triggers run as the entry point of an agent, so when a Meta Ads event fires, the agent kicks off automatically.
Every Meta Ads action and trigger ships with a fully-typed schema — input parameters with name, type, required flag, and description, plus the output payload shape. The schemas are documented in the sections above. Helix uses these schemas to validate your configuration at build time and to type-check the data flowing between steps.
Yes. While Meta Ads ships with 52 pre-built ads & conversion actions, you can layer custom logic around them inside Helix — pre/post-processing steps, conditional branches, retries, or stitching Meta Ads together with other connected tools. For deeper customization, talk to our team about Nagent's Agentic AI Lab — forward-deployed engineers who build Meta Ads-based workflows tailored to your business.