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, cost per conversion, and the email/ESP open rate and click rate).

Both paid-media and email/ESP campaigns use the same endpoints: an ESP snapshot carries the email counters and reuses the shared conversions and conversionValue keys rather than an esp-prefixed variant.

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, cost per conversion, and the email/ESP open rate and click 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. Paid-media keys: impressions, clicks, spend, conversions, conversionValue, audienceSize, segmentSize. Email/ESP keys: delivered, opensUnique, clicksUnique, bouncesUnique, unsubscribesUnique; ESP-reported conversions reuse the shared conversions / conversionValue keys. The derived ids (ctr, cpm, cpc, roas, matchRate, costPerConversion, openRate, clickRate) are reserved and are dropped by the platform rather than stored: it computes each of them from the raw counters on every report response, and a stored copy would be summed across rows on aggregation, contradicting the value it sits next to.

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

Parameters:

metrics – Same keys as store_campaign_metrics, including the reserved derived ids that the platform drops rather than stores.

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.