Meta Ads

App · Marketing Automation · 20 actions

Build and manage Meta ad campaigns (campaigns, ad sets, ads, creatives) and read how they are delivering.

Actions

ActionWhat it does
Create a campaignCreate a campaign in an ad account.
Create an adCreate an ad in an ad set from a creative you have already made.
Create an ad creativeCreate a link ad creative from one of your Facebook Pages: a message, a destination URL and an optional headline.
Create an ad setCreate an ad set under a campaign, with its own daily budget and country targeting.
Delete a campaignDelete a campaign along with every ad set and ad inside it.
Delete an adDelete an ad.
Delete an ad setDelete an ad set and the ads inside it.
Get a campaignRead one campaign's objective, status, budget and schedule.
Get account insightsRead impressions, reach, clicks, CTR and spend for a whole ad account over a chosen window, optionally broken out per campaign, ad set or ad.
Get an ad setRead one ad set's budget, schedule, optimization goal and the countries it targets.
Get campaign insightsRead impressions, reach, clicks, CTR and spend for one campaign over a chosen window, optionally broken out per ad set or ad.
List ad accountsList every Meta ad account the connected user can advertise on, with each account's currency, status and lifetime spend.
List ad creativesList the saved ad creatives in an ad account: the headline, body text and thumbnail each ad can run.
List ad setsList the ad sets in an ad account, or just the ones in a single campaign, with each ad set's budget and targeting.
List adsList the ads in an ad account, or just the ones in a single ad set, with each ad's status and creative.
List campaignsList the campaigns in an ad account, with each campaign's objective, delivery status and budget.
List Facebook PagesList the Facebook Pages you manage, with the id each one needs when you create an ad creative.
Update a campaignRename a campaign, pause or resume it, or change its daily budget.
Update an adRename an ad, or pause or resume it.
Update an ad setRename an ad set, pause or resume it, or change its daily budget.

Create a campaign

Create a campaign in an ad account. New campaigns are created paused unless you choose otherwise, so nothing starts spending before you have added an ad set and an ad.

Inputs

Ad accountad_account_idtextRequired
The ad account to create the campaign in.
NamenametextRequired
The campaign's name, as shown in Ads Manager.
ObjectiveobjectivetextRequired
What the campaign optimizes for. This cannot be changed after the campaign is created.One of: OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_APP_PROMOTION, OUTCOME_SALES. Default: OUTCOME_TRAFFIC.
Statusstatustext
The status to create the campaign in.One of: ACTIVE, PAUSED, ARCHIVED. Default: PAUSED.
Special ad categoriesspecial_ad_categorieslist
Declare a regulated category if the ads promote housing, employment, credit, or social issues, elections and politics. Choose None for anything else: Meta requires the declaration either way.One or more of: NONE, HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS. Default: ["NONE"].
Daily budgetdaily_budgetnumber
An optional daily budget in the ad account's own currency, for example, 25 for twenty-five dollars. Leave empty to set budgets on the ad sets instead.
Buying typebuying_typetext
How inventory is bought. Auction is the default and is what almost every campaign uses.One of: AUCTION, RESERVED.
Share budget across ad setsshare_budget_across_ad_setstrue/false
Only applies when you leave the daily budget empty and set budgets on the ad sets instead. Turn it on to let Meta move up to 20% of one ad set's budget to another in the same campaign. Off keeps each ad set to its own budget.Default: false.

Outputs

campaignobject
Example output
{
  "campaign": {
    "account_id": "1234567890",
    "budget_remaining": 25.0,
    "buying_type": "AUCTION",
    "created_time": "2026-07-30T11:02:19-0700",
    "daily_budget": 25.0,
    "effective_status": "PAUSED",
    "id": "23851234567890123",
    "lifetime_budget": null,
    "name": "Spring launch",
    "objective": "OUTCOME_TRAFFIC",
    "special_ad_categories": [],
    "start_time": "2026-08-01T00:00:00-0700",
    "status": "PAUSED",
    "stop_time": "",
    "updated_time": "2026-08-02T08:41:03-0700"
  }
}

