Meta Ads

Create a new ad creative with object_story_spec. The spec defines the ad content (link, photo, or video) and the associated Facebook Page. Notes for v26.0: poll_spec and the poll type under interactive_components_spec are no longer supported and will be rejected. If the advertiser has a shop, eligible creatives now default to destination_spec.destination_type=WEBSITE_AND_SHOP — set it to WEBSITE_AND_SHOP_OPT_OUT to opt out.

Create a new custom audience. Subtype determines the audience source (CUSTOM, WEBSITE, APP, OFFLINE_CONVERSION, LOOKALIKE, ENGAGEMENT, etc.).

Create a dynamic creative with asset_feed_spec. Meta automatically combines different images, videos, titles, bodies, and CTAs to find the best performing combinations.

Create a new A/B test experiment (ad study).

Create a new product feed for a catalog.

Create a new lead generation form on a Facebook Page. Requires pages_manage_ads permission.

Create a lookalike audience based on an existing custom audience. Ratio (1-10) determines how closely the new audience resembles the source.

Create a new offline conversion data set.

Create a new product set within a catalog.

Create a new reach & frequency prediction. Provide targeting spec as JSON string, budget in cents, and scheduling info.

Create a new automated rule for the ad account.

Create a new system user in the configured business. Requires META_BUSINESS_ID env var.

Debug an access token to inspect its properties, permissions, expiration, and validity. Requires META_APP_ID and META_APP_SECRET.

Delete an ad. This action is irreversible.

Delete an ad set. This action is irreversible.

Delete a custom audience. This action is irreversible.

Delete a publisher block list. This action is irreversible.

Delete a budget schedule. This action is irreversible.

Delete a campaign. This action is irreversible.

Delete an Instant Experience (Canvas). This action is irreversible.

Delete an ad image by hash. This action is irreversible.

Delete a reach & frequency prediction. This action is irreversible.

Delete an automated rule.

Delete an ad video. This action is irreversible.

Exchange a short-lived access token for a long-lived token. Requires META_APP_ID and META_APP_SECRET to be configured.

Generate an ad preview without needing an existing ad. Provide creative spec directly to see how it would look.

Get activity log for the ad account. Shows changes made to campaigns, ad sets, ads, etc.

Get performance insights for the ad account. Returns metrics like impressions, clicks, spend, reach, etc.

Get details of a specific ad by ID.

Get details of the configured ad account including status, balance, currency, timezone, and spend info.

Get performance insights for a specific ad.

Get a preview of an ad in a specific format. Returns HTML iframe for rendering.

Get details of a specific ad set by ID.

Get all ads belonging to a specific ad set.

Get performance insights for a specific ad set.

Get leads generated by a specific ad set. Requires leads_retrieval permission.

Get human-readable targeting description for an ad set. Converts targeting spec into readable sentences.

Check status and retrieve results of an async insight report.

Get details of a specific custom audience by ID.

Get health status and delivery readiness of a custom audience. Shows match rate, size, and operation status.

Check the status of a catalog batch operation.

Get details of a specific business by ID.

Get details of a specific campaign by ID.

Get all ads belonging to a specific campaign.

Get all ad sets belonging to a specific campaign.

Get performance insights for a specific campaign.

Get leads generated by a specific campaign. Requires leads_retrieval permission.

Get details of a specific Instant Experience (Canvas) by ID.

Get details of a specific product catalog.

Get details of a specific ad creative by ID.

Get delivery estimate for an ad set, including estimated daily reach. Note: the delivery_estimate edge exists on the ad set (and ad account) node, not on individual ads. Also note: as of v26.0, the daily_outcomes_curve, budget_guardrail, and estimate_dau fields are no longer returned (removed with no replacement).

Get details of a specific experiment (ad study).

Get results/cells of an experiment (ad study).

Get upload history for a product feed.

Get leads submitted through a lead generation form.

Get details of a specific ad image by ID.

Get details of a specific lead by ID.

Get details of a specific lead generation form.

Get details of a specific product.

Get details of a specific product set.

Get estimated audience reach for a given targeting specification. Useful for planning campaigns before creating them.

Get details of a specific reach & frequency prediction by ID.

Get details of a specific automated rule.

Get details of a specific saved audience by ID.

Get targeting suggestions based on existing targeting criteria. Meta suggests related interests, behaviors, and demographics.

Get details of a specific ad video by ID.

List users who have access to the ad account with their roles and permissions.

List all ad accounts accessible by the current user. Returns paginated results.

List ads in the ad account. Optionally filter by campaign, ad set, or status.

List ad sets in the ad account. Optionally filter by campaign or status.

List publisher block lists for the ad account. Returns paginated results.

List budget schedules attached to a campaign or ad set. Returns paginated results.

List ad accounts owned by the configured business. Requires META_BUSINESS_ID env var.

List Instagram accounts owned by the configured business. Requires META_BUSINESS_ID env var.

List Facebook Pages owned by the configured business. Requires META_BUSINESS_ID env var.

List users of the configured business. Requires META_BUSINESS_ID env var.

List all businesses accessible by the current user. Returns paginated results.

List campaigns in the ad account. Supports filtering by status and objective. Returns paginated results.

List Instant Experience (Canvas) creatives in the ad account.

List product catalogs for the ad account.

List ad creatives in the ad account.

List custom audiences in the ad account.

List A/B test experiments (ad studies) for the ad account.

List product feeds for a catalog.

List ad images uploaded to the ad account.

List lead generation forms for a Facebook Page.

List offline conversion data sets for the ad account.

List product sets within a catalog.

List products within a catalog.

List reach & frequency predictions for the ad account. Returns paginated results.

List automated rules for the ad account.

List saved audiences in the ad account. Saved audiences are reusable targeting presets.

List system users of the configured business. Requires META_BUSINESS_ID env var.

List ad videos uploaded to the ad account.

Extend a valid long-lived user access token through Meta's documented token exchange flow. Requires META_APP_ID and META_APP_SECRET.

Remove a user from the configured business. Requires META_BUSINESS_ID env var.

Remove publisher URLs from an existing block list.

Remove users from a custom audience. Payload format is the same as add_users_to_audience.

Search the Meta Ad Library for ads. Allows searching by keywords, countries, and ad type. Useful for competitive research and transparency.

Search for geographic locations (countries, regions, cities, zip codes) for ad targeting.

Search for targeting options (interests, behaviors, demographics, etc.) by keyword. Use this to find valid targeting IDs for ad set targeting specs.

Map targeting IDs to their full details (names, types, paths). Useful for resolving IDs obtained from other endpoints.

Send a server-side conversion event via the Conversions API (pixel).

Send offline conversion events through the Conversions API to a dataset. Store events must use action_source=physical_store.

Update an existing ad. Only provided fields will be modified.

Update the configured ad account settings. Only provided fields will be modified.

Update an existing ad set. Only provided fields will be modified.

Update an existing custom audience. Only provided fields will be modified.

Update an existing budget schedule. Only provided fields will be modified.

Update an existing campaign. Only provided fields will be modified.

Update an existing product catalog.

Update an existing ad creative. Only name and url_tags can be modified after creation.

Update an existing experiment (ad study).

Update an existing product in a catalog.

Update an existing product set.

Update an existing automated rule.

Upload/trigger a feed file upload for a product feed.

Upload an ad image from a public URL or a local file. Returns image hash for use in ad creatives. Note: fetching from a URL requires the app to have Meta's URL-fetch capability — if that fails with an OAuthException 'Application does not have the capability to make this API call', use file_path to upload the raw bytes instead, which does not require that capability.

Upload an ad video from a public URL or a local file. Returns video ID for use in ad creatives.