> For the complete documentation index, see [llms.txt](https://docs.erathos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.erathos.com/connectors/apis/openai-ads.md).

# OpenAI Ads

Connect your OpenAI Ads to your data warehouse. Sync campaigns, ads, insights, conversions, and feeds to BigQuery, Redshift, Postgres, Databricks, and more.

## Using the Erathos platform

When selecting OpenAI Ads as a new connector on the Erathos platform, you will need to name your connection and fill in the following form:

* **Token** — your OpenAI Ads API key, a bearer token scoped to a single ad account, used to authenticate all requests to the OpenAI Ads API

With this connection created you can seamlessly move your OpenAI Ads data to your BigQuery, Redshift or Postgres data warehouse.

### How to find my token?

OpenAI Ads authenticates with a bearer API key issued from Ads Manager. Sign in to the ad account you want to sync, go to **Settings → Integrations → API Keys**, and create a new API key. Note that each key is scoped to a single ad account — generate it from the account whose data you want to bring into Erathos.

Copy the generated key and keep it secure. The authentication scheme is documented in the [OpenAI Ads API reference](https://developers.openai.com/ads/api-reference/authentication), where you can also verify your key's scopes and permissions.

Paste the key into the **Token** field on the Erathos platform and click **Save and close** to complete the setup.

## Endpoints and fields

### ad\_account

Sync type availability: Full-refresh

Parent of [lead\_sync\_subscriptions](#lead_sync_subscriptions)

| Field          | Type      |
| -------------- | --------- |
| id             | text      |
| name           | text      |
| status         | text      |
| currency       | text      |
| country        | text      |
| timezone\_name | text      |
| business\_id   | text      |
| created\_at    | timestamp |
| updated\_at    | timestamp |

### ad\_account\_insights

Sync type availability: Full and incremental refresh

[Cursor](https://docs.erathos.com/platform/connections/sync-types#understanding-cursors): `updated_at`

| Field       | Type    | Cursor |
| ----------- | ------- | ------ |
| impressions | integer |        |
| clicks      | integer |        |
| spend       | float   |        |
| conversions | integer |        |
| currency    | text    |        |
| updated\_at | date    | ✓      |

### ad\_accounts

Sync type availability: Full-refresh

| Field          | Type      |
| -------------- | --------- |
| id             | text      |
| name           | text      |
| status         | text      |
| currency       | text      |
| country        | text      |
| timezone\_name | text      |
| created\_at    | timestamp |
| updated\_at    | timestamp |

### ad\_group\_insights

Sync type availability: Full and incremental refresh

[Cursor](https://docs.erathos.com/platform/connections/sync-types#understanding-cursors): `updated_at`

Child of [ad\_groups](#ad_groups)

| Field         | Type    | Cursor |
| ------------- | ------- | ------ |
| ad\_group\_id | text    |        |
| impressions   | integer |        |
| clicks        | integer |        |
| spend         | float   |        |
| conversions   | integer |        |
| currency      | text    |        |
| updated\_at   | date    | ✓      |

### ad\_groups

Sync type availability: Full-refresh

Parent of [ad\_group\_insights](#ad_group_insights)

| Field         | Type      |
| ------------- | --------- |
| id            | text      |
| name          | text      |
| campaign\_id  | text      |
| status        | text      |
| daily\_budget | float     |
| bid\_strategy | text      |
| start\_time   | timestamp |
| end\_time     | timestamp |
| created\_at   | timestamp |
| updated\_at   | timestamp |

### ad\_insights

Sync type availability: Full and incremental refresh

[Cursor](https://docs.erathos.com/platform/connections/sync-types#understanding-cursors): `updated_at`

Child of [ads](#ads)

| Field       | Type    | Cursor |
| ----------- | ------- | ------ |
| ad\_id      | text    |        |
| impressions | integer |        |
| clicks      | integer |        |
| spend       | float   |        |
| conversions | integer |        |
| currency    | text    |        |
| updated\_at | date    | ✓      |

### ads

Sync type availability: Full-refresh

Parent of [ad\_insights](#ad_insights)

| Field         | Type      |
| ------------- | --------- |
| id            | text      |
| name          | text      |
| ad\_group\_id | text      |
| status        | text      |
| format        | text      |
| created\_at   | timestamp |
| updated\_at   | timestamp |

### bulk\_mutation\_job

Sync type availability: Full-refresh

Parent of [bulk\_mutation\_job\_operations](#bulk_mutation_job_operations)

| Field            | Type      |
| ---------------- | --------- |
| id               | text      |
| status           | text      |
| operation\_count | integer   |
| created\_at      | timestamp |
| completed\_at    | timestamp |
| updated\_at      | timestamp |

### bulk\_mutation\_job\_operations

Sync type availability: Full-refresh

Child of [bulk\_mutation\_job](#bulk_mutation_job)

| Field          | Type      |
| -------------- | --------- |
| id             | text      |
| type           | text      |
| status         | text      |
| entity\_id     | text      |
| error\_message | text      |
| created\_at    | timestamp |

### campaign\_insights

Sync type availability: Full and incremental refresh

[Cursor](https://docs.erathos.com/platform/connections/sync-types#understanding-cursors): `updated_at`

Child of [campaigns](#campaigns)

| Field        | Type    | Cursor |
| ------------ | ------- | ------ |
| campaign\_id | text    |        |
| impressions  | integer |        |
| clicks       | integer |        |
| spend        | float   |        |
| conversions  | integer |        |
| currency     | text    |        |
| updated\_at  | date    | ✓      |

### campaigns

Sync type availability: Full-refresh

Parent of [campaign\_insights](#campaign_insights)

| Field            | Type      |
| ---------------- | --------- |
| id               | text      |
| name             | text      |
| objective        | text      |
| status           | text      |
| daily\_budget    | float     |
| lifetime\_budget | float     |
| start\_time      | timestamp |
| end\_time        | timestamp |
| created\_at      | timestamp |
| updated\_at      | timestamp |

### conversions\_event\_settings

Sync type availability: Full-refresh

| Field          | Type      |
| -------------- | --------- |
| id             | text      |
| event\_name    | text      |
| status         | text      |
| default\_value | float     |
| currency       | text      |
| created\_at    | timestamp |
| updated\_at    | timestamp |

### conversions\_events

Sync type availability: Full-refresh

Child of [conversions\_pixels](#conversions_pixels)

| Field              | Type      |
| ------------------ | --------- |
| id                 | text      |
| event\_name        | text      |
| event\_time        | timestamp |
| event\_source\_url | text      |
| value              | float     |
| currency           | text      |

### conversions\_insights

Sync type availability: Full and incremental refresh

[Cursor](https://docs.erathos.com/platform/connections/sync-types#understanding-cursors): `updated_at`

| Field             | Type    | Cursor |
| ----------------- | ------- | ------ |
| event\_name       | text    |        |
| conversions       | integer |        |
| conversion\_value | float   |        |
| currency          | text    |        |
| updated\_at       | date    | ✓      |

### conversions\_pixels

Sync type availability: Full-refresh

Parent of [conversions\_events](#conversions_events)

| Field       | Type      |
| ----------- | --------- |
| id          | text      |
| name        | text      |
| status      | text      |
| created\_at | timestamp |
| updated\_at | timestamp |

### custom\_audience\_operations

Sync type availability: Full-refresh

Child of [custom\_audiences](#custom_audiences)

| Field          | Type      |
| -------------- | --------- |
| id             | text      |
| type           | text      |
| status         | text      |
| payload\_count | integer   |
| created\_at    | timestamp |
| updated\_at    | timestamp |

### custom\_audiences

Sync type availability: Full-refresh

Parent of [custom\_audience\_operations](#custom_audience_operations)

| Field             | Type      |
| ----------------- | --------- |
| id                | text      |
| name              | text      |
| type              | text      |
| description       | text      |
| approximate\_size | integer   |
| status            | text      |
| created\_at       | timestamp |
| updated\_at       | timestamp |

### feed\_products\_query

Sync type availability: Full-refresh

Child of [feeds](#feeds)

| Field        | Type      |
| ------------ | --------- |
| id           | text      |
| title        | text      |
| price        | float     |
| currency     | text      |
| availability | text      |
| brand        | text      |
| updated\_at  | timestamp |

### feed\_sftp\_access

Sync type availability: Full-refresh

Child of [feeds](#feeds)

| Field       | Type      |
| ----------- | --------- |
| username    | text      |
| host        | text      |
| port        | integer   |
| directory   | text      |
| expires\_at | timestamp |

### feed\_uploads

Sync type availability: Full-refresh

| Field         | Type      |
| ------------- | --------- |
| id            | text      |
| feed\_id      | text      |
| status        | text      |
| started\_at   | timestamp |
| completed\_at | timestamp |
| item\_count   | integer   |
| created\_at   | timestamp |
| updated\_at   | timestamp |

### feeds

Sync type availability: Full-refresh

Parent of [feed\_products\_query](#feed_products_query), [feed\_sftp\_access](#feed_sftp_access)

| Field       | Type      |
| ----------- | --------- |
| id          | text      |
| name        | text      |
| type        | text      |
| status      | text      |
| item\_count | integer   |
| created\_at | timestamp |
| updated\_at | timestamp |

### geo\_lookup\_search

Sync type availability: Full-refresh

| Field         | Type |
| ------------- | ---- |
| name          | text |
| code          | text |
| type          | text |
| country\_code | text |
| parent\_code  | text |

### lead\_sync\_subscriptions

Sync type availability: Full-refresh

Child of [ad\_account](#ad_account)

| Field         | Type      |
| ------------- | --------- |
| id            | text      |
| callback\_url | text      |
| event\_type   | text      |
| status        | text      |
| created\_at   | timestamp |
| updated\_at   | timestamp |

### partner\_data\_upload

Sync type availability: Full-refresh

| Field         | Type      |
| ------------- | --------- |
| id            | text      |
| status        | text      |
| file\_name    | text      |
| record\_count | integer   |
| created\_at   | timestamp |
| updated\_at   | timestamp |

### spend\_limit\_windows

Sync type availability: Full-refresh

| Field        | Type      |
| ------------ | --------- |
| spend\_limit | float     |
| currency     | text      |
| start\_time  | timestamp |
| end\_time    | timestamp |
| status       | text      |

## Entity Relationships

```mermaid
erDiagram
    ad_account ||--o{ lead_sync_subscriptions : "id = ad_account_id"
    campaigns ||--o{ ad_groups : "id = campaign_id"
    ad_groups ||--o{ ads : "id = ad_group_id"
    ad_groups ||--o{ ad_group_insights : "id = ad_group_id"
    ads ||--o{ ad_insights : "id = ad_id"
    campaigns ||--o{ campaign_insights : "id = campaign_id"
    bulk_mutation_job ||--o{ bulk_mutation_job_operations : "id = job_id"
    conversions_pixels ||--o{ conversions_events : "id = pixel_id"
    custom_audiences ||--o{ custom_audience_operations : "id = custom_audience_id"
    feeds ||--o{ feed_products_query : "id = feed_id"
    feeds ||--o{ feed_sftp_access : "id = feed_id"
    feeds ||--o{ feed_uploads : "id = feed_id"

    ad_account { text id PK }
    ad_account_insights { date updated_at }
    ad_accounts { text id PK }
    ad_group_insights { text ad_group_id }
    ad_groups { text id PK }
    ad_insights { text ad_id }
    ads { text id PK }
    bulk_mutation_job { text id PK }
    bulk_mutation_job_operations { text id PK }
    campaign_insights { text campaign_id }
    campaigns { text id PK }
    conversions_event_settings { text id PK }
    conversions_events { text id PK }
    conversions_insights { date updated_at }
    conversions_pixels { text id PK }
    custom_audience_operations { text id PK }
    custom_audiences { text id PK }
    feed_products_query { text id PK }
    feed_sftp_access { text username }
    feed_uploads { text id PK }
    feeds { text id PK }
    geo_lookup_search { text code }
    lead_sync_subscriptions { text id PK }
    partner_data_upload { text id PK }
    spend_limit_windows { timestamp start_time }
```