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, Get, Context Store Search, Context Store SQL Query
Campaigns	List, Create, Get, Update, Context Store Search, Context Store SQL Query
Ad Sets	List, Create, Get, Update, Context Store Search, Context Store SQL Query
Ads	List, Create, Get, Update, Context Store Search, Context Store SQL Query
Ad Creatives	List, Context Store Search, Context Store SQL Query, Semantic Search
Ads Insights	List, Context Store Search, Context Store SQL Query
Custom Conversions	List, Context Store Search, Context Store SQL Query
Images	List, Context Store Search, Context Store SQL Query
Videos	List, Context Store Search, Context Store SQL Query
Pixels	List, Get
Pixel Stats	List
Ad Library	List

Current User

Current User Get

Returns information about the current user associated with the access token

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "current_user",
  "action": "get"
}'

Python SDK

await facebook_marketing.current_user.get()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_accounts",
  "action": "list"
}'

Python SDK

await facebook_marketing.ad_accounts.list()

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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 Get

Returns information about the specified ad account including balance and currency

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_accounts",
  "action": "get",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

await facebook_marketing.ad_accounts.get(
    account_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_accounts",
    "action": "get",
    "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

Response Schema

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_city	string | null
business_country_code	string | null
business_name	string | null
business_state	string | null
business_street	string | null
business_street2	string | null
business_zip	string | null
created_time	string | null
currency	string | null
disable_reason	integer | null
end_advertiser	string | null
end_advertiser_name	string | null
funding_source	string | null
funding_source_details	object | null
has_migrated_permissions	boolean | null
is_personal	integer | null
is_prepay_account	boolean | null
is_tax_id_required	boolean | null
min_campaign_group_spend_cap	string | null
min_daily_budget	integer | null
owner	string | null
spend_cap	string | null
timezone_id	integer | null
timezone_name	string | null
timezone_offset_hours_utc	number | null

Ad Accounts Context Store 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.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_accounts",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_accounts",
    "action": "context_store_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, startswith, endswith, contains, array_contains, 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 meta.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

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].id	string	Ad account ID
data[].account_id	string	Ad account ID (numeric)
data[].name	string	Ad account name
data[].balance	string	Current balance of the ad account
data[].currency	string	Currency used by the ad account
data[].account_status	integer	Account status
data[].amount_spent	string	Total amount spent
data[].business_name	string	Business name
data[].created_time	string	Account creation time
data[].spend_cap	string	Spend cap
data[].timezone_name	string	Timezone name

Ad Accounts Context Store SQL Query

Run a SQL query against ad accounts records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_accounts",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await facebook_marketing.ad_accounts.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_accounts",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Campaigns

Campaigns List

Returns a list of campaigns for the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "campaigns",
  "action": "list",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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 Create

Creates a new ad campaign in the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "campaigns",
  "action": "create",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

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

Parameters

Parameter Name	Type	Required	Description
account_id	string	Yes	The Facebook Ad Account ID (without act_ prefix)

Response Schema

Records

Field Name	Type	Description
id	string

Campaigns Get

Returns a single campaign by ID

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "campaigns",
  "action": "get",
  "params": {
    "campaign_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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 Update

Updates an existing ad campaign

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "campaigns",
  "action": "update",
  "params": {
    "campaign_id": "<str>"
  }
}'

Python SDK

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

API

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

Parameters

Parameter Name	Type	Required	Description
campaign_id	string	Yes	The campaign ID

Response Schema

Records

Field Name	Type	Description
success	boolean

Campaigns Context Store 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.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "campaigns",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "campaigns",
    "action": "context_store_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, startswith, endswith, contains, array_contains, 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 meta.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

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].id	string	Campaign ID
data[].name	string	Campaign name
data[].account_id	string	Ad account ID
data[].status	string	Campaign status
data[].effective_status	string	Effective status
data[].objective	string	Campaign objective
data[].daily_budget	number	Daily budget in account currency
data[].lifetime_budget	number	Lifetime budget
data[].budget_remaining	number	Remaining budget
data[].created_time	string	Campaign creation time
data[].start_time	string	Campaign start time
data[].stop_time	string	Campaign stop time
data[].updated_time	string	Last update time

Campaigns Context Store SQL Query

Run a SQL query against campaigns records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "campaigns",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await facebook_marketing.campaigns.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "campaigns",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Ad Sets

