How do I install the Facebook-Marketing full reference skill?

Run npx skillmds@latest add tools-only/facebook-marketing-full-reference in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Facebook-Marketing full reference skill do?

This is the full reference documentation for the Facebook-Marketing agent connector. It is listed under Marketing & Growth on SkillMD.

Is Facebook-Marketing full reference safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Facebook-Marketing full reference?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Facebook-Marketing full reference free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Facebook-Marketing full reference?

tools-only (@tools-only) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Facebook-Marketing full reference by tools-only

Name: Facebook-Marketing full reference
Author: tools-only

Facebook-Marketing full reference

This is the full reference documentation for the Facebook-Marketing agent connector.

Supported entities and actions

The Facebook-Marketing connector supports the following entities and actions.

Entity	Actions
Current User	Get
Ad Accounts	List, Search
Campaigns	List, Get, Search
Ad Sets	List, Get, Search
Ads	List, Get, Search
Ad Creatives	List, Search
Ads Insights	List, Search
Ad Account	Get, Search
Custom Conversions	List, Search
Images	List, Search
Videos	List, Search

Current User

Current User Get

Returns information about the current user associated with the access token

Python SDK

await facebook_marketing.current_user.get()

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "current_user",
    "action": "get"
}'

Parameters

Parameter Name	Type	Required	Description
`fields`	`string`	No	Comma-separated list of fields to return

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`

Ad Accounts

Ad Accounts List

Returns a list of ad accounts associated with the current user

Python SDK

await facebook_marketing.ad_accounts.list()

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_accounts",
    "action": "list"
}'

Parameters

Parameter Name	Type	Required	Description
`fields`	`string`	No	Comma-separated list of fields to return
`limit`	`integer`	No	Maximum number of results to return
`after`	`string`	No	Cursor for pagination

Records

Field Name	Type	Description
`id`	`string`
`account_id`	`string \| null`
`name`	`string \| null`
`account_status`	`integer \| null`
`age`	`number \| null`
`amount_spent`	`string \| null`
`balance`	`string \| null`
`business`	`object \| any`
`business_name`	`string \| null`
`created_time`	`string \| null`
`currency`	`string \| null`
`disable_reason`	`integer \| null`
`spend_cap`	`string \| null`
`timezone_id`	`integer \| null`
`timezone_name`	`string \| null`

Meta

Field Name	Type	Description
`after`	`string \| null`

Ad Accounts Search

Search and filter ad accounts records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await facebook_marketing.ad_accounts.search(
    query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_accounts",
    "action": "search",
    "params": {
        "query": {"filter": {"eq": {"id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's next_cursor
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`id`	`string`	Ad account ID
`account_id`	`string`	Ad account ID (numeric)
`name`	`string`	Ad account name
`balance`	`string`	Current balance of the ad account
`currency`	`string`	Currency used by the ad account
`account_status`	`integer`	Account status
`amount_spent`	`string`	Total amount spent
`business_name`	`string`	Business name
`created_time`	`string`	Account creation time
`spend_cap`	`string`	Spend cap
`timezone_name`	`string`	Timezone name

Field Name	Type	Description
`hits`	`array`	List of matching records
`hits[].id`	`string`	Record identifier
`hits[].score`	`number`	Relevance score
`hits[].data`	`object`	Record data containing the searchable fields listed above
`hits[].data.id`	`string`	Ad account ID
`hits[].data.account_id`	`string`	Ad account ID (numeric)
`hits[].data.name`	`string`	Ad account name
`hits[].data.balance`	`string`	Current balance of the ad account
`hits[].data.currency`	`string`	Currency used by the ad account
`hits[].data.account_status`	`integer`	Account status
`hits[].data.amount_spent`	`string`	Total amount spent
`hits[].data.business_name`	`string`	Business name
`hits[].data.created_time`	`string`	Account creation time
`hits[].data.spend_cap`	`string`	Spend cap
`hits[].data.timezone_name`	`string`	Timezone name
`next_cursor`	`string \| null`	Cursor for next page of results
`took_ms`	`number`	Query execution time in milliseconds

Campaigns

Campaigns List

Returns a list of campaigns for the specified ad account

Python SDK

await facebook_marketing.campaigns.list(
    account_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "campaigns",
    "action": "list",
    "params": {
        "account_id": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`account_id`	`string`	Yes	The Facebook Ad Account ID (without act_ prefix)
`fields`	`string`	No	Comma-separated list of fields to return
`limit`	`integer`	No	Maximum number of results to return
`after`	`string`	No	Cursor for pagination

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`account_id`	`string \| null`
`adlabels`	`array \| null`
`adlabels[].id`	`string \| null`
`adlabels[].name`	`string \| null`
`adlabels[].created_time`	`string \| null`
`adlabels[].updated_time`	`string \| null`
`bid_strategy`	`string \| null`
`boosted_object_id`	`string \| null`
`budget_rebalance_flag`	`boolean \| null`
`budget_remaining`	`number \| null`
`buying_type`	`string \| null`
`daily_budget`	`number \| null`
`created_time`	`string \| null`
`configured_status`	`string \| null`
`effective_status`	`string \| null`
`issues_info`	`array \| null`
`issues_info[].error_code`	`string \| null`
`issues_info[].error_message`	`string \| null`
`issues_info[].error_summary`	`string \| null`
`issues_info[].error_type`	`string \| null`
`issues_info[].level`	`string \| null`
`lifetime_budget`	`number \| null`
`objective`	`string \| null`
`smart_promotion_type`	`string \| null`
`source_campaign_id`	`string \| null`
`special_ad_category`	`string \| null`
`special_ad_category_country`	`array \| null`
`spend_cap`	`number \| null`
`start_time`	`string \| null`
`status`	`string \| null`
`stop_time`	`string \| null`
`updated_time`	`string \| null`

Meta

Field Name	Type	Description
`after`	`string \| null`

Campaigns Get

Returns a single campaign by ID

Python SDK

await facebook_marketing.campaigns.get(
    campaign_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "campaigns",
    "action": "get",
    "params": {
        "campaign_id": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`campaign_id`	`string`	Yes	The campaign ID
`fields`	`string`	No	Comma-separated list of fields to return

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`account_id`	`string \| null`
`adlabels`	`array \| null`
`adlabels[].id`	`string \| null`
`adlabels[].name`	`string \| null`
`adlabels[].created_time`	`string \| null`
`adlabels[].updated_time`	`string \| null`
`bid_strategy`	`string \| null`
`boosted_object_id`	`string \| null`
`budget_rebalance_flag`	`boolean \| null`
`budget_remaining`	`number \| null`
`buying_type`	`string \| null`
`daily_budget`	`number \| null`
`created_time`	`string \| null`
`configured_status`	`string \| null`
`effective_status`	`string \| null`
`issues_info`	`array \| null`
`issues_info[].error_code`	`string \| null`
`issues_info[].error_message`	`string \| null`
`issues_info[].error_summary`	`string \| null`
`issues_info[].error_type`	`string \| null`
`issues_info[].level`	`string \| null`
`lifetime_budget`	`number \| null`
`objective`	`string \| null`
`smart_promotion_type`	`string \| null`
`source_campaign_id`	`string \| null`
`special_ad_category`	`string \| null`
`special_ad_category_country`	`array \| null`
`spend_cap`	`number \| null`
`start_time`	`string \| null`
`status`	`string \| null`
`stop_time`	`string \| null`
`updated_time`	`string \| null`

Campaigns Search

Search and filter campaigns records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await facebook_marketing.campaigns.search(
    query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "campaigns",
    "action": "search",
    "params": {
        "query": {"filter": {"eq": {"id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's next_cursor
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`id`	`string`	Campaign ID
`name`	`string`	Campaign name
`account_id`	`string`	Ad account ID
`status`	`string`	Campaign status
`effective_status`	`string`	Effective status
`objective`	`string`	Campaign objective
`daily_budget`	`number`	Daily budget in account currency
`lifetime_budget`	`number`	Lifetime budget
`budget_remaining`	`number`	Remaining budget
`created_time`	`string`	Campaign creation time
`start_time`	`string`	Campaign start time
`stop_time`	`string`	Campaign stop time
`updated_time`	`string`	Last update time

Field Name	Type	Description
`hits`	`array`	List of matching records
`hits[].id`	`string`	Record identifier
`hits[].score`	`number`	Relevance score
`hits[].data`	`object`	Record data containing the searchable fields listed above
`hits[].data.id`	`string`	Campaign ID
`hits[].data.name`	`string`	Campaign name
`hits[].data.account_id`	`string`	Ad account ID
`hits[].data.status`	`string`	Campaign status
`hits[].data.effective_status`	`string`	Effective status
`hits[].data.objective`	`string`	Campaign objective
`hits[].data.daily_budget`	`number`	Daily budget in account currency
`hits[].data.lifetime_budget`	`number`	Lifetime budget
`hits[].data.budget_remaining`	`number`	Remaining budget
`hits[].data.created_time`	`string`	Campaign creation time
`hits[].data.start_time`	`string`	Campaign start time
`hits[].data.stop_time`	`string`	Campaign stop time
`hits[].data.updated_time`	`string`	Last update time
`next_cursor`	`string \| null`	Cursor for next page of results
`took_ms`	`number`	Query execution time in milliseconds

Ad Sets

Ad Sets List

Returns a list of ad sets for the specified ad account

Python SDK

await facebook_marketing.ad_sets.list(
    account_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_sets",
    "action": "list",
    "params": {
        "account_id": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`account_id`	`string`	Yes	The Facebook Ad Account ID (without act_ prefix)
`fields`	`string`	No	Comma-separated list of fields to return
`limit`	`integer`	No	Maximum number of results to return
`after`	`string`	No	Cursor for pagination

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`account_id`	`string \| null`
`adlabels`	`array \| null`
`adlabels[].id`	`string \| null`
`adlabels[].name`	`string \| null`
`adlabels[].created_time`	`string \| null`
`adlabels[].updated_time`	`string \| null`
`bid_amount`	`number \| null`
`bid_info`	`object \| any`
`bid_strategy`	`string \| null`
`bid_constraints`	`object \| any`
`budget_remaining`	`number \| null`
`campaign_id`	`string \| null`
`created_time`	`string \| null`
`daily_budget`	`number \| null`
`effective_status`	`string \| null`
`end_time`	`string \| null`
`learning_stage_info`	`object \| any`
`lifetime_budget`	`number \| null`
`promoted_object`	`object \| any`
`start_time`	`string \| null`
`targeting`	`object \| null`
`updated_time`	`string \| null`

Meta

Field Name	Type	Description
`after`	`string \| null`

Ad Sets Get

Returns a single ad set by ID

Python SDK

await facebook_marketing.ad_sets.get(
    adset_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_sets",
    "action": "get",
    "params": {
        "adset_id": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`adset_id`	`string`	Yes	The ad set ID
`fields`	`string`	No	Comma-separated list of fields to return

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`account_id`	`string \| null`
`adlabels`	`array \| null`
`adlabels[].id`	`string \| null`
`adlabels[].name`	`string \| null`
`adlabels[].created_time`	`string \| null`
`adlabels[].updated_time`	`string \| null`
`bid_amount`	`number \| null`
`bid_info`	`object \| any`
`bid_strategy`	`string \| null`
`bid_constraints`	`object \| any`
`budget_remaining`	`number \| null`
`campaign_id`	`string \| null`
`created_time`	`string \| null`
`daily_budget`	`number \| null`
`effective_status`	`string \| null`
`end_time`	`string \| null`
`learning_stage_info`	`object \| any`
`lifetime_budget`	`number \| null`
`promoted_object`	`object \| any`
`start_time`	`string \| null`
`targeting`	`object \| null`
`updated_time`	`string \| null`

Ad Sets Search

Search and filter ad sets records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await facebook_marketing.ad_sets.search(
    query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_sets",
    "action": "search",
    "params": {
        "query": {"filter": {"eq": {"id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's next_cursor
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`id`	`string`	Ad Set ID
`name`	`string`	Ad Set name
`account_id`	`string`	Ad account ID
`campaign_id`	`string`	Parent campaign ID
`effective_status`	`string`	Effective status
`daily_budget`	`number`	Daily budget
`lifetime_budget`	`number`	Lifetime budget
`budget_remaining`	`number`	Remaining budget
`bid_amount`	`number`	Bid amount
`bid_strategy`	`string`	Bid strategy
`created_time`	`string`	Ad set creation time
`start_time`	`string`	Ad set start time
`end_time`	`string`	Ad set end time
`updated_time`	`string`	Last update time

Field Name	Type	Description
`hits`	`array`	List of matching records
`hits[].id`	`string`	Record identifier
`hits[].score`	`number`	Relevance score
`hits[].data`	`object`	Record data containing the searchable fields listed above
`hits[].data.id`	`string`	Ad Set ID
`hits[].data.name`	`string`	Ad Set name
`hits[].data.account_id`	`string`	Ad account ID
`hits[].data.campaign_id`	`string`	Parent campaign ID
`hits[].data.effective_status`	`string`	Effective status
`hits[].data.daily_budget`	`number`	Daily budget
`hits[].data.lifetime_budget`	`number`	Lifetime budget
`hits[].data.budget_remaining`	`number`	Remaining budget
`hits[].data.bid_amount`	`number`	Bid amount
`hits[].data.bid_strategy`	`string`	Bid strategy
`hits[].data.created_time`	`string`	Ad set creation time
`hits[].data.start_time`	`string`	Ad set start time
`hits[].data.end_time`	`string`	Ad set end time
`hits[].data.updated_time`	`string`	Last update time
`next_cursor`	`string \| null`	Cursor for next page of results
`took_ms`	`number`	Query execution time in milliseconds

Ads List

Returns a list of ads for the specified ad account

Python SDK

await facebook_marketing.ads.list(
    account_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ads",
    "action": "list",
    "params": {
        "account_id": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`account_id`	`string`	Yes	The Facebook Ad Account ID (without act_ prefix)
`fields`	`string`	No	Comma-separated list of fields to return
`limit`	`integer`	No	Maximum number of results to return
`after`	`string`	No	Cursor for pagination

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`account_id`	`string \| null`
`adset_id`	`string \| null`
`campaign_id`	`string \| null`
`adlabels`	`array \| null`
`adlabels[].id`	`string \| null`
`adlabels[].name`	`string \| null`
`adlabels[].created_time`	`string \| null`
`adlabels[].updated_time`	`string \| null`
`bid_amount`	`integer \| null`
`bid_info`	`object \| any`
`bid_type`	`string \| null`
`configured_status`	`string \| null`
`conversion_specs`	`array \| null`
`created_time`	`string \| null`
`creative`	`object \| any`
`effective_status`	`string \| null`
`last_updated_by_app_id`	`string \| null`
`recommendations`	`array \| null`
`recommendations[].blame_field`	`string \| null`
`recommendations[].code`	`integer \| null`
`recommendations[].confidence`	`string \| null`
`recommendations[].importance`	`string \| null`
`recommendations[].message`	`string \| null`
`recommendations[].title`	`string \| null`
`source_ad_id`	`string \| null`
`status`	`string \| null`
`tracking_specs`	`array \| null`
`updated_time`	`string \| null`

Meta

Field Name	Type	Description
`after`	`string \| null`

Ads Get

Returns a single ad by ID

Python SDK

await facebook_marketing.ads.get(
    ad_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ads",
    "action": "get",
    "params": {
        "ad_id": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`ad_id`	`string`	Yes	The ad ID
`fields`	`string`	No	Comma-separated list of fields to return

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`account_id`	`string \| null`
`adset_id`	`string \| null`
`campaign_id`	`string \| null`
`adlabels`	`array \| null`
`adlabels[].id`	`string \| null`
`adlabels[].name`	`string \| null`
`adlabels[].created_time`	`string \| null`
`adlabels[].updated_time`	`string \| null`
`bid_amount`	`integer \| null`
`bid_info`	`object \| any`
`bid_type`	`string \| null`
`configured_status`	`string \| null`
`conversion_specs`	`array \| null`
`created_time`	`string \| null`
`creative`	`object \| any`
`effective_status`	`string \| null`
`last_updated_by_app_id`	`string \| null`
`recommendations`	`array \| null`
`recommendations[].blame_field`	`string \| null`
`recommendations[].code`	`integer \| null`
`recommendations[].confidence`	`string \| null`
`recommendations[].importance`	`string \| null`
`recommendations[].message`	`string \| null`
`recommendations[].title`	`string \| null`
`source_ad_id`	`string \| null`
`status`	`string \| null`
`tracking_specs`	`array \| null`
`updated_time`	`string \| null`

Ads Search

Search and filter ads records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await facebook_marketing.ads.search(
    query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ads",
    "action": "search",
    "params": {
        "query": {"filter": {"eq": {"id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's next_cursor
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`id`	`string`	Ad ID
`name`	`string`	Ad name
`account_id`	`string`	Ad account ID
`adset_id`	`string`	Parent ad set ID
`campaign_id`	`string`	Parent campaign ID
`status`	`string`	Ad status
`effective_status`	`string`	Effective status
`created_time`	`string`	Ad creation time
`updated_time`	`string`	Last update time

Field Name	Type	Description
`hits`	`array`	List of matching records
`hits[].id`	`string`	Record identifier
`hits[].score`	`number`	Relevance score
`hits[].data`	`object`	Record data containing the searchable fields listed above
`hits[].data.id`	`string`	Ad ID
`hits[].data.name`	`string`	Ad name
`hits[].data.account_id`	`string`	Ad account ID
`hits[].data.adset_id`	`string`	Parent ad set ID
`hits[].data.campaign_id`	`string`	Parent campaign ID
`hits[].data.status`	`string`	Ad status
`hits[].data.effective_status`	`string`	Effective status
`hits[].data.created_time`	`string`	Ad creation time
`hits[].data.updated_time`	`string`	Last update time
`next_cursor`	`string \| null`	Cursor for next page of results
`took_ms`	`number`	Query execution time in milliseconds

Ad Creatives

Ad Creatives List

Returns a list of ad creatives for the specified ad account

Python SDK

await facebook_marketing.ad_creatives.list(
    account_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_creatives",
    "action": "list",
    "params": {
        "account_id": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`account_id`	`string`	Yes	The Facebook Ad Account ID (without act_ prefix)
`fields`	`string`	No	Comma-separated list of fields to return
`limit`	`integer`	No	Maximum number of results to return
`after`	`string`	No	Cursor for pagination

Records

Field Name	Type	Description
`id`	`string`
`name`	`string \| null`
`account_id`	`string \| null`
`actor_id`	`string \| null`
`body`	`string \| null`
`call_to_action_type`	`string \| null`
`effective_object_story_id`	`string \| null`
`image_hash`	`string \| null`
`image_url`	`string \| null`
`link_url`	`string \| null`
`object_story_id`	`string \| null`
`object_story_spec`	`object \| null`
`object_type`	`string \| null`
`status`	`string \| null`
`thumbnail_url`	`string \| null`
`title`	`string \| null`
`url_tags`	`string \| null`

Meta

Field Name	Type	Description
`after`	`string \| null`

Ad Creatives Search

Search and filter ad creatives records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await facebook_marketing.ad_creatives.search(
    query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_creatives",
    "action": "search",
    "params": {
        "query": {"filter": {"eq": {"id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's next_cursor
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`id`	`string`	Ad Creative ID
`name`	`string`	Ad Creative name
`account_id`	`string`	Ad account ID
`body`	`string`	Ad body text
`title`	`string`	Ad title
`status`	`string`	Creative status
`image_url`	`string`	Image URL
`thumbnail_url`	`string`	Thumbnail URL
`link_url`	`string`	Link URL
`call_to_action_type`	`string`	Call to action type

Field Name	Type	Description
`hits`	`array`	List of matching records
`hits[].id`	`string`	Record identifier
`hits[].score`	`number`	Relevance score
`hits[].data`	`object`	Record data containing the searchable fields listed above
`hits[].data.id`	`string`	Ad Creative ID
`hits[].data.name`	`string`	Ad Creative name
`hits[].data.account_id`	`string`	Ad account ID
`hits[].data.body`	`string`	Ad body text
`hits[].data.title`	`string`	Ad title
`hits[].data.status`	`string`	Creative status
`hits[].data.image_url`	`string`	Image URL
`hits[].data.thumbnail_url`	`string`	Thumbnail URL
`hits[].data.link_url`	`string`	Link URL
`hits[].data.call_to_action_type`	`string`	Call to action type
`next_cursor`	`string \| null`	Cursor for next page of results
`took_ms`	`number`	Query execution time in milliseconds

Ads Insights

Ads Insights List

Returns performance insights for the specified ad account

Python SDK

await facebook_marketing.ads_insights.list(
    account_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ads_insights",
    "action": "list",
    "params": {
        "account_id": "<str>"
    }
}'

Parameters

Parameter Name	Type	Required	Description
`account_id`	`string`	Yes	The Facebook Ad Account ID (without act_ prefix)
`fields`	`string`	No	Comma-separated list of fields to return
`date_preset`	`"today" \| "yesterday" \| "this_month" \| "last_month" \| "this_quarter" \| "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"`	No	Predefined date range
`time_range`	`string`	No	Time range as JSON object with since and until dates (YYYY-MM-DD)
`level`	`"ad" \| "adset" \| "campaign" \| "account"`	No	Level of aggregation
`time_increment`	`string`	No	Number of days (1-90) to aggregate data over, or 'monthly' for monthly aggregation, or 'all_days' for daily breakdown. Use time_increment=1 to get daily insights data.
`limit`	`integer`	No	Maximum number of results to return
`after`	`string`	No	Cursor for pagination

Records

Field Name	Type	Description
`account_id`	`string \| null`
`account_name`	`string \| null`
`campaign_id`	`string \| null`
`campaign_name`	`string \| null`
`adset_id`	`string \| null`
`adset_name`	`string \| null`
`ad_id`	`string \| null`
`ad_name`	`string \| null`
`clicks`	`integer \| null`
`impressions`	`integer \| null`
`reach`	`integer \| null`
`spend`	`number \| null`
`cpc`	`number \| null`
`cpm`	`number \| null`
`ctr`	`number \| null`
`date_start`	`string \| null`
`date_stop`	`string \| null`
`actions`	`array \| null`
`actions[].action_type`	`string \| null`
`actions[].action_destination`	`string \| null`
`actions[].action_target_id`	`string \| null`
`actions[].value`	`number \| null`
`actions[].1d_click`	`number \| null`
`actions[].7d_click`	`number \| null`
`actions[].28d_click`	`number \| null`
`actions[].1d_view`	`number \| null`
`actions[].7d_view`	`number \| null`
`actions[].28d_view`	`number \| null`
`action_values`	`array \| null`
`action_values[].action_type`	`string \| null`
`action_values[].action_destination`	`string \| null`
`action_values[].action_target_id`	`string \| null`
`action_values[].value`	`number \| null`
`action_values[].1d_click`	`number \| null`
`action_values[].7d_click`	`number \| null`
`action_values[].28d_click`	`number \| null`
`action_values[].1d_view`	`number \| null`
`action_values[].7d_view`	`number \| null`
`action_values[].28d_view`	`number \| null`

Meta

Field Name	Type	Description
`after`	`string \| null`

Ads Insights Search

Search and filter ads insights records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await facebook_marketing.ads_insights.search(
    query={"filter": {"eq": {"account_id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ads_insights",
    "action": "search",
    "params": {
        "query": {"filter": {"eq": {"account_id": "<str>"}}}
    }
}'

Parameters

Parameter Name	Type	Required	Description
`query`	`object`	Yes	Filter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
`query.filter`	`object`	No	Filter conditions
`query.sort`	`array`	No	Sort conditions
`limit`	`integer`	No	Maximum results to return (default 1000)
`cursor`	`string`	No	Pagination cursor from previous response's next_cursor
`fields`	`array`	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
`account_id`	`string`	Ad accoun

…(truncated)

Facebook-Marketing full reference

File contents

Facebook-Marketing full reference

Supported entities and actions

Current User

Current User Get

Python SDK

API

Parameters

Records

Ad Accounts

Ad Accounts List

Python SDK

API

Parameters

Records

Meta

Ad Accounts Search

Python SDK

API

Parameters

Searchable Fields

Campaigns

Campaigns List

Python SDK

API

Parameters

Records

Meta

Campaigns Get

Python SDK

API

Parameters

Records

Campaigns Search

Python SDK

API

Parameters

Searchable Fields

Ad Sets

Ad Sets List

Python SDK

API

Parameters

Records

Meta

Ad Sets Get

Python SDK

API

Parameters

Records

Ad Sets Search

Python SDK

API

Parameters

Searchable Fields

Ads

Ads List

Python SDK

API

Parameters

Records

Meta

Ads Get

Python SDK

API

Parameters

Records

Ads Search

Python SDK

API

Parameters

Searchable Fields

Ad Creatives

Ad Creatives List

Python SDK

API

Parameters

Records

Meta