# 600 Reference B714705c

> Facebook-Marketing full reference

- Skill: `tools-only/600-reference-b714705c` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/600-reference-b714705c`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/600-reference-b714705c/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/600-reference-b714705c

---

# 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](#current-user-get) |
| Ad Accounts | [List](#ad-accounts-list), [Search](#ad-accounts-search) |
| Campaigns | [List](#campaigns-list), [Create](#campaigns-create), [Get](#campaigns-get), [Update](#campaigns-update), [Search](#campaigns-search) |
| Ad Sets | [List](#ad-sets-list), [Create](#ad-sets-create), [Get](#ad-sets-get), [Update](#ad-sets-update), [Search](#ad-sets-search) |
| Ads | [List](#ads-list), [Create](#ads-create), [Get](#ads-get), [Update](#ads-update), [Search](#ads-search) |
| Ad Creatives | [List](#ad-creatives-list), [Search](#ad-creatives-search) |
| Ads Insights | [List](#ads-insights-list), [Search](#ads-insights-search) |
| Ad Account | [Get](#ad-account-get), [Search](#ad-account-search) |
| Custom Conversions | [List](#custom-conversions-list), [Search](#custom-conversions-search) |
| Images | [List](#images-list), [Search](#images-search) |
| Videos | [List](#videos-list), [Search](#videos-search) |

## Current User

### Current User Get

Returns information about the current user associated with the access token

#### Python SDK

```python
await facebook_marketing.current_user.get()
```

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### Records

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


</details>

## Ad Accounts

### Ad Accounts List

Returns a list of ad accounts associated with the current user

#### Python SDK

```python
await facebook_marketing.ad_accounts.list()
```

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### 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` |  |

</details>

### 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

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

#### API

```bash
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": "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 `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 |

<details>
<summary><b>Response Schema</b></summary>

| 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 |

</details>

## Campaigns

### Campaigns List

Returns a list of campaigns for the specified ad account

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### 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` |  |

</details>

### Campaigns Create

Creates a new ad campaign in the specified ad account

#### Python SDK

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

#### API

```bash
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) |


<details>
<summary><b>Response Schema</b></summary>

#### Records

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | `string` |  |


</details>

### Campaigns Get

Returns a single campaign by ID

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### 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` |  |


</details>

### Campaigns Update

Updates an existing ad campaign

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### Records

| Field Name | Type | Description |
|------------|------|-------------|
| `success` | `boolean` |  |


</details>

### 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

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

#### API

```bash
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": "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 `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 |

<details>
<summary><b>Response Schema</b></summary>

| 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 |

</details>

## Ad Sets

### Ad Sets List

Returns a list of ad sets for the specified ad account

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### 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` |  |

</details>

### Ad Sets Create

Creates a new ad set in the specified ad account

#### Python SDK

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

#### API

```bash
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) |


<details>
<summary><b>Response Schema</b></summary>

#### Records

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | `string` |  |


</details>

### Ad Sets Get

Returns a single ad set by ID

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### 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` |  |


</details>

### Ad Sets Update

Updates an existing ad set

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### Records

| Field Name | Type | Description |
|------------|------|-------------|
| `success` | `boolean` |  |


</details>

### 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

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

#### API

```bash
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": "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 `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 |

<details>
<summary><b>Response Schema</b></summary>

| 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 |

</details>

## Ads

### Ads List

Returns a list of ads for the specified ad account

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### 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` |  |

</details>

### Ads Create

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

#### Python SDK

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

#### API

```bash
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) |


<details>
<summary><b>Response Schema</b></summary>

#### Records

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | `string` |  |


</details>

### Ads Get

Returns a single ad by ID

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### 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` |  |


</details>

### Ads Update

Updates an existing ad

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### Records

| Field Name | Type | Description |
|------------|------|-------------|
| `success` | `boolean` |  |


</details>

### 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

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

#### API

```bash
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": "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 `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 |

<details>
<summary><b>Response Schema</b></summary>

| 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 |

</details>

## Ad Creatives

### Ad Creatives List

Returns a list of ad creatives for the specified ad account

#### Python SDK

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

#### API

```bash
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 |


<details>
<summary><b>Response Schema</b></summary>

#### 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` |  |

</details>

### 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

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

#### API

```bash
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": "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 `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 |

<details>
<summary><b>Response Schema</b></summary>

| 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 |

</details>

## Ads Insights

### Ads Insights List

Returns performance insights for the specified ad account

#### Python SDK

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

#### API

```bash
curl --location 'https://api.airbyte.ai/api/v1/integrations/conne

…(truncated)