Ad Sets List

Returns a list of ad sets for the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_sets",
  "action": "list",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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 Create

Creates a new ad set in the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_sets",
  "action": "create",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

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

Parameters

Parameter Name	Type	Required	Description
account_id	string	Yes	The Facebook Ad Account ID (without act_ prefix)

Response Schema

Records

Field Name	Type	Description
id	string

Ad Sets Get

Returns a single ad set by ID

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_sets",
  "action": "get",
  "params": {
    "adset_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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 Update

Updates an existing ad set

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_sets",
  "action": "update",
  "params": {
    "adset_id": "<str>"
  }
}'

Python SDK

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

API

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

Parameters

Parameter Name	Type	Required	Description
adset_id	string	Yes	The ad set ID

Response Schema

Records

Field Name	Type	Description
success	boolean

Ad Sets Context Store 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.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_sets",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_sets",
    "action": "context_store_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, startswith, endswith, contains, array_contains, 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 meta.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

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].id	string	Ad Set ID
data[].name	string	Ad Set name
data[].account_id	string	Ad account ID
data[].campaign_id	string	Parent campaign ID
data[].effective_status	string	Effective status
data[].daily_budget	number	Daily budget
data[].lifetime_budget	number	Lifetime budget
data[].budget_remaining	number	Remaining budget
data[].bid_amount	number	Bid amount
data[].bid_strategy	string	Bid strategy
data[].created_time	string	Ad set creation time
data[].start_time	string	Ad set start time
data[].end_time	string	Ad set end time
data[].updated_time	string	Last update time

Ad Sets Context Store SQL Query

Run a SQL query against ad sets records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_sets",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await facebook_marketing.ad_sets.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_sets",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Ads

Ads List

Returns a list of ads for the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ads",
  "action": "list",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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 Create

Creates a new ad in the specified ad account. Note - requires a Facebook Page to be connected to the ad account.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ads",
  "action": "create",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

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

Parameters

Parameter Name	Type	Required	Description
account_id	string	Yes	The Facebook Ad Account ID (without act_ prefix)

Response Schema

Records

Field Name	Type	Description
id	string

Ads Get

Returns a single ad by ID

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ads",
  "action": "get",
  "params": {
    "ad_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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 Update

Updates an existing ad

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ads",
  "action": "update",
  "params": {
    "ad_id": "<str>"
  }
}'

Python SDK

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

API

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

Parameters

Parameter Name	Type	Required	Description
ad_id	string	Yes	The ad ID

Response Schema

Records

Field Name	Type	Description
success	boolean

Ads Context Store 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.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ads",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ads",
    "action": "context_store_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, startswith, endswith, contains, array_contains, 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 meta.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

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].id	string	Ad ID
data[].name	string	Ad name
data[].account_id	string	Ad account ID
data[].adset_id	string	Parent ad set ID
data[].campaign_id	string	Parent campaign ID
data[].status	string	Ad status
data[].effective_status	string	Effective status
data[].created_time	string	Ad creation time
data[].updated_time	string	Last update time

Ads Context Store SQL Query

Run a SQL query against ads records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ads",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await facebook_marketing.ads.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ads",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Ad Creatives

Ad Creatives List

Returns a list of ad creatives for the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_creatives",
  "action": "list",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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 Context Store 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.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_creatives",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_creatives",
    "action": "context_store_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, startswith, endswith, contains, array_contains, 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 meta.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

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].id	string	Ad Creative ID
data[].name	string	Ad Creative name
data[].account_id	string	Ad account ID
data[].body	string	Ad body text
data[].title	string	Ad title
data[].status	string	Creative status
data[].image_url	string	Image URL
data[].thumbnail_url	string	Thumbnail URL
data[].link_url	string	Link URL
data[].call_to_action_type	string	Call to action type

Ad Creatives Context Store SQL Query

Run a SQL query against ad creatives records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_creatives",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await facebook_marketing.ad_creatives.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_creatives",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Ad Creatives Semantic Search

Search ad creatives records by meaning rather than by exact or fuzzy field values. Semantic search embeds a natural-language prompt and returns the most similar passages, ranked by relevance. Pass semantic={field, prompt, filter?, context_size?, min_similarity?, dedup?} to context_store_search instead of query. Only available in hosted mode.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_creatives",
  "action": "context_store_search",
  "params": {
    "semantic": {"field": "body", "prompt": "<your natural-language query>"}
  }
}'