Create an ad

Create an ad in an ad set from a creative you have already made. New ads go through Meta's review before they can deliver, and are created paused unless you choose otherwise.

Inputs

Ad accountad_account_idtextRequired
The ad account the ad set belongs to.
Ad set IDad_set_idtextRequired
The ad set to create the ad in.
NamenametextRequired
The ad's name, as shown in Ads Manager.
Creative IDcreative_idtextRequired
The creative this ad runs, as returned by Create an ad creative or List ad creatives.
Statusstatustext
The status to create the ad in. Only Active and Paused are allowed at creation.One of: ACTIVE, PAUSED. Default: PAUSED.

Outputs

adobject
Example output
{
  "ad": {
    "account_id": "1234567890",
    "adset_id": "23851234567890456",
    "campaign_id": "23851234567890123",
    "created_time": "2026-07-30T11:06:31-0700",
    "creative_id": "23851234567891011",
    "effective_status": "PAUSED",
    "id": "23851234567890789",
    "name": "Spring launch \u2014 link ad",
    "status": "PAUSED",
    "updated_time": "2026-08-02T08:41:03-0700"
  }
}

Create an ad creative

Create a link ad creative from one of your Facebook Pages: a message, a destination URL and an optional headline. Meta builds the preview image from the link.

Inputs

Ad accountad_account_idtextRequired
The ad account to save the creative in.
NamenametextRequired
A name for the creative, used to find it later in Ads Manager.
Facebook Pagepage_idtextRequired
The Page the ad is published as. Pick one of your Pages, or paste a Page id.
MessagemessagetextRequired
The ad's primary text, shown above the image.
Destination URLlinktextRequired
Where the ad sends people, for example, https://example.com/spring.
Headlinelink_titletext
An optional headline shown under the image. Leave empty to let Meta use the page's own title.

Outputs

ad_creativeobject
Example output
{
  "ad_creative": {
    "account_id": "1234567890",
    "body": "Everything new, in one place.",
    "id": "23851234567891011",
    "name": "Spring launch creative",
    "status": "ACTIVE",
    "thumbnail_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/example.jpg",
    "title": "Spring collection"
  }
}

Create an ad set

Create an ad set under a campaign, with its own daily budget and country targeting. New ad sets are created paused unless you choose otherwise.

Inputs

Ad accountad_account_idtextRequired
The ad account the campaign belongs to.
Campaign IDcampaign_idtextRequired
The campaign to create the ad set under.
NamenametextRequired
The ad set's name, as shown in Ads Manager.
Daily budgetdaily_budgetnumberRequired
The most this ad set may spend per day, in the ad account's own currency: 25 means twenty-five dollars on a USD account.Default: 5.
Billing eventbilling_eventtextRequired
What Meta charges for.One of: APP_INSTALLS, CLICKS, IMPRESSIONS, LINK_CLICKS, NONE, OFFER_CLAIMS, PAGE_LIKES, POST_ENGAGEMENT, THRUPLAY, PURCHASE, LISTING_INTERACTION. Default: IMPRESSIONS.
Optimization goaloptimization_goaltextRequired
What Meta optimizes delivery for.One of: NONE, IMPRESSIONS, REACH, LINK_CLICKS, LANDING_PAGE_VIEWS, POST_ENGAGEMENT, PAGE_LIKES, THRUPLAY, LEAD_GENERATION, OFFSITE_CONVERSIONS. Default: LINK_CLICKS.
CountriescountrieslistRequired
The countries to target, as two-letter codes such as US, GB or DE. At least one is required.Default: ["US"].
Statusstatustext
The status to create the ad set in.One of: ACTIVE, PAUSED, ARCHIVED. Default: PAUSED.
Bid strategybid_strategytext
How Meta bids. Lowest cost without cap lets Meta bid for you and needs no bid cap; the other two require one.One of: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP. Default: LOWEST_COST_WITHOUT_CAP.
Bid capbid_amountnumber
The most to pay per billing event, in the account's currency. Required for Lowest cost with bid cap and Cost cap; leave empty for Lowest cost without cap.
Start timestart_timedate and time
When the ad set should start delivering. Leave empty to start as soon as it is active.
End timeend_timedate and time
When the ad set should stop delivering. Leave empty to run until you pause it.

