Campaign Reporting

Managing campaigns and campaign reporting

class CampaignReportingMixin

This class defines all functions related to cross-platform ad campaign performance tracking (blueconic.domain.Campaign, blueconic.domain.CampaignMetricsRow, blueconic.domain.CampaignReportRow).

It allows notebooks to register campaigns, push daily metrics snapshots (including historical backfills), and retrieve aggregated reports with derived metrics (CTR, CPM, CPC, ROAS, match rate).

create_campaign(name, platform, account_id, external_campaign_id)

Register a new campaign in BlueConic. Upserts by (platform, account_id, external_campaign_id).

Parameters:

  • name – Campaign name

  • platform – Ad platform (e.g. meta, google)

  • account_id – Ad account ID on the external platform

  • external_campaign_id – The natural campaign ID on the external platform

Returns:

The created Campaign (with BlueConic-generated id)

Return type:

Campaign

delete_campaign(campaign_id)

Delete a campaign and all of its metric snapshots.

delete_campaign_metrics(campaign_id, date)

Delete a specific campaign metrics snapshot.

get_campaign(campaign_id)

Retrieve a campaign by its BlueConic ID.

get_campaign_metrics(campaign_id, start_date=None, end_date=None)

Retrieve raw daily metric snapshots for a campaign in the given date range.

get_campaign_report(segment_ids=None, platforms=None, campaign_ids=None, start_date=None, end_date=None)

Get an aggregated campaign report with derived metrics (CTR, CPM, CPC, ROAS, match rate). Aggregation is computed server-side over the given period.

Parameters:

  • segment_ids – Optional segment IDs to filter by

  • platforms – Optional ad platforms to filter by

  • campaign_ids – Optional campaign IDs to filter by

  • start_date – Optional start date (inclusive). At least one of start_date or end_date is required.

  • end_date – Optional end date (inclusive). At least one of start_date or end_date is required.

Returns:

List of CampaignReportRow (one per campaign matching the filter)

Return type:

List[CampaignReportRow]

Raises:

ValueError – When neither start_date nor end_date is provided.

get_campaign_report_over_time(segment_ids=None, platforms=None, campaign_ids=None, start_date=None, end_date=None)

Get per-date campaign report rows for graph plotting. Unlike get_campaign_report, which aggregates the whole period into one row per campaign, this preserves daily granularity: one row per (campaign, date) with the raw metrics recorded on that date and the derived metrics computed from them.

Parameters:

  • segment_ids – Optional segment IDs to filter by

  • platforms – Optional ad platforms to filter by

  • campaign_ids – Optional campaign IDs to filter by

  • start_date – Optional start date (inclusive). At least one of start_date or end_date is required.

  • end_date – Optional end date (inclusive). At least one of start_date or end_date is required.

Returns:

List of CampaignDailyReportRow ordered by (campaign id, date ascending)

Return type:

List[CampaignDailyReportRow]

Raises:

ValueError – When neither start_date nor end_date is provided.

get_campaigns(start=0, count=10000000)

Gets all campaigns and returns them in a generator with all BlueConic campaigns.

Parameters:

  • start (int, optional) – The campaign to start from. Defaults to 0.

  • count (int, optional) – The number of campaigns to retrieve. Defaults to 10000000.

Returns:

Iterator with Campaign

Return type:

Iterator[Campaign]

store_campaign_metrics(campaign_id, date, metrics, connection_id=None, segment_id=None, platform_audience_id=None)

Push a daily metrics snapshot for a campaign. Supports historical backfills.

Parameters:

  • campaign_id – BlueConic campaign ID

  • date – Snapshot date

  • metrics – Metric values (e.g. impressions, clicks, spend, conversions, conversionValue, audienceSize, segmentSize)

  • connection_id – Optional source connection ID

  • segment_id – Optional linked segment ID

  • platform_audience_id – Optional platform-side audience id this snapshot was reported against (e.g. a Meta Custom Audience id, Google Ads user list id)

Returns:

The stored CampaignMetricsRow

Return type:

CampaignMetricsRow

update_campaign(campaign_id, name, platform, account_id, external_campaign_id)

Update an existing campaign.

update_campaign_metrics(campaign_id, date, metrics, connection_id=None, segment_id=None, platform_audience_id=None)

Update an existing campaign metrics snapshot for a specific date.

Using campaign reporting objects

class Campaign

This class represents a BlueConic campaign used for cross-platform ad performance tracking.

property account_id

The ad account ID on the external platform.

property created_at

When the campaign was registered in BlueConic.

property external_campaign_id

The natural campaign ID on the external platform.

property id

The BlueConic-generated ID of the campaign.

property name

The campaign name.

property platform

The ad platform (e.g. meta, google).

class CampaignMetricsRow

This class represents a single daily metrics snapshot for a BlueConic campaign.

class CampaignReportRow

This class represents an aggregated campaign report row, as returned by get_campaign_report. It bundles the Campaign with both raw metrics aggregated over the requested period and derived metrics (CTR, CPM, CPC, ROAS, match rate, etc.) computed server-side.

class CampaignDailyReportRow

A per-date campaign report row, as returned by get_campaign_report_over_time. It bundles the Campaign with the raw metrics recorded on a single date and the derived metrics (CTR, CPM, CPC, ROAS, match rate, cost per conversion) computed from them.

Use this for graph plotting when daily granularity matters. For a single aggregated row per campaign over a whole period, see CampaignReportRow.