Python SDK

Semantic search is passed through the generic execute method — the typed ad_creatives.context_store_search helper only accepts query.

await facebook_marketing.execute(
    "ad_creatives",
    "context_store_search",
    {"semantic": {"field": "body", "prompt": "<your natural-language query>"}},
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ad_creatives",
    "action": "context_store_search",
    "params": {
        "semantic": {"field": "body", "prompt": "<your natural-language query>"}
    }
}'

Semantic Parameters

Parameter Name	Type	Required	Description
semantic.field	string	Yes	Field to search semantically. Mutually exclusive with query.
semantic.prompt	string	Yes	Natural-language query that is embedded and compared against stored passages.
semantic.filter	object	No	Filter conditions (same shape/operators as query.filter). sort is not supported — results are ranked by similarity.
semantic.context_size	integer	No	Characters of surrounding context to return per hit, up to the field's configured window. Omit to return the full configured window.
semantic.min_similarity	number	No	Minimum similarity score in [-1.0, 1.0]. Omit for 0.25; scores below the threshold are discarded before deduplication and top-k selection. Use -1.0 to disable the cutoff.
semantic.dedup	string	No	max (default) returns the single best-scoring passage per record; none returns multiple passages per record, still ranked by similarity and capped by limit.
fields	array	No	Field paths to include in results (dot notation for nested fields). Applied to each hit's entity.
limit	integer	No	Maximum results to return (default 10, maximum 100).

Semantically Searchable Fields

Field Name	Max Context (chars)	Description
body	2048	Ad body text

Response Schema

Field Name	Type	Description
data	array	List of matching passages
data[].entity	object	The matched source record
data[].entity.id	string	Source record field
data[].entity.status	string	Source record field
data[].entity.name	string	Source record field
data[].entity.account_id	string	Source record field
data[].entity.title	string	Source record field
data[].entity.call_to_action_type	string	Source record field
data[].entity.object_type	string	Source record field
data[].entity.actor_id	string	Source record field
data[].entity.effective_object_story_id	string	Source record field
data[].entity.video_id	string	Source record field
data[].entity.image_hash	string	Source record field
data[].entity.link_url	string	Source record field
data[].entity.url_tags	string	Source record field
data[].entity.instagram_permalink_url	string	Source record field
data[].metadata	object	Match metadata
data[].metadata.score	number	Similarity score
data[].metadata.context	string	The matched passage text
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds

Ads Insights

Ads Insights List

Returns performance insights for the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ads_insights",
  "action": "list",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_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

Response Schema

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 Context Store 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.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ads_insights",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "account_id": "<str>"
        }
      }
    }
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ads_insights",
    "action": "context_store_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, startswith, endswith, contains, array_contains, 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 meta.cursor
fields	array	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
account_id	string	Ad account ID
account_name	string	Ad account name
campaign_id	string	Campaign ID
campaign_name	string	Campaign name
adset_id	string	Ad set ID
adset_name	string	Ad set name
ad_id	string	Ad ID
ad_name	string	Ad name
clicks	integer	Number of clicks
impressions	integer	Number of impressions
reach	integer	Number of unique people reached
spend	number	Amount spent
cpc	number	Cost per click
cpm	number	Cost per 1000 impressions
ctr	number	Click-through rate
date_start	string	Start date of the reporting period
date_stop	string	End date of the reporting period
actions	array	Total number of actions taken
action_values	array	Action values taken on the ad

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].account_id	string	Ad account ID
data[].account_name	string	Ad account name
data[].campaign_id	string	Campaign ID
data[].campaign_name	string	Campaign name
data[].adset_id	string	Ad set ID
data[].adset_name	string	Ad set name
data[].ad_id	string	Ad ID
data[].ad_name	string	Ad name
data[].clicks	integer	Number of clicks
data[].impressions	integer	Number of impressions
data[].reach	integer	Number of unique people reached
data[].spend	number	Amount spent
data[].cpc	number	Cost per click
data[].cpm	number	Cost per 1000 impressions
data[].ctr	number	Click-through rate
data[].date_start	string	Start date of the reporting period
data[].date_stop	string	End date of the reporting period
data[].actions	array	Total number of actions taken
data[].action_values	array	Action values taken on the ad

