Facebook — Business and ads

List granted permissions — facebook.list_permissions

Lists the permissions the connected Facebook user granted or declined to the app. Use to explain why another Facebook action failed with a permission error.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
limit	integer	no	Max items per page (1-100). Min 1. Max 100.
after	string	no	Cursor for the next page, from paging.cursors.after of the previous call.

Extra fields: ignored.

Output

Field	Type	Description
data	array of object
data[].permission	string
data[].status	string
paging	object
paging.cursors	object

List businesses — facebook.list_businesses

Lists Business Manager accounts the connected user belongs to (id, name). Use the id with list_owned_pages or list_owned_ad_accounts.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	business_management

Input

Field	Type	Required	Description
fields	string	no	Comma-separated Graph fields to return, e.g. "id,name"; empty uses the defaults.
limit	integer	no	Max items per page (1-100). Min 1. Max 100.
after	string	no	Cursor for the next page, from paging.cursors.after of the previous call.

Extra fields: ignored.

Output

Field	Type	Description
data	array of object
data[].id	string
data[].name	string
paging	object
paging.cursors	object

List business-owned Pages — facebook.list_owned_pages

Lists Pages owned by a Business Manager account. Requires the business id from list_businesses. Supports paging.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	business_management

Input

Field	Type	Required	Description
business_id	string	yes	Business Manager id. From facebook.list_businesses.
fields	string	no	Comma-separated Graph fields to return, e.g. "id,name"; empty uses the defaults.
limit	integer	no	Max items per page (1-100). Min 1. Max 100.
after	string	no	Cursor for the next page, from paging.cursors.after of the previous call.

Extra fields: ignored.

Output

Field	Type	Description
data	array of object
data[].id	string
data[].name	string
data[].category	string
paging	object
paging.cursors	object

List business client Pages — facebook.list_client_pages

Lists Pages that clients shared with a Business Manager account. Requires the business id from list_businesses. Supports paging.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	business_management

Input

Field	Type	Required	Description
business_id	string	yes	Business Manager id. From facebook.list_businesses.
fields	string	no	Comma-separated Graph fields to return, e.g. "id,name"; empty uses the defaults.
limit	integer	no	Max items per page (1-100). Min 1. Max 100.
after	string	no	Cursor for the next page, from paging.cursors.after of the previous call.

Extra fields: ignored.

Output

Field	Type	Description
data	array of object
data[].id	string
data[].name	string
data[].category	string
paging	object
paging.cursors	object

List ad accounts — facebook.list_ad_accounts

Lists ad accounts the connected user can access (id like act_123, name, status, currency). Use the id as parent for list_ads or get_ad_insights.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	ads_read

Input

Field	Type	Required	Description
fields	string	no	Comma-separated Graph fields to return, e.g. "id,name"; empty uses the defaults.
limit	integer	no	Max items per page (1-100). Min 1. Max 100.
after	string	no	Cursor for the next page, from paging.cursors.after of the previous call.

Extra fields: ignored.

Output

Field	Type	Description
data	array of object
data[].id	string
data[].name	string
data[].account_status	integer
data[].currency	string
paging	object
paging.cursors	object

List business-owned ad accounts — facebook.list_owned_ad_accounts

Lists ad accounts owned by a Business Manager account. Requires the business id from list_businesses. Supports paging.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	ads_read, business_management

Input

Field	Type	Required	Description
business_id	string	yes	Business Manager id. From facebook.list_businesses.
fields	string	no	Comma-separated Graph fields to return, e.g. "id,name"; empty uses the defaults.
limit	integer	no	Max items per page (1-100). Min 1. Max 100.
after	string	no	Cursor for the next page, from paging.cursors.after of the previous call.

Extra fields: ignored.

Output

Field	Type	Description
data	array of object
data[].id	string
data[].name	string
data[].account_status	integer
data[].currency	string
paging	object
paging.cursors	object

List ads — facebook.list_ads

Lists ads under an ad account (act_...), campaign or ad set. effective_status filters, e.g. ["ACTIVE","PAUSED"]. Supports paging.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	ads_read

Input