Outputs

ad_setobject
Example output
{
  "ad_set": {
    "account_id": "1234567890",
    "bid_amount": null,
    "billing_event": "IMPRESSIONS",
    "budget_remaining": 25.0,
    "campaign_id": "23851234567890123",
    "countries": [
      "US"
    ],
    "created_time": "2026-07-30T11:04:52-0700",
    "daily_budget": 25.0,
    "effective_status": "PAUSED",
    "end_time": "",
    "id": "23851234567890456",
    "lifetime_budget": null,
    "name": "US \u2014 broad",
    "optimization_goal": "LINK_CLICKS",
    "start_time": "2026-08-01T00:00:00-0700",
    "status": "PAUSED",
    "updated_time": "2026-08-02T08:41:03-0700"
  }
}

Delete a campaign

Delete a campaign along with every ad set and ad inside it. This cannot be undone: pause the campaign instead if you may want it back.

Inputs

Campaign IDcampaign_idtextRequired
The campaign to delete.

Outputs

campaign_idtext
The id that was deleted.
deletedtrue/false
Always true on success.
Example output
{
  "campaign_id": "23851234567890123",
  "deleted": true
}

Delete an ad

Delete an ad. This cannot be undone: pause it instead if you may want it back.

Inputs

Ad IDad_idtextRequired
The ad to delete.

Outputs

ad_idtext
The id that was deleted.
deletedtrue/false
Always true on success.
Example output
{
  "ad_id": "23851234567890789",
  "deleted": true
}

Delete an ad set

Delete an ad set and the ads inside it. This cannot be undone: pause it instead if you may want it back.

Inputs

Ad set IDad_set_idtextRequired
The ad set to delete.

Outputs

ad_set_idtext
The id that was deleted.
deletedtrue/false
Always true on success.
Example output
{
  "ad_set_id": "23851234567890456",
  "deleted": true
}

Get a campaign

Read one campaign's objective, status, budget and schedule.

Inputs

Campaign IDcampaign_idtextRequired
The campaign to read, as returned by List campaigns, for example, 23851234567890123.

Outputs

campaignobject
Example output
{
  "campaign": {
    "account_id": "1234567890",
    "budget_remaining": 25.0,
    "buying_type": "AUCTION",
    "created_time": "2026-07-30T11:02:19-0700",
    "daily_budget": 25.0,
    "effective_status": "PAUSED",
    "id": "23851234567890123",
    "lifetime_budget": null,
    "name": "Spring launch",
    "objective": "OUTCOME_TRAFFIC",
    "special_ad_categories": [],
    "start_time": "2026-08-01T00:00:00-0700",
    "status": "PAUSED",
    "stop_time": "",
    "updated_time": "2026-08-02T08:41:03-0700"
  }
}

Get account insights

Read impressions, reach, clicks, CTR and spend for a whole ad account over a chosen window, optionally broken out per campaign, ad set or ad.

Inputs

Ad accountad_account_idtextRequired
The ad account to report on.
Date rangedate_presettext
The reporting window. Defaults to the last 30 days.One of: today, yesterday, this_week_mon_today, this_week_sun_today, last_week_mon_sun, last_week_sun_sat, this_month, last_month, this_quarter, last_quarter, and 9 more. Default: last_30d.
Levelleveltext
How finely to cut the rows: one row for the account, or one per campaign, ad set or ad.One of: account, campaign, adset, ad.
Breakdownbreakdowntext
Optionally split each row by a dimension, such as age or country.One of: age, gender, country, publisher_platform, impression_device, device_platform.
Maximum resultsmax_resultsnumber
How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