Ads Insights Context Store SQL Query

Run a SQL query against ads insights records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ads_insights",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await facebook_marketing.ads_insights.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "ads_insights",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Custom Conversions

Custom Conversions List

Returns a list of custom conversions for the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "custom_conversions",
  "action": "list",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "custom_conversions",
    "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

Response Schema

Records

Field Name	Type	Description
id	string
name	string | null
account_id	string | null
business	string | null
creation_time	string | null
custom_event_type	string | null
data_sources	array | null
data_sources[].id	string | null
data_sources[].source_type	string | null
data_sources[].name	string | null
default_conversion_value	number | null
description	string | null
event_source_type	string | null
first_fired_time	string | null
is_archived	boolean | null
is_unavailable	boolean | null
last_fired_time	string | null
offline_conversion_data_set	string | null
retention_days	number | null
rule	string | null

Meta

Field Name	Type	Description
after	string | null

Custom Conversions Context Store Search

Search and filter custom conversions 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.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "custom_conversions",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "custom_conversions",
    "action": "context_store_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, startswith, endswith, contains, array_contains, 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 meta.cursor
fields	array	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
id	string	Custom Conversion ID
name	string	Custom Conversion name
account_id	string	Ad account ID
description	string	Description
custom_event_type	string	Custom event type
creation_time	string	Creation time
first_fired_time	string	First fired time
last_fired_time	string	Last fired time
is_archived	boolean	Whether the conversion is archived

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].id	string	Custom Conversion ID
data[].name	string	Custom Conversion name
data[].account_id	string	Ad account ID
data[].description	string	Description
data[].custom_event_type	string	Custom event type
data[].creation_time	string	Creation time
data[].first_fired_time	string	First fired time
data[].last_fired_time	string	Last fired time
data[].is_archived	boolean	Whether the conversion is archived

Custom Conversions Context Store SQL Query

Run a SQL query against custom conversions records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "custom_conversions",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await facebook_marketing.custom_conversions.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "custom_conversions",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Images

Images List

Returns a list of ad images for the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "images",
  "action": "list",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "images",
    "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

Response Schema

Records

Field Name	Type	Description
id	string | null
name	string | null
account_id	string | null
created_time	string | null
creatives	array | null
filename	string | null
hash	string | null
height	integer | null
is_associated_creatives_in_adgroups	boolean | null
original_height	integer | null
original_width	integer | null
permalink_url	string | null
status	string | null
updated_time	string | null
url	string | null
url_128	string | null
width	integer | null

Meta

Field Name	Type	Description
after	string | null

Images Context Store Search

Search and filter images 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.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "images",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "images",
    "action": "context_store_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, startswith, endswith, contains, array_contains, 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 meta.cursor
fields	array	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
id	string	Image ID
name	string	Image name
account_id	string	Ad account ID
hash	string	Image hash
url	string	Image URL
permalink_url	string	Permalink URL
width	integer	Image width
height	integer	Image height
status	string	Image status
created_time	string	Creation time
updated_time	string	Last update time

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].id	string	Image ID
data[].name	string	Image name
data[].account_id	string	Ad account ID
data[].hash	string	Image hash
data[].url	string	Image URL
data[].permalink_url	string	Permalink URL
data[].width	integer	Image width
data[].height	integer	Image height
data[].status	string	Image status
data[].created_time	string	Creation time
data[].updated_time	string	Last update time

Images Context Store SQL Query

Run a SQL query against images records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "images",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await facebook_marketing.images.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "images",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Videos

Videos List

Returns a list of ad videos for the specified ad account

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "videos",
  "action": "list",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "videos",
    "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

Response Schema

Records

Field Name	Type	Description
id	string
title	string | null
account_id	string | null
ad_breaks	array | null
backdated_time	string | null
backdated_time_granularity	string | null
content_category	string | null
content_tags	array | null
created_time	string | null
custom_labels	array | null
description	string | null
embed_html	string | null
embeddable	boolean | null
format	array | null
format[].filter	string | null
format[].embed_html	string | null
format[].width	integer | null
format[].height	integer | null
format[].picture	string | null
icon	string | null
is_crosspost_video	boolean | null
is_crossposting_eligible	boolean | null
is_episode	boolean | null
is_instagram_eligible	boolean | null
length	number | null
live_status	string | null
permalink_url	string | null
post_views	integer | null
premiere_living_room_status	boolean | null
published	boolean | null
scheduled_publish_time	string | null
source	string | null
universal_video_id	string | null
updated_time	string | null
views	integer | null