Field	Type	Required	Description
parent_id	string	yes	Ad account id (act_<id>), campaign id or ad set id. From facebook.list_ad_accounts.
fields	string	no	Comma-separated Graph fields to return, e.g. "id,name"; empty uses the defaults.
effective_status	string	no	JSON array string of ad statuses to keep, e.g. ["ACTIVE","PAUSED"].
limit	integer	no	Max items per page (1-100). Min 1. Max 100.
after	string	no	Cursor for the next page, from paging.cursors.after of the previous call.

Extra fields: ignored.

Output

Field	Type	Description
data	array of object
data[].id	string
data[].name	string
data[].status	string
data[].effective_status	string
paging	object
paging.cursors	object

Get ad insights — facebook.get_ad_insights

Reads ad performance for an ad account, campaign, ad set or ad. Choose fields (impressions,spend,clicks), date_preset, time_range, level, breakdowns. time_range is a JSON string like {"since":"YYYY-MM-DD","until":"YYYY-MM-DD"}.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	ads_read

Input

Field	Type	Required	Description
object_id	string	yes	Ad account (act_<id>), campaign, ad set or ad id. From facebook.list_ad_accounts.
fields	string	no	Comma-separated insight fields, e.g. "impressions,spend,clicks".
date_preset	string	no	Relative date range; default last_30d. Ignored when time_range is set. One of: today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year.
time_range	string	no	JSON string like
level	string	no	Level to aggregate results at; defaults to the level of object_id. One of: ad, adset, campaign, account.
breakdowns	string	no	Comma-separated breakdowns, e.g. "age,gender" or "publisher_platform".
limit	integer	no	Max items per page (1-100). Min 1. Max 100.
after	string	no	Cursor for the next page, from paging.cursors.after of the previous call.

Extra fields: ignored.

Output

Field	Type	Description
data	array of object
data[].impressions	string
data[].clicks	string
data[].spend	string
data[].date_start	string
data[].date_stop	string
paging	object
paging.cursors	object

Search targeting locations — facebook.search_geographic_targeting_locations

Searches geographic locations usable in ad targeting by keyword q. location_types limits to country, region, city, etc. Returns keys for targeting specs. location_types is a JSON array string like ["city","region"].

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	ads_read

Input

Field	Type	Required	Description
q	string	yes	Location name to search, e.g. "Hanoi".
location_types	string	no	JSON array string of types, e.g. ["city","region"]; country, region, city, zip, geo_market, electoral_district.
limit	integer	no	Max items per page (1-100). Min 1. Max 100.
after	string	no	Cursor for the next page, from paging.cursors.after of the previous call.

Extra fields: ignored.

Output

Field	Type	Description
data	array of object
data[].key	string
data[].name	string
data[].type	string
data[].country_code	string
paging	object
paging.cursors	object

Get current user — facebook.get_current_user

Reads the connected Facebook user profile (id, name). Use to confirm which account is connected. Pass fields to request more.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
fields	string	no	Comma-separated Graph fields to return, e.g. "id,name"; empty uses the defaults.

Extra fields: ignored.

Output

Field	Type	Description
id	string
name	string

Get Graph object — facebook.get_graph_object

Reads any Graph node by id (digits, 123_456, me or act_<id>). Pass fields to choose properties and page_id to use that Page's token.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
node_id	string	yes	Graph node id: digits, "123_456", "me" or "act_<id>".
fields	string	no	Comma-separated Graph fields to return, e.g. "id,name"; empty uses the defaults.
page_id	string	no	Page whose token is used to read; empty uses the user token. From facebook.list_managed_pages.

Extra fields: ignored.

Output

Field	Type	Description
id	string

Get Graph objects — facebook.get_graph_objects

Reads 1-50 Graph nodes by id in one call. Returns an objects map keyed by id. Pass page_id to use that Page's token.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
ids	array of string	yes	Graph node ids (1-50), e.g. ["123", "123_456"].
fields	string	no	Comma-separated Graph fields to return, e.g. "id,name"; empty uses the defaults.
page_id	string	no	Page whose token is used to read; empty uses the user token. From facebook.list_managed_pages.

Extra fields: ignored.

Output

Field	Type	Description
objects	object