countnumber
How many rows were returned.
date_presettext
The reporting window the figures cover.
insightslist
Example output
{
  "count": 1,
  "date_preset": "last_30d",
  "insights": [
    {
      "ad_id": "",
      "ad_name": "",
      "adset_id": "",
      "adset_name": "",
      "campaign_id": "23851234567890123",
      "campaign_name": "Spring launch",
      "clicks": 342.0,
      "cpc": 0.42,
      "cpm": 7.79,
      "ctr": 1.8556,
      "date_start": "2026-08-05",
      "date_stop": "2026-09-03",
      "frequency": 1.428,
      "impressions": 18432.0,
      "reach": 12907.0,
      "spend": 143.64
    }
  ]
}

Get an ad set

Read one ad set's budget, schedule, optimization goal and the countries it targets.

Inputs

Ad set IDad_set_idtextRequired
The ad set to read, as returned by List ad sets.

Outputs

ad_setobject
Example output
{
  "ad_set": {
    "account_id": "1234567890",
    "bid_amount": null,
    "billing_event": "IMPRESSIONS",
    "budget_remaining": 25.0,
    "campaign_id": "23851234567890123",
    "countries": [
      "US"
    ],
    "created_time": "2026-07-30T11:04:52-0700",
    "daily_budget": 25.0,
    "effective_status": "PAUSED",
    "end_time": "",
    "id": "23851234567890456",
    "lifetime_budget": null,
    "name": "US \u2014 broad",
    "optimization_goal": "LINK_CLICKS",
    "start_time": "2026-08-01T00:00:00-0700",
    "status": "PAUSED",
    "updated_time": "2026-08-02T08:41:03-0700"
  }
}

Get campaign insights

Read impressions, reach, clicks, CTR and spend for one campaign over a chosen window, optionally broken out per ad set or ad.

Inputs

Campaign IDcampaign_idtextRequired
The campaign to report on.
Date rangedate_presettext
The reporting window. Defaults to the last 30 days.One of: today, yesterday, this_week_mon_today, this_week_sun_today, last_week_mon_sun, last_week_sun_sat, this_month, last_month, this_quarter, last_quarter, and 9 more. Default: last_30d.
Levelleveltext
How finely to cut the rows: one row for the campaign, or one per ad set or ad.One of: account, campaign, adset, ad.
Breakdownbreakdowntext
Optionally split each row by a dimension, such as age or country.One of: age, gender, country, publisher_platform, impression_device, device_platform.
Maximum resultsmax_resultsnumber
How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

countnumber
How many rows were returned.
date_presettext
The reporting window the figures cover.
insightslist
Example output
{
  "count": 1,
  "date_preset": "last_30d",
  "insights": [
    {
      "ad_id": "",
      "ad_name": "",
      "adset_id": "",
      "adset_name": "",
      "campaign_id": "23851234567890123",
      "campaign_name": "Spring launch",
      "clicks": 342.0,
      "cpc": 0.42,
      "cpm": 7.79,
      "ctr": 1.8556,
      "date_start": "2026-08-05",
      "date_stop": "2026-09-03",
      "frequency": 1.428,
      "impressions": 18432.0,
      "reach": 12907.0,
      "spend": 143.64
    }
  ]
}

List ad accounts

List every Meta ad account the connected user can advertise on, with each account's currency, status and lifetime spend.

Inputs

Maximum resultsmax_resultsnumber
How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

ad_accountslist
countnumber
How many rows were returned.
Example output
{
  "ad_accounts": [
    {
      "account_id": "1234567890",
      "account_status": "1",
      "account_status_label": "ACTIVE",
      "amount_spent": 412.75,
      "balance": 0.0,
      "business_name": "Lodol Demo",
      "created_time": "2026-01-14T09:12:44+0000",
      "currency": "USD",
      "id": "act_1234567890",
      "name": "Lodol Demo Ads",
      "spend_cap": null,
      "timezone_name": "America/Los_Angeles"
    }
  ],
  "count": 1
}

List ad creatives

List the saved ad creatives in an ad account: the headline, body text and thumbnail each ad can run.

Inputs