Meta

Field Name	Type	Description
after	string | null

Videos Context Store Search

Search and filter videos 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.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "videos",
  "action": "context_store_search",
  "params": {
    "query": {
      "filter": {
        "eq": {
          "id": "<str>"
        }
      }
    }
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "videos",
    "action": "context_store_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, startswith, endswith, contains, array_contains, 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 meta.cursor
fields	array	No	Field paths to include in results

Searchable Fields

Field Name	Type	Description
id	string	Video ID
title	string	Video title
account_id	string	Ad account ID
description	string	Video description
length	number	Video length in seconds
source	string	Video source URL
permalink_url	string	Permalink URL
views	integer	Number of views
created_time	string	Creation time
updated_time	string	Last update time

Response Schema

Field Name	Type	Description
data	array	List of matching records
meta	object	Pagination metadata
meta.has_more	boolean	Whether additional pages are available
meta.cursor	string | null	Cursor for next page of results
meta.took_ms	number | null	Query execution time in milliseconds
data[].id	string	Video ID
data[].title	string	Video title
data[].account_id	string	Ad account ID
data[].description	string	Video description
data[].length	number	Video length in seconds
data[].source	string	Video source URL
data[].permalink_url	string	Permalink URL
data[].views	integer	Number of views
data[].created_time	string	Creation time
data[].updated_time	string	Last update time

Videos Context Store SQL Query

Run a SQL query against videos records in the Airbyte Context Store. SQL projections may return any set of columns, so each result row is a dictionary matching the query's selected fields. Only available in hosted mode.

Use the hosted server documentation to find the qualified Context Store table name and SQL guidance.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "videos",
  "action": "context_store_sql_query",
  "params": {
    "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
  }
}'

Python SDK

await facebook_marketing.videos.context_store_sql_query(
    sql="SELECT * FROM <qualified_context_store_table> LIMIT 100"
)

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "videos",
    "action": "context_store_sql_query",
    "params": {
        "sql": "SELECT * FROM <qualified_context_store_table> LIMIT 100"
    }
}'

Parameters

Parameter Name	Type	Required	Description
sql	string	Yes	SQL query to execute against this entity's Context Store data
limit	integer	No	Maximum results to return

Response Schema

Field Name	Type	Description
data	array	Projected rows, with dictionary keys matching the selected columns
meta	object	Query metadata
meta.has_more	boolean	Whether the result was limited and more rows are available
meta.cursor	null	SQL query results do not use cursor pagination
meta.took_ms	number | null	Query execution time in milliseconds

Pixels

Pixels List

Returns a list of Facebook pixels for the specified ad account, including pixel configuration and event quality data

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "pixels",
  "action": "list",
  "params": {
    "account_id": "<str>"
  }
}'

Python SDK

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

API

curl --location 'https://api.airbyte.ai/api/v1/integrations/connectors/{your_connector_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
    "entity": "pixels",
    "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

Response Schema

Records

Field Name	Type	Description
id	string
name	string | null
creation_time	string | null
creator	object | null
data_use_setting	string | null
enable_automatic_matching	boolean | null
first_party_cookie_status	string | null
is_created_by_app	boolean | null
is_crm	boolean | null
is_unavailable	boolean | null
last_fired_time	string | null
owner_ad_account	object | null
owner_business	object | null

Meta

Field Name	Type	Description
after	string | null

Pixels Get

Returns details about a single Facebook pixel by ID

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "pixels",
  "action": "get",
  "params": {
    "pixel_id": "<str>"
  }
}'

Python SDK

await facebook_marketing.pixels.get(
    pixel_id="<str>"
)

API

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

Parameters

Parameter Name	Type	Required	Description
pixel_id	string	Yes	The Facebook pixel ID
fields	string	No	Comma-separated list of fields to return

Response Schema

Records

