Skip to main content
Last updated on

LinkedIn Ads connector concepts

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

Learn how the managed LinkedIn Ads connector in Lakeflow Connect works.

How the connector works​

The LinkedIn Ads connector ingests data from LinkedIn Ads into Databricks using the LinkedIn Marketing API, pinned to API version 202604. The connector supports two types of tables:

  • Entity tables: These tables contain configuration data about your ad accounts, such as campaigns, creatives, and account users. Entity tables are fully refreshed on each pipeline update. They do not support incremental ingestion or history tracking (SCD type 2).
  • Prebuilt report tables: These tables contain performance and demographic metrics, such as impressions, clicks, and spend. Report tables support incremental ingestion with a configurable lookback window that captures late-arriving revisions.

For a list of supported tables and their schemas, see LinkedIn Ads connector reference.

Source namespaces​

The connector exposes source tables under two kinds of namespace. When you define a pipeline object, the source_schema you specify determines which namespace the table comes from:

  • default: Contains the single source-wide table, account_history, which covers every ad account the authorizing token can reach.
  • Per-account namespaces: One namespace for each sponsored ad account, named after the sponsored ad-account ID. This namespace name is the value you set as source_schema in your pipeline spec. All four remaining entity tables and all seven report tables live here.

Because eleven of the twelve tables are per-account, a pipeline that ingests more than one ad account repeats those table definitions once per account, with a different source_schema each time.

To find a sponsored ad account ID, open the account in LinkedIn Campaign Manager. The numeric ID appears under the account name and in the page URL, after /accounts/ (for example, https://www.linkedin.com/campaignmanager/accounts/512345678/).

Incremental ingestion and lookback windows​

LinkedIn revises a day's metrics in place as late conversions and attribution updates arrive, so a row the connector already ingested can change afterward. To capture those revisions, each incremental update re-reads a trailing window of already-synced dates rather than only fetching new ones.

On the first update, a report is read from its start date up to yesterday. On every later update, each grain (an ad account or a campaign, depending on the report) resumes from its last committed cursor minus lookback_window_days, floored at the report's start date. The default lookback is 7 days, and you can set any value from 0 to 365. Set it to at least the length of your organization's conversion attribution window so late conversions land in your tables.

Progress is tracked per grain rather than per table, which means a mid-update failure keeps the grains that already finished instead of restarting the whole report:

  • ad_analytics_by_campaign_report tracks progress per ad account.
  • The creative report and all five demographic reports track progress per campaign.

Because progress is per grain, lowering sync_start_date after the first update does not backfill a report that has already synced. Only accounts or campaigns that appear for the first time start from the new date. To re-ingest earlier history, run a full refresh on the table.

Report families​

The seven prebuilt reports fall into two families with different shapes:

  • Daily performance reports produce one row per pivot entity per day. The day column holds an ISO date, and the entity column is named after the report's pivot, so the campaign report is keyed by campaign_id and the creative report by creative_id.
  • Monthly member-demographic reports produce one row per campaign per demographic value per month. LinkedIn's demographic responses do not carry the campaign, so the connector attributes campaign_id from the campaign it queried.

Monthly reports cannot be narrowed below a calendar month. LinkedIn returns no rows for a sub-month range at monthly granularity, so a sync_start_date that falls mid-month is aligned back to the first of that month, and the row returned for that month is a full-month aggregate.

Data retention horizons​

LinkedIn limits how far back each report family can be read. These are LinkedIn's limits, not the connector's:

  • Daily performance data is retained for 10 years.
  • Professional demographic data is retained for 2 years.

A sync_start_date older than the horizon that applies to the report fails the read, because data before it cannot be retrieved from the API. The error message names the earliest date you can use.

Time zone​

The connector evaluates all report date boundaries in UTC rather than in the ad account's time zone, and you cannot override this. If your ad account reports in a non-UTC time zone, expect daily totals to differ from what the LinkedIn Campaign Manager UI shows for the same calendar day.

On this page