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.
| Key | What it is | Required / default |
|---|---|---|
type | bearer | Required |
token | The 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:
| Key | Value |
|---|---|
base_url | https://api.linkedin.com |
headers | LinkedIn-Version (a YYYYMM version) and X-Restli-Protocol-Version: "2.0.0" |
params_encoding | dotted |
paginator | offset with offset_param: start, limit_param: count, total_path: paging.total |
records | path: elements |
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-Versionand Rest.li 2.0 protocol headers. params_encoding: dottedturns nested parameters into LinkedIn's dotted form (dateRange.start.year=2026).- Paging uses
startandcountuntilpaging.totalis reached. Records come from theelementslist.
Read data
In a source
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:
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.
| Stream | What it reads | Endpoint |
|---|---|---|
ad_accounts | Sponsored ad accounts and organization references | /rest/adAccounts |
campaign_groups | Campaign groups, budgets and run schedules | /rest/adCampaignGroups |
campaigns | Campaigns, budgets and cost types | /rest/adCampaigns |
creatives | Creatives, creative types and content references | /rest/adCreatives |
campaign_performance | Daily 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.retryon the source or a stream to change it.
See also
- REST API connector: paginators and request keys in full.
- Apply outputs: how rows are sent to a REST API.
- Shared vocabulary: run one pipeline across LinkedIn, Google, Microsoft and other ad networks.