Integrations / Meta Ads

Meta Ads

Meta Marketing API for Facebook and Instagram ads: list ad accounts, campaigns, ad sets and ads, pull performance insights, pause or activate campaigns.

8 actions OAuth 2 7 read1 write Calls graph.facebook.com

Connect

TypeScript

const conn = await setu.connections.initiate({ userId: "user_1", toolkit: "metaads" });
console.log(conn.connectUrl); // show this to your user
await conn.waitUntilActive();

Permissions requested

Scope	Why it is requested
`public_profile`	Read your name and ID so Setu can label the connection
`ads_read`	Read your ad accounts, campaigns, ads and performance reports
`ads_management`	Pause or activate campaigns in your ad accounts

Actions

Get ad accountreadmetaads.get_ad_accountRead one ad account: name, status (1 active, 2 disabled, ...), currency and time zone.

Needs scope: ads_read

Input	Type		Description
`ad_account_id`	string	Required	Ad account id including the act_ prefix, e.g. act_1234567890

TypeScript

await setu.execute({
  userId: "user_1",
  action: "metaads.get_ad_account",
  input: {
    "ad_account_id": "<ad_account_id>"
  },
});

Get campaignreadmetaads.get_campaignRead one campaign: name, objective, status, budgets, start and stop times.

Needs scope: ads_read

Input	Type		Description
`campaign_id`	string	Required	Campaign id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "metaads.get_campaign",
  input: {
    "campaign_id": "<campaign_id>"
  },
});

Get ads insightsreadmetaads.get_insightsPerformance report for an ad account, campaign, ad set or ad: choose metric fields (impressions, spend, clicks, ctr, ...), a date_preset such as last_7d, and a level to split by campaign/adset/ad.

Needs scope: ads_read

Input	Type		Description
`object_id`	string	Required	act_ ad account id, or a campaign, ad set or ad id
`fields`	string	Optional	Comma-separated metrics, e.g. impressions,spend,clicks,ctr,cpc,reach
`date_preset`	string	Optional	e.g. today, yesterday, last_7d, last_30d, this_month, last_month, maximum
`time_range`	string	Optional	Instead of date_preset: JSON like {"since":"2026-01-01","until":"2026-01-31"}
`level`	string	Optional	account, campaign, adset or ad
`breakdowns`	string	Optional	Optional, e.g. age,gender or publisher_platform
`limit`	integer	Optional	Maximum rows

TypeScript

await setu.execute({
  userId: "user_1",
  action: "metaads.get_insights",
  input: {
    "object_id": "<object_id>"
  },
});

List ad accountsreadmetaads.list_ad_accountsList the ad accounts the connected person can access (id, name, status, currency, time zone). Account ids start with act_.

Needs scope: ads_read

Input	Type		Description
`limit`	integer	Optional	Maximum accounts to return

TypeScript

await setu.execute({
  userId: "user_1",
  action: "metaads.list_ad_accounts",
  input: {},
});

List ad setsreadmetaads.list_ad_setsList ad sets in an ad account with name, parent campaign, status and budgets.

Needs scope: ads_read

Input	Type		Description
`ad_account_id`	string	Required	Ad account id including the act_ prefix, e.g. act_1234567890
`effective_status`	string	Optional	Optional JSON list of statuses, e.g. ["ACTIVE","PAUSED"]
`limit`	integer	Optional	Maximum ad sets to return

TypeScript

await setu.execute({
  userId: "user_1",
  action: "metaads.list_ad_sets",
  input: {
    "ad_account_id": "<ad_account_id>"
  },
});

List adsreadmetaads.list_adsList ads in an ad account with name, ad set, campaign and status.

Needs scope: ads_read

Input	Type		Description
`ad_account_id`	string	Required	Ad account id including the act_ prefix, e.g. act_1234567890
`effective_status`	string	Optional	Optional JSON list of statuses, e.g. ["ACTIVE","PAUSED"]
`limit`	integer	Optional	Maximum ads to return

TypeScript

await setu.execute({
  userId: "user_1",
  action: "metaads.list_ads",
  input: {
    "ad_account_id": "<ad_account_id>"
  },
});

List campaignsreadmetaads.list_campaignsList campaigns in an ad account with name, objective, status and budgets. Without a filter, archived and deleted campaigns are left out.

Needs scope: ads_read

Input	Type		Description
`ad_account_id`	string	Required	Ad account id including the act_ prefix, e.g. act_1234567890
`effective_status`	string	Optional	Optional JSON list of statuses, e.g. ["ACTIVE","PAUSED"]
`limit`	integer	Optional	Maximum campaigns to return

TypeScript

await setu.execute({
  userId: "user_1",
  action: "metaads.list_campaigns",
  input: {
    "ad_account_id": "<ad_account_id>"
  },
});

Pause or activate campaignwritemetaads.set_campaign_statusSet a campaign to PAUSED or ACTIVE. Activating can start spending money immediately.

Needs scope: ads_management

Input	Type		Description
`campaign_id`	string	Required	Campaign id
`status`	string	Required	New status

TypeScript

await setu.execute({
  userId: "user_1",
  action: "metaads.set_campaign_status",
  input: {
    "campaign_id": "<campaign_id>",
    "status": "<status>"
  },
});