Field Name	Type	Description
id	string
name	string | null
creation_time	string | null
creator	object | null
data_use_setting	string | null
enable_automatic_matching	boolean | null
first_party_cookie_status	string | null
is_created_by_app	boolean | null
is_crm	boolean | null
is_unavailable	boolean | null
last_fired_time	string | null
owner_ad_account	object | null
owner_business	object | null

Pixel Stats

Pixel Stats List

Returns event quality and stats data for a Facebook pixel, including event counts, match quality scores, and deduplication metrics

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "pixel_stats",
  "action": "list",
  "params": {
    "pixel_id": "<str>"
  }
}'

Python SDK

await facebook_marketing.pixel_stats.list(
    pixel_id="<str>"
)

API

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

Parameters

Parameter Name	Type	Required	Description
pixel_id	string	Yes	The Facebook pixel ID
start_time	string	No	Start time for stats period as Unix timestamp
end_time	string	No	End time for stats period as Unix timestamp
aggregation	"event" | "device" | "custom_data_field"	No	Aggregation level for stats

Response Schema

Records

Field Name	Type	Description
data	array | null
event	string | null
event_source	string | null
total_count	integer | null
total_matched_count	integer | null
total_deduped_count	integer | null
test_events_count	integer | null

Ad Library

Ad Library List

Search the Facebook Ad Library for ads about social issues, elections or politics, and ads delivered to the UK or EU. Returns archived ads matching the specified search criteria including ad creative content, delivery dates, spend ranges, and demographic reach data.

CLI

airbyte-agent connectors execute --json '{
  "workspace": "<your_workspace_name>",
  "name": "facebook-marketing",
  "entity": "ad_library",
  "action": "list",
  "params": {
    "ad_reached_countries": "<str>"
  }
}'

Python SDK

await facebook_marketing.ad_library.list(
    ad_reached_countries="<str>"
)

API

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

Parameters

Parameter Name	Type	Required	Description
ad_reached_countries	string	Yes	Search by ISO country code to return ads that reached specific countries. Use ALL to search all countries.
search_terms	string	No	The terms to search for. Blank space is treated as logical AND. Limit of 100 characters.
search_page_ids	string	No	Search for ads by specific Facebook Page IDs (comma-separated, up to 10)
ad_type	"ALL" | "EMPLOYMENT_ADS" | "FINANCIAL_PRODUCTS_AND_SERVICES_ADS" | "HOUSING_ADS" | "POLITICAL_AND_ISSUE_ADS"	No	Filter by ad type category
ad_active_status	"ACTIVE" | "ALL" | "INACTIVE"	No	Filter by ad active status
ad_delivery_date_min	string	No	Search for ads delivered after this date (inclusive, YYYY-MM-DD)
ad_delivery_date_max	string	No	Search for ads delivered before this date (inclusive, YYYY-MM-DD)
bylines	string	No	Filter by paid-for-by disclaimer byline (JSON array of strings). Available only for POLITICAL_AND_ISSUE_ADS.
languages	string	No	Filter by language codes (ISO 639-1 JSON array, e.g. "['en','es']")
media_type	"ALL" | "IMAGE" | "MEME" | "VIDEO" | "NONE"	No	Filter by media type in the ad
publisher_platforms	string	No	Filter by Meta platform where the ad appeared (JSON array)
search_type	"KEYWORD_UNORDERED" | "KEYWORD_EXACT_PHRASE"	No	Type of search to use for search_terms
unmask_removed_content	boolean	No	Whether to reveal content removed for violating standards
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

Response Schema

Records

Field Name	Type	Description
id	string
ad_creation_time	string | null
ad_creative_bodies	array | null
ad_creative_link_captions	array | null
ad_creative_link_descriptions	array | null
ad_creative_link_titles	array | null
ad_delivery_start_time	string | null
ad_delivery_stop_time	string | null
ad_snapshot_url	string | null
age_country_gender_reach_breakdown	array | null
beneficiary_payers	array | null
br_total_reach	integer | null
bylines	string | null
currency	string | null
delivery_by_region	array | null
demographic_distribution	array | null
estimated_audience_size	object | null
eu_total_reach	integer | null
impressions	object | null
languages	array | null
page_id	string | null
page_name	string | null
publisher_platforms	array | null
spend	object | null
target_ages	array | null
target_gender	string | null
target_locations	array | null
total_reach_by_location	array | null

Meta

Field Name	Type	Description
after	string | null