Custom Reports Private Preview
In addition to the prebuilt AD_REPORT_DAILY report, you can add any number of custom reports during connection setup. For each custom report, you determine the:
See the Custom Reports: Primary key section to learn how these choices determine the report's primary key.
Once you save a custom report, its Aggregation level, Time granularity, and Segment become permanent and cannot be changed, because changing them would alter the report's primary key. To use different values, add a new custom report instead. The Destination table name is also permanent. Report fields can still be edited at any time.
Aggregation level
Determines the entity level your report is aggregated by: Ad account, Campaign, Ad group, or Ad.
The aggregation level determines:
- Which performance metrics (impressions, clicks, spend, CTR, CPC, CPM) are available for the selected level.
- Which entity fields (IDs, names, and other attributes) are available for the selected level and the levels above it in the hierarchy (Ad account → Campaign → Ad group → Ad). For example, a report aggregated at the Ad group level can include ad group, campaign, and ad account entity fields, but not ad-level fields.
Time granularity
Determines how report rows are bucketed over time: Hourly, Daily, or Monthly.
Every report includes start_time/end_time columns for the reporting window. Daily reports also include the metadata.readable_time field, mapped to the destination date column. Monthly reports map to the month column in the destination, in YYYY-MM format. The date and month values are in your ad account's time zone, while start_time and end_time are Unix timestamps in UTC.
Segment
Optionally split the report by Product, Country, or Device. Each segment makes its own identifying fields and metrics available. For example, selecting Country makes country.name and the country-level metrics available.
A custom report can have at most one segment. Hourly time granularity cannot be combined with a segment, and Monthly time granularity cannot be combined with the Product segment.
Fields
The fields available to select depend on the aggregation level and the segment you choose:
- Metrics -
impressions,clicks,spend,ctr,cpc, andcpmfor the selected aggregation level or, if you select a segment, for that segment. - Entity fields - IDs and attributes, such as name, status, or budget, for the selected aggregation level and the levels above it.
- Segment fields - IDs and attributes for the selected segment, identifying the product, country, or device the row represents.
- Report metadata -
readable_timeandtimezone, always available regardless of aggregation level or segment.
Primary key
Your report's primary key depends on whether you select a segment.
Without a segment, your report uses the selected entity's ID as its primary key. For example, reports at the Ad group level use ad_group.id. The key also includes date for Daily reports, month for Monthly reports, or start_time and end_time for Hourly reports.
With a segment, your report's primary key is _fivetran_id together with date for Daily reports or month for Monthly reports. _fivetran_id hashes the entity ID, the date or month, and the segment's identifying fields: country.name for Country, device.type for Device, and product.feed_id and product.item_id for Product. When the API returns at least one row for a re-synced day or month, we replace that period's rows, removing segment values the API no longer returns. If the API returns no rows for a certain time period, we leave its existing destination rows unchanged.
Every report includes start_time and end_time, but only Hourly reports include them in the primary key.
Limitations
- A custom report can have at most one segment.
Hourlytime granularity cannot be combined with a segment.Monthlytime granularity cannot be combined with the Product segment, because the OpenAI Ads API keeps only 30 days of product data.- Each custom report must include at least one field.
- The destination table name must be unique within the connection, contain only lowercase letters, numbers, and underscores, cannot start with an underscore, and cannot match the prebuilt report or a metadata table name.
- A report's aggregation level, time granularity, and segment cannot be changed once the report is saved. Add a new custom report if you need different values.