LinkedIn Ads
Automatic login, nothing to type. What causes most arguments with clients is not the connection: it is that LinkedIn has two video metrics with similar names, and they are not the same number.
Start
ConnectLinkedIn login
Under Sources · Connect new source · LinkedIn Ads, the card opens the login directly. The window only closes after caOS has fetched the accounts, so an empty list means that login does not reach any ad account.
Then tick the client's accounts. Discovering is not the same as owning: caOS brings every account that login can reach, including other clients of the same agency.
The grid has two LinkedIn cards, Ads and Pages. Both use the same authorisation: connecting through one already enables the other.
Confirm beforehand that the person can grant the permissions. At a client with an app approval policy, this usually needs a conversation before, not during.
Your credential, and what happens to it
Connect once and you are connected. The credential renews itself, indefinitely. You do not need a date in the calendar and you do not need to reconnect periodically.
There is only one way the connection drops: someone revokes access on the platform side (password changed, person removed from the account, authorisation cancelled). The account then shows up under Lost connections and reconnecting fixes it, keeping the tags it already had.
Your credential is encrypted end to end. It is encrypted before it is stored, and the key does not live in the database, so even database access does not reveal it. Nobody at caOS, and not you either, can read the credential back after it is saved. The screen only shows that it exists and is valid.
Only the metrics you asked for are read. caOS does not write to your ad account in order to extract data, and it stores no personal data about who saw the ad. Processing follows Brazilian data protection law (LGPD), and deletion is yours: revoking the connection erases the stored credential.
Reference
Metrics and dimensionswhat each field means
“Plays” and “Views” are not the same metric. videoViews
counts 2 seconds or more with half the video on screen, and is LinkedIn's own
standard. videoStarts counts the video having started to play, and a
single frame already counts. Plays is always the bigger number: measured across a
whole campaign, the gap was 7.4%. What becomes video view in reports is the View.
If the client's screenshot says Plays and your dashboard shows less, the metrics
are different.
Core metrics10
| API field | What it is | Where it shows up |
|---|---|---|
| costInLocalCurrency | Spend, in the account currency. | Arrives as text. Convert it before summing. |
| impressions | How many times the ad was shown. | Impressions. |
| clicks | Every click. | For clicks through to the site, use landingPageClicks. |
| totalEngagements | Sum of the interactions LinkedIn counts as engagement. | The ready-made field, instead of adding reactions, comments and shares by hand. |
| videoViews | Views: 2 seconds with half the video on screen. | This becomes video view in reports. It is LinkedIn's own standard. |
| videoStarts | Plays started: a single frame already counts. | This is what LinkedIn's interface calls Plays. Always larger than the one above. |
| videoCompletions | Watched to the end. The three quartiles are there too. | Only exists in the per-campaign table. |
| approximateMemberReach | Distinct people reached, approximate. | Do not sum it. It also disappears over long windows, see Good to know. |
| oneClickLeads | Leads through the native form. | With oneClickLeadFormOpens, which is who opened it. |
| externalWebsiteConversions | Site conversions, through the LinkedIn tag. | Depends on the tag being installed on the client's site. |
Dimensions3
| API field | What it is | Where it shows up |
|---|---|---|
| day | The day of the row. | Every performance table comes by day. |
| campaign_id | LinkedIn's campaign, which is the ad set. | What the client calls a campaign is the campaign group, a separate table. |
| account_id | The ad account. | Present in both performance tables. |
Report parameters
The fields above say what comes back. These parameters say how: they decide the grain of the row, the period it covers and what counts as a conversion. Two reports from the same account showing different numbers almost always differ here.
| Parameter | What it changes | Values |
|---|---|---|
| pivot | The grain of each row. | CAMPAIGN (which is the ad set) and CREATIVE. The API refuses two pivots at once: asking for campaign and region in the same call returns HTTP 400. |
| timeGranularity | The aggregation. | caOS asks for DAILY. The API also accepts monthly and the whole period in one row. |
| fields | The metrics requested. | The list in the table above. Targeting fields are excluded: they are complex objects and break the load. |
| dateRange | The period. | Comes from the source. Beyond ~90 days reach stops coming back, with no error. |
Everything you can pull
The tables above are what most reports use, but you are not stuck with them. The full LinkedIn catalogue has 8 tables and 148 fields, and you choose what goes in when you build the source. What is marked used by default is what the example source uses; the rest is available just the same.
The list below comes from the Xtractor catalogue itself, the same one the new source screen reads. If a field is here, the screen offers it.
campaigns36 fields
storyDeliveryEnabled, targeting, targetingCriteria, servingStatuses, totalBudget, version_tag, locale, version, associatedEntity, associated_entity_organization_id, associated_entity_person_id, optimizationTargetType, changeAuditStamps, campaignGroup, campaign_group_id, dailyBudget, unitCost, creativeSelection, costType, name, objectiveType, offsiteDeliveryEnabled, offsitePreferences, id, audienceExpansionEnabled, test, format, pacingStrategy, account, account_id, status, type, created_time, last_modified_time, run_schedule_start, run_schedule_end
ad_analytics_by_campaign used by default25 fields
campaign_id, clicks, costInLocalCurrency, comments, dateRange, day, impressions, landingPageClicks, likes, oneClickLeadFormOpens, oneClickLeads, otherEngagements, shares, totalEngagements, videoViews, videoFirstQuartileCompletions, videoMidpointCompletions, videoThirdQuartileCompletions, videoCompletions, reactions, follows, videoStarts, externalWebsiteConversions, approximateMemberReach, account_id
accounts21 fields
changeAuditStamps, created_time, last_modified_time, currency, id, name, notifiedOnCampaignOptimization, notifiedOnCreativeApproval, notifiedOnCreativeRejection, notifiedOnEndOfCampaign, notifiedOnNewFeaturesEnabled, reference, reference_organization_id, reference_person_id, servingStatuses, status, total_budget, total_budget_ends_at, type, test, version
creatives18 fields
account, account_id, campaign, campaign_id, content, reference, review, createdAt, created_time, last_modified_time, createdBy, lastModifiedAt, lastModifiedBy, id, intendedStatus, isServing, isTest, servingHoldReasons
campaign_groups15 fields
changeAuditStamps, created_time, last_modified_time, name, servingStatuses, backfilled, id, account, account_id, status, total_budget, test, allowed_campaign_types, run_schedule_start, run_schedule_end
ad_analytics_by_creative used by default14 fields
clicks, shares, landingPageClicks, comments, creative_id, costInLocalCurrency, dateRange, day, impressions, likes, oneClickLeadFormOpens, oneClickLeads, otherEngagements, totalEngagements
video_ads10 fields
account, account_id, changeAuditStamps, created_time, last_modified_time, content_reference, content_reference_ucg_post_id, content_reference_share_id, name, type
account_users9 fields
account, campaign_contact, account_id, changeAuditStamps, created_time, last_modified_time, role, user, user_person_id
Output
Where the data landsa spreadsheet and a warehouse are different jobs
Google Sheets
For building a report by hand
Tick spend, impressions, clicks and the name. Remember LinkedIn spend arrives as text: if the spreadsheet sum comes out zero, that is why.
For the client to recognise the campaign name, tick the campaign groups table too: what they call a campaign lives there.
BigQuery
For modelling on top
8 datasets. Performance at two levels, always daily: by LinkedIn campaign (which is the ad set), with 25 fields including reach, engagement and video; and by creative, with 14 fields, without video and without reach.
Structure: accounts, account users, campaign groups, campaigns, creatives and video ads.
Trust
Data freshnesswhy yesterday's number still moves
Ad platforms rewrite the past. A conversion attributed days later, revised spend, a corrected row: Tuesday's number changes on Thursday. If the extraction only ever brought the newest day, your spreadsheet would freeze at the first value and drift away from the platform with nobody noticing.
So caOS re-reads the last 30 days on every sync and rewrites what changed. Older history stays in the destination and is not touched. In practice: what sits in your spreadsheet or your warehouse is what the platform says today, not what it said on the day of the first load.
Reach is the special case. It is approximate, and LinkedIn stops returning it, with no error at all, once the requested period goes beyond roughly 90 days. If your first load has an old start date and reach comes back empty, that is why. The other metrics arrive normally.
Detail
Good to knowwhat usually raises questions
LinkedIn's “campaign” is the ad set. What the client calls a campaign is the campaign group. The performance table comes at ad set level. To get the name they recognise, tick the groups table too.
Video, reactions, follows and reach only exist per campaign. The per creative table has cost, impressions, clicks and engagement, and no video or reach.
There is no region or demographic breakdown. When that breakdown was built outside, the platform refused to accept campaign and region together, and coverage landed near half of impressions: LinkedIn does not attribute a region to the rest, because of a privacy threshold.
Two fields that break the load. The targeting fields on the campaigns table are complex objects and have brought the load down before. Tick only the simple fields you actually use.
Support
When it failsthe message and what to do
“Invalid state.” The window stayed open for more than 10 minutes, or the link was used twice. Start again from the button.
It says authenticated and no account appears. Either the login has no access to any ad account, or the lookup failed. Reload Sources; if it stays empty, redo it with the right login.
The card shows a padlock when creating the source. caOS only unlocks LinkedIn once an account has been chosen: an active credential with no account added counts the same as no connection.
Accounts are missing, and they were not the discarded ones. caOS asks for one page of 100 accounts and does not continue past it. A login reaching more than 100 brings only the first 100. Authorise with a narrower login.