Ad accountad_account_idtextRequired
The ad account whose creatives to list.
Maximum resultsmax_resultsnumber
How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

ad_creativeslist
countnumber
How many rows were returned.
Example output
{
  "ad_creatives": [
    {
      "account_id": "1234567890",
      "body": "Everything new, in one place.",
      "id": "23851234567891011",
      "name": "Spring launch creative",
      "status": "ACTIVE",
      "thumbnail_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/example.jpg",
      "title": "Spring collection"
    }
  ],
  "count": 1
}

List ad sets

List the ad sets in an ad account, or just the ones in a single campaign, with each ad set's budget and targeting.

Inputs

Ad accountad_account_idtextRequired
The ad account whose ad sets to list.
Campaign IDcampaign_idtext
Only list the ad sets in this campaign. Leave empty to list every ad set in the account.
Statusstatustext
Only return rows with this delivery status. Leave empty for all.One of: ACTIVE, PAUSED, ARCHIVED, DELETED.
Maximum resultsmax_resultsnumber
How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

ad_setslist
countnumber
How many rows were returned.
Example output
{
  "ad_sets": [
    {
      "account_id": "1234567890",
      "bid_amount": null,
      "billing_event": "IMPRESSIONS",
      "budget_remaining": 25.0,
      "campaign_id": "23851234567890123",
      "countries": [
        "US"
      ],
      "created_time": "2026-07-30T11:04:52-0700",
      "daily_budget": 25.0,
      "effective_status": "PAUSED",
      "end_time": "",
      "id": "23851234567890456",
      "lifetime_budget": null,
      "name": "US \u2014 broad",
      "optimization_goal": "LINK_CLICKS",
      "start_time": "2026-08-01T00:00:00-0700",
      "status": "PAUSED",
      "updated_time": "2026-08-02T08:41:03-0700"
    }
  ],
  "count": 1
}

List ads

List the ads in an ad account, or just the ones in a single ad set, with each ad's status and creative.

Inputs

Ad accountad_account_idtextRequired
The ad account whose ads to list.
Ad set IDad_set_idtext
Only list the ads in this ad set. Leave empty to list every ad in the account.
Statusstatustext
Only return rows with this delivery status. Leave empty for all.One of: ACTIVE, PAUSED, ARCHIVED, DELETED.
Maximum resultsmax_resultsnumber
How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

adslist
countnumber
How many rows were returned.
Example output
{
  "ads": [
    {
      "account_id": "1234567890",
      "adset_id": "23851234567890456",
      "campaign_id": "23851234567890123",
      "created_time": "2026-07-30T11:06:31-0700",
      "creative_id": "23851234567891011",
      "effective_status": "PAUSED",
      "id": "23851234567890789",
      "name": "Spring launch \u2014 link ad",
      "status": "PAUSED",
      "updated_time": "2026-08-02T08:41:03-0700"
    }
  ],
  "count": 1
}

List campaigns

List the campaigns in an ad account, with each campaign's objective, delivery status and budget.

Inputs

Ad accountad_account_idtextRequired
The ad account whose campaigns to list.
Statusstatustext
Only return rows with this delivery status. Leave empty for all.One of: ACTIVE, PAUSED, ARCHIVED, DELETED.
Maximum resultsmax_resultsnumber
How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

campaignslist
countnumber
How many rows were returned.
Example output
{
  "campaigns": [
    {
      "account_id": "1234567890",
      "budget_remaining": 25.0,
      "buying_type": "AUCTION",
      "created_time": "2026-07-30T11:02:19-0700",
      "daily_budget": 25.0,
      "effective_status": "PAUSED",
      "id": "23851234567890123",
      "lifetime_budget": null,
      "name": "Spring launch",
      "objective": "OUTCOME_TRAFFIC",
      "special_ad_categories": [],
      "start_time": "2026-08-01T00:00:00-0700",
      "status": "PAUSED",
      "stop_time": "",
      "updated_time": "2026-08-02T08:41:03-0700"
    }
  ],
  "count": 1
}

List Facebook Pages

List the Facebook Pages you manage, with the id each one needs when you create an ad creative. Pages you can run ads for are marked, because Meta refuses a creative naming a Page you cannot advertise for.

Inputs

Maximum resultsmax_resultsnumber
How many rows to return (1-500). Defaults to 25.From 1 to 500. Default: 25.

Outputs

countnumber
How many rows were returned.
pageslist
Example output
{
  "count": 1,
  "pages": [
    {
      "can_advertise": true,
      "category": "Software company",
      "id": "102938475610293",
      "name": "Lodol Demo Page",
      "tasks": [
        "ADVERTISE",
        "ANALYZE",
        "CREATE_CONTENT",
        "MANAGE",
        "MODERATE"
      ]
    }
  ]
}

Update a campaign

Rename a campaign, pause or resume it, or change its daily budget. Only the fields you fill in are changed.

Inputs

Campaign IDcampaign_idtextRequired
The campaign to update.
New namenametext
A new name for the campaign. Leave empty to keep it.
Statusstatustext
A new status. Leave empty to keep the current one.One of: ACTIVE, PAUSED, ARCHIVED.
Daily budgetdaily_budgetnumber
A new daily budget in the account's currency, for example, 25. Leave empty to keep the current budget.

Outputs

campaignobject
Example output
{
  "campaign": {
    "account_id": "1234567890",
    "budget_remaining": 25.0,
    "buying_type": "AUCTION",
    "created_time": "2026-07-30T11:02:19-0700",
    "daily_budget": 25.0,
    "effective_status": "PAUSED",
    "id": "23851234567890123",
    "lifetime_budget": null,
    "name": "Spring launch",
    "objective": "OUTCOME_TRAFFIC",
    "special_ad_categories": [],
    "start_time": "2026-08-01T00:00:00-0700",
    "status": "PAUSED",
    "stop_time": "",
    "updated_time": "2026-08-02T08:41:03-0700"
  }
}

Update an ad

Rename an ad, or pause or resume it. Only the fields you fill in are changed.

Inputs

Ad IDad_idtextRequired
The ad to update.
New namenametext
A new name for the ad. Leave empty to keep it.
Statusstatustext
A new status. Leave empty to keep the current one.One of: ACTIVE, PAUSED, ARCHIVED.

Outputs

adobject
Example output
{
  "ad": {
    "account_id": "1234567890",
    "adset_id": "23851234567890456",
    "campaign_id": "23851234567890123",
    "created_time": "2026-07-30T11:06:31-0700",
    "creative_id": "23851234567891011",
    "effective_status": "PAUSED",
    "id": "23851234567890789",
    "name": "Spring launch \u2014 link ad",
    "status": "PAUSED",
    "updated_time": "2026-08-02T08:41:03-0700"
  }
}

Update an ad set

Rename an ad set, pause or resume it, or change its daily budget. Only the fields you fill in are changed.

Inputs

Ad set IDad_set_idtextRequired
The ad set to update.
New namenametext
A new name for the ad set. Leave empty to keep it.
Statusstatustext
A new status. Leave empty to keep the current one.One of: ACTIVE, PAUSED, ARCHIVED.
Daily budgetdaily_budgetnumber
A new daily budget in the account's currency. Leave empty to keep the current budget.

Outputs

ad_setobject
Example output
{
  "ad_set": {
    "account_id": "1234567890",
    "bid_amount": null,
    "billing_event": "IMPRESSIONS",
    "budget_remaining": 25.0,
    "campaign_id": "23851234567890123",
    "countries": [
      "US"
    ],
    "created_time": "2026-07-30T11:04:52-0700",
    "daily_budget": 25.0,
    "effective_status": "PAUSED",
    "end_time": "",
    "id": "23851234567890456",
    "lifetime_budget": null,
    "name": "US \u2014 broad",
    "optimization_goal": "LINK_CLICKS",
    "start_time": "2026-08-01T00:00:00-0700",
    "status": "PAUSED",
    "updated_time": "2026-08-02T08:41:03-0700"
  }
}

On this page