Skip to main content

LinkedIn Ads

The linkedin_ads connector reads ad accounts, campaign groups, campaigns, creatives and ad analytics from the LinkedIn Marketing API. From a job, it can also send rows to any endpoint, such as conversion events. It is a REST connector: you declare the requests in YAML, the same way as the REST API connector.

Install​

sw connectors -i linkedin_ads

Connect​

LinkedIn signs in with an OAuth bearer token. Put these keys in a source's auth: block (with provider: linkedin_ads) or in a job's connection.

KeyWhat it isRequired / default
typebearerRequired
tokenThe access token (secret: a {{ secrets.NAME }} reference, redacted in every log line)Required

The http block describes the API. It takes the same keys as the REST API connector. The values LinkedIn needs:

KeyValue
base_urlhttps://api.linkedin.com
headersLinkedIn-Version (a YYYYMM version) and X-Restli-Protocol-Version: "2.0.0"
params_encodingdotted
paginatoroffset with offset_param: start, limit_param: count, total_path: paging.total
recordspath: elements
source.yaml
kind: source
name: linkedin_ads_demo

spec:
config:
account_ids: { type: list, items: string, description: "Sponsored Ad Account IDs" }
api_version: { type: string, default: "202401", description: "LinkedIn Version header (YYYYMM)" }
start_date: { type: date, default: "-30d", description: "Start date for performance metrics" }
secrets:
linkedin_access_token: { type: string }

auth:
provider: linkedin_ads
type: bearer
token: "{{ secrets.linkedin_access_token }}"

http:
base_url: https://api.linkedin.com
headers:
LinkedIn-Version: "{{ config.api_version }}"
X-Restli-Protocol-Version: "2.0.0"
params_encoding: dotted
paginator:
type: offset
offset_param: start
limit_param: count
page_size: 100
total_path: paging.total
records:
path: elements
  • Every request sends the LinkedIn-Version and Rest.li 2.0 protocol headers.
  • params_encoding: dotted turns nested parameters into LinkedIn's dotted form (dateRange.start.year=2026).
  • Paging uses start and count until paging.total is reached. Records come from the elements list.

Read data​

In a source​

streams/campaigns.yaml
partitions:
- { name: account_id, values: "{{ config.account_ids }}" }
policy:
retry: { max_attempts: 3, max_delay: 2m }

requests:
- name: raw_campaigns
operation:
path: /rest/adCampaigns
method: GET
params:
q: search
search.account.values[0]: "urn:li:sponsoredAccount:{{ partition.account_id }}"

transform:
mode: page
steps:
- name: campaigns
select: |
SELECT partition->>'account_id' AS account_id,
(record->>'id')::BIGINT AS campaign_id,
record->>'name' AS campaign_name,
record->>'status' AS status,
record->>'type' AS campaign_type,
record->>'costType' AS cost_type
FROM raw_campaigns

export:
campaigns:
step: campaigns
primary_key: [account_id, campaign_id]

In a job​

The connection holds the sign-in and the http defaults. A step's operation is the same request as in a stream, and its sql reads the table records (call steps).

connections:
linkedin_ads_api:
provider: linkedin_ads
type: bearer
token: "{{ secrets.linkedin_access_token }}"
http:
base_url: https://api.linkedin.com
headers:
LinkedIn-Version: "{{ config.api_version }}"
X-Restli-Protocol-Version: "2.0.0"

steps:
- name: campaigns
connection: linkedin_ads_api
operation:
path: /rest/adCampaigns
method: GET
params:
q: search
search.account.values[0]: "urn:li:sponsoredAccount:{{ config.account_id }}"
records: {path: elements}
paginator: {type: offset, offset_param: start, limit_param: count, page_size: 100, total_path: paging.total}
sql: |
SELECT (record->>'id')::BIGINT AS campaign_id,
record->>'name' AS campaign_name,
record->>'status' AS status,
(record->>'$.dailyBudget.amount')::DOUBLE AS daily_budget
FROM records

Analytics​

The /rest/adAnalytics endpoint takes structured parameters. With params_encoding: dotted you write them as nested YAML:

streams/campaign_performance.yaml
partitions:
- { name: account_id, values: "{{ config.account_ids }}" }
incremental:
cursor_field: date
start: "{{ config.start_date }}"
window: 1d
requests:
- name: raw_campaign_performance
operation:
path: /rest/adAnalytics
method: GET
params:
q: analytics
pivot: CAMPAIGN
timeGranularity: DAILY
accounts:
- "urn:li:sponsoredAccount:{{ partition.account_id }}"
dateRange:
start:
year: "{{ window.start | date('%Y') | int }}"
month: "{{ window.start | date('%m') | int }}"
day: "{{ window.start | date('%d') | int }}"
end:
year: "{{ window.end | date('%Y') | int }}"
month: "{{ window.end | date('%m') | int }}"
day: "{{ window.end | date('%d') | int }}"

transform:
mode: page
steps:
- name: campaign_performance
select: |
SELECT partition->>'account_id' AS account_id,
split_part(record->>'pivotValue', ':', 4)::BIGINT AS campaign_id,
make_date((record->>'$.dateRange.start.year')::INT,
(record->>'$.dateRange.start.month')::INT,
(record->>'$.dateRange.start.day')::INT) AS date,
coalesce((record->>'impressions')::BIGINT, 0) AS impressions,
coalesce((record->>'clicks')::BIGINT, 0) AS clicks,
coalesce((record->>'costInUsd')::DOUBLE, 0) AS spend
FROM raw_campaign_performance

export:
campaign_performance:
step: campaign_performance
primary_key: [account_id, campaign_id, date]

Starter streams​

The starter template (examples/sources/ads/linkedin_ads) has these streams. Copy them and change the columns, SQL or endpoints to fit your needs.

StreamWhat it readsEndpoint
ad_accountsSponsored ad accounts and organization references/rest/adAccounts
campaign_groupsCampaign groups, budgets and run schedules/rest/adCampaignGroups
campaignsCampaigns, budgets and cost types/rest/adCampaigns
creativesCreatives, creative types and content references/rest/adCreatives
campaign_performanceDaily impressions, clicks, spend, conversions and leads/rest/adAnalytics

Write data back​

A job's apply output (reverse ETL) sends rows to any endpoint of this API as HTTP requests. This one sends conversion events to the Conversions API, a chunk of rows per request:

outputs:
- name: send
connection: linkedin_ads_api
step: events # a row per conversion event
operation:
path: /rest/conversionEvents
method: POST
headers: {X-RestLi-Method: BATCH_CREATE}
json: {elements: "{{ rows }}"} # the chunk's rows, in one request
apply:
chunk_size: 500
on_row_error: continue
  • Without json, each row is sent as one request, with the row as its JSON body. {{ rows }} sends the whole chunk in one request, and every row of the chunk gets the call's outcome.
  • {{ row.<column> }} puts a row's value in the path, parameters, headers or body.
  • A row the API rejects fails alone, with the HTTP status as its code.
  • The conversion rule must exist in the ad account. LinkedIn deduplicates events on eventId.

The complete job, which also hashes emails in SQL, is examples/linkedin_ads.

Good to know​

  • Engines: sources (streamwright run), and DuckDB and Spark jobs through call steps. Writes run only in job apply outputs.
  • Vendor arguments: any HTTP request field goes to LinkedIn unchanged, for example params: { q: search, count: 100 }.
  • Retries: as with every REST connector, a request is retried on HTTP 429, 500, 502, 503 and 504 by default (REST API). Set policy.retry on the source or a stream to change it.

See also​