600 Reference 6b5c0369

# 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) |
| Pixels | [List](#pixels-list), [Get](#pixels-get) |
| Pixel Stats | [List](#pixel-stats-list) |
| Ad Library | [List](#ad-library-list) |

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


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

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

</details>

### Ads Insights Search

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

#### Python SDK

```python
await facebook_marketing.ads_insights.search(
    query={"filter": {"eq": {"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_insights",
    "action": "search",
    "params": {
        "query": {"filter": {"eq": {"account_id": "<str>"}}}
    }
}'
```

#### Parameters

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

<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[].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 |

</details>

## Ad Account

### Ad Account Get

Returns information about the specified ad account including balance and currency

#### Python SDK

```python
await facebook_marketing.ad_account.get(
    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_account",
    "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 |


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


</details>

### Ad Account Search

Search and filter ad account 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_account.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_account",
    "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>

## Custom Conversions

### Custom Conversions List

Returns a list of custom conversions for the specified ad account

#### Python SDK

```python
await facebook_marketing.custom_conversions.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": "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 |


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

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

</details>

### Custom Conversions 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.

#### Python SDK

```python
await facebook_marketing.custom_conversions.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": "custom_conversions",
    "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` | 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 |

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

</details>

## Images

### Images List

Returns a list of ad images for the specified ad account

#### Python SDK

```python
await facebook_marketing.images.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": "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 |


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

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

</details>

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

#### Python SDK

```python
await facebook_marketing.images.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": "images",
    "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` | 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 |

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

</details>

## Videos

### Videos List

Returns a list of ad videos for the specified ad account

#### Python SDK

```python
await facebook_marketing.videos.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": "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 |


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

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

</details>

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

#### Python SDK

```python
await facebook_marketing.videos.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": "videos",
    "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` | 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 |

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

</details>

## Pixels

### Pixels List

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

#### Python SDK

```python
await facebook_marketing.pixels.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": "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 |


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

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

</details>

### Pixels Get

Returns details about a single Facebook pixel by ID

#### Python SDK

```python
await facebook_marketing.pixels.get(
    pixel_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": "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 |


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

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


</details>

## Pixel Stats

### Pixel Stats List

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

#### Python SDK

```python
await facebook_marketing.pixel_stats.list(
    pixel_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": "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 |


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

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


</details>

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

#### Python SDK

```python
await facebook_marketing.ad_library.list(
    ad_reached_countries="<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_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 |


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

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

</details>