Advanced Analytica Advanced Analytica: IBOM
← All connectors
LinkedIn Ads logo

Source connector

LinkedIn Ads

Set up LinkedIn Ads as a source and move its data into your chosen destination.

Version 6.2.11 certified generally available

LinkedIn Ads

Use this page to set up the LinkedIn Ads source connector and find reference information.

Prerequisites

  • A LinkedIn Ads account with permission to access data from the accounts you want to sync.
  • A start date in YYYY-MM-DD format. The connector doesn’t replicate data from before this date.

Setup guide

Step 1: Set up LinkedIn Ads

For Airbyte Cloud, Oauth2.0 authentication significantly simplifies setup. You can authenticate your account directly from the Airbyte UI.

Set up authentication for Airbyte Open Source

To authenticate the connector in Airbyte Open Source, create a LinkedIn developer application. Then obtain one of these credentials:

  1. OAuth2.0 credentials, consisting of:

    • Client ID
    • Client Secret
    • Refresh Token (expires after 12 months)
  2. Access Token (expires after 60 days)

Follow the steps below to create the application and obtain the required credentials. For an authentication overview, see the official documentation.

Create a LinkedIn developer application

  1. Log in to LinkedIn with a developer account.

  2. Go to the Apps page and click the Create App icon. Complete these fields:

    1. For App Name, enter a name.
    2. For LinkedIn Page, enter your company’s name or LinkedIn Company Page URL.
    3. For Privacy policy URL, enter the link to your company’s privacy policy.
    4. For App logo, upload your company’s logo.
    5. Check I have read and agree to these terms, then click Create App. LinkedIn redirects you to your application’s details page.
  3. Verify your app by following these steps:

    1. Click the Settings tab. In the App Settings section, click Verify under Company. A popup window appears. Click Generate URL to generate the verification URL. Copy and send the URL to the Page Admin, who may be you. Click I’m done. If you administer the Page, open the URL in a new tab. Otherwise, an administrator must complete the next step. Click Verify.

    2. Click the Product tab to display the Products page. For Marketing Developer Platform, click Request access. A popup window appears. Review and select I have read and agree to these terms. Finally, click Request access.

Authorise your app

  1. Click the Auth tab to authorise your application. Copy the Client ID and Client Secret. Click the open eye icon to reveal the client secret. In the Oauth 2.0 settings, click the pencil icon and provide your app’s redirect URL.

  2. Click the OAuth 2.0 tools link in the Understanding authentication and OAuth 2.0 section on the right side of the page.

  3. Click Create token.

  4. Select the scopes you want your app to use. The connector requires these scopes:

    • r_ads - Read ad accounts and related data
    • r_ads_reporting - Read ad analytics and reporting data
    • r_basicprofile - Read basic profile information
    • r_liteprofile - Read lite profile information
    • r_emailaddress - Read email address
    • r_organization_social - Read organization social data
    • r_organization_admin - Read organization admin data
    • r_events - Read events data
    • r_1st_connections_size - Read first-degree connection count
    • r_marketing_leadgen_automation - Read lead gen form data
    • r_ads_leadgen_automation - Read lead gen automation data

    Available scopes depend on your LinkedIn API programme access level. You need at least r_ads and r_ads_reporting to sync ad account data and analytics. The Videos stream also requires r_organization_social. See Videos.

  5. Click Request access token. LinkedIn redirects you to an authorisation page. Sign in with your LinkedIn credentials and authorise your app. You then receive your Access Token and Refresh Token.

:::caution These tokens won’t appear again. Copy them and store them securely. :::

:::tip If either token expires, return to LinkedIn’s Token Generator to generate a new one. You can check your tokens’ status using the Token Inspector. :::

Step 2: Set up the connector in Airbyte

Airbyte Cloud

  1. Log into your Airbyte Cloud account.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select LinkedIn Ads from the Source type dropdown.
  4. Enter a name for the LinkedIn Ads connector.
  5. To authenticate:
  • Select OAuth2.0 from the Authentication dropdown, then click Authenticate your LinkedIn Ads account. Sign in to your account and click Allow.

Airbyte Open Source

  1. Go to the Airbyte Open Source dashboard.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select LinkedIn Ads from the Source type dropdown.
  4. Enter a name for the LinkedIn Ads connector.
  5. To authenticate:
  • Select an option from the Authentication dropdown:
    1. OAuth2.0: Enter your Client ID, Client Secret and Refresh Token. The refresh token expires after 12 months.
    2. Access Token: Enter your Access Token. The access token expires after 60 days.
  1. For Start Date, use the provided datepicker or enter a date programmatically in YYYY-MM-DD format. The connector won’t replicate data from before this date.
  2. (Optional) For Account IDs, provide a space-separated list of Account IDs to pull data from. Without Account IDs, the connector replicates data from every account accessible with your credentials.
  3. (Optional) For Lookback Window, enter how many days before the last saved cursor each incremental sync re-fetches. This window applies to every incremental stream. It captures late-arriving analytics values, including conversions and attribution updates. It also captures entities whose lastModified timestamp changed after the previous sync. The default is 0, which re-fetches nothing.
  4. (Optional) For Number of Workers, enter the number of concurrent workers syncing ad analytics streams. The default is 3. A higher value may improve sync speed but could increase the risk of reaching API rate limits.
  5. (Optional) For Custom Ad Analytics Reports, provide one or more custom reports to query through the LinkedIn Ads API. Custom reports can align the data pulled from LinkedIn Ads with your specific needs. To add a custom report:
  6. Click Add.
  7. Enter a Report Name. This becomes the stream name during replication, preceded by custom_.
  8. Select a Pivot Category from the dropdown. This sets the main dimension used to group or segment the report data.
  9. Select a Time Granularity to group your report data by time. The options are:
    • ALL: Data isn’t grouped by time, providing a cumulative view.
    • DAILY: Returns data grouped by day. Use this to monitor short-term changes and effects closely.
    • MONTHLY: Returns data grouped by month. Use this to assess monthly goals or observe seasonal patterns.
    • YEARLY: Returns data grouped by year. Use this for high-level analysis of long-term trends and year-over-year comparisons.
  10. (Optional) For Custom Ad Statistics Reports, provide one or more reports that use LinkedIn’s Statistics Finder. This groups results by up to three pivot categories at once. To add a statistics report:
  11. Click Add.
  12. Enter a Report Name. This becomes the stream name during replication, preceded by custom_statistics_.
  13. Select up to three Pivot Categories. Airbyte sends them using LinkedIn’s Statistics Finder (q=statistics) request format.
  14. Select a Time Granularity using the same options listed above.

Note: Analytics reports become streams named custom_<Report Name>. Statistics reports become streams named custom_statistics_<Report Name>. Report names must be unique within each list. Don’t name an analytics report statistics_<something>, as it would conflict with a statistics report named <something>. 12. Click Set up source and wait for the tests to finish.

Supported sync modes

The LinkedIn Ads source connector supports these sync modes:

Supported streams

:::info

The Organizations stream returns the authenticated member’s organisation access control (ACL) records. It returns one row for each organisation and role, including the organisation URN, role and state. The stream returns all role states: APPROVED, REQUESTED, REJECTED and REVOKED. Filter the state field if you only need approved roles. This stream requires the r_organization_admin or rw_organization_admin OAuth scope. Without it, LinkedIn returns a 403 for this stream only.

:::

:::info

For Ad Analytics Streams such as Ad Analytics by Campaign and Ad Analytics by Creative, the pivot column is renamed to pivotValue. This supports correct data normalisation and prevents name conflicts with certain destinations. The field contains the associated entity’s ID as a URN. See the LinkedIn documentation for the Ad Analytics streams’ URN value format.

:::

Performance considerations

Rate limits

LinkedIn Ads applies Official Rate Limits for API Usage, more information here. Rate-limited requests receive a 429 response. These limits reset every day at midnight UTC. In rare cases, LinkedIn may also return a 429 response to protect its infrastructure. API service returns to normal automatically. In these cases, you receive this error message:

"Caught retriable error '<some_error> or null' after <some_number> tries. Waiting <some_number> seconds then retrying..."

This response is expected when the connector reaches the 429 - Rate Limit Exceeded HTTP Error. The connector automatically retries rate-limited requests using exponential backoff. For persistent rate limiting, check Rate Limits on this page > Choose your app > Analytics.

Ad analytics streams

LinkedIn Ads supports several streams that provide ad effectiveness metrics for a specified date range. These cover properties and dimensions such as clicks, follows, impressions, reactions and totalEngagements, among others. Fetching every property for each ad object can increase sync times.

To improve sync performance, select only the columns you need in your downstream destination. Selecting fewer columns should reduce sync duration.

:::caution

The LinkedIn Ads API doesn’t return records without values for any specified dimension. Select columns carefully, as your selection may produce fewer or more records.

:::

Data type map

Integration TypeAirbyte TypeNotes
numbernumberfloat number
integerintegerwhole number
datestringFORMAT YYYY-MM-DD
datetimestringFORMAT YYYY-MM-DDThh:mm:ss
arrayarray
booleanbooleanTrue/False
stringstring

Limitations

Lead forms and responses

The Lead forms and Lead form responses streams only support Full Refresh sync mode. Incremental sync isn’t available because the LinkedIn API limits time-range filtering for lead data.

Videos

The Videos stream returns videos referenced by each sponsored account’s ad creatives. This includes the video duration in milliseconds. For each creative, the connector resolves the referenced sponsored-content post. It then fetches the video embedded in that post. The stream therefore covers videos used in ads. You can join it with the Creatives stream through the creative’s content.reference. It only supports Full Refresh sync mode. The LinkedIn API doesn’t provide a modification timestamp suitable for filtering.

Keep these limitations in mind:

  • A video used by several creatives or posts appears once per reference. Deduplicate using the id primary key for one row per video.
  • The Videos API can’t retrieve legacy media assets uploaded through the deprecated Assets API (urn:li:digitalmediaAsset: URNs). The connector skips them.
  • The connector skips deleted or inaccessible posts and videos with a log message. They don’t cause the sync to fail.
  • Resolving a creative’s post requires the r_organization_social scope (Posts API permissions). The connector’s OAuth flow requests this scope. With a raw access token lacking this scope, every post lookup is skipped. The stream therefore completes with zero records.
  • Message Ads (Sponsored InMail) creatives reference InMail content (urn:li:adInMailContent: URNs), not a post. They can’t contain videos retrievable through the Videos API. The post lookup returns a 400. The connector skips the creative with a log message instead of failing the sync.
  • The stream intentionally doesn’t use the Videos API associatedAccount finder for the account’s whole media library. LinkedIn controls access to that finder at application level. Applications with only the r_ads scope receive 403 ACCESS_DENIED from it. Fetching each video by URN works with the standard scopes this connector already requests.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Troubleshooting

  • Invalid or expired access token (401): Re-authenticate the source to get a valid LinkedIn access token.
  • Ad account access denied (403): Authorise the r_ads scope to read ad accounts. Confirm the authorised member has access in Campaign Manager. If LinkedIn identifies another missing scope, such as rw_ads, grant it and re-authenticate.

Changelog

Expand to review
VersionDatePull RequestSubject
6.2.112026-11-1086483Replace YAML anchors with declarative $ref for the shared analytics property list (no functional change)
6.2.102026-11-1091628Update dependencies
6.2.92026-10-3090258Explain authentication and missing scopes in connection checks
6.2.82026-11-0389292Update dependencies
6.2.72026-11-0290379Restore the creatives stream’s DNS retry diagnostic while preserving rate-limit and server-error handling.
6.2.62026-10-1388690Update dependencies
6.2.52026-10-0687926Update dependencies
6.2.42026-09-2986321Fix the videos stream failing on Message Ads (Sponsored InMail) creatives and on creatives with a null content.reference
6.2.32026-09-2987239Update dependencies
6.2.22026-09-2286716Update dependencies
6.2.12026-09-1584019Update dependencies
6.2.02026-09-1476087Add organizations stream via the organizationAcls endpoint
6.1.02026-09-1481509Add videos stream
6.0.22026-07-3183268Fix pivot in custom analytics report streams to contain the configured pivot category.
6.0.12026-07-3183269Fix invalid error_handlers manifest key so the custom error handler and exponential backoff are actually applied
6.0.02026-07-3074334Batch analytics requests for ad_campaign_analytics, ad_creative_analytics, and ad_impression_device_analytics in groups of up to 50, reducing sync time by approximately 98% for large accounts. Breaking change for ad_impression_device_analytics only: its primary key now includes sponsoredCampaign, preventing records from different campaigns from being collapsed in deduplication mode. Refresh the source schema after upgrading; deduplication users should refresh this stream to rebuild destination data.
5.7.02026-07-3078505Add custom_statistics_report stream and ad_statistics_reports config for LinkedIn Statistics Finder reports (up to three pivots).
5.6.132026-07-2883194Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override
5.6.122026-07-2883183Roll Cloud back to 5.6.10 — 5.6.11 is built on SDM 7.23.7, which breaks bundled custom components
5.6.112026-07-2883018Update dependencies
5.6.102026-07-2177286Update dependencies
5.6.92026-04-2173947Update dependencies
5.6.82026-04-0776120Fix dynamic stream name field_path to avoid parent stream name collision
5.6.72026-04-0676040Replace deprecated MessageRepresentationAirbyteTracedErrors with AirbyteTracedException in tests
5.6.62026-04-0675583Add oauth_connector_input_specification with granular scopes
5.6.52026-03-3075597Map HTTP 429 responses to RATE_LIMITED instead of RETRY for proper indefinite backoff on rate-limited requests
5.6.42026-02-1172831Upgrade LinkedIn API version from 202502 to 202601
5.6.32026-02-1072768Update dependencies
5.6.22026-01-2072028Update dependencies
5.6.12026-01-1468982Update dependencies
5.6.02025-11-0469180Promoting release candidate 5.6.0-rc.1 to a main version.
5.6.0-rc.12025-10-2968614Upgrade to latest CDK to only include the selected columns of the schema in API requests for ad analytics streams
5.5.52025-10-2868626Increase concurrency and introduce initial attempt at API budget
5.5.42025-10-2164967Update dependencies
5.5.32025-10-1467564Upgrade to CDK v7.
5.5.22025-07-1663336Promoting release candidate 5.5.2-rc.1 to a main version.
5.5.2-rc.12025-06-2360996Fix to properly manage pagination for Lead forms and Lead form responses streams
5.5.12025-06-1861639Reduce default concurrency level to 3 and enable configurability via num_workers config property
5.5.02025-04-2859116Promoting release candidate 5.5.0-rc.1 to a main version.
5.5.0-rc.12025-04-2558628Convert to manifest-only format
5.4.12025-04-2358134Fix to properly retrieve approximateMemberReach for adAnalytics streams following v5.3.3.
5.4.02025-04-2258593Promoting release candidate 5.4.0-rc.1 to a main version.
5.4.0-rc.12025-04-1858114Removes custom retrievers and cursors from analytics streams so that they can take up concurrency.
5.3.32025-03-1255724Update outdated schema approximateUniqueImpressions to new approximateMemberReach for adAnalytics streams.
5.3.22025-03-0855447Update dependencies
5.3.12025-03-0555211Update dependencies
5.3.02025-03-0255171Migrate API to v202502
5.2.32025-03-0154813Update dependencies
5.2.22025-02-2253308Update dependencies
5.2.12025-02-1053611Add schema precisions for Lead forms and Lead form responses streams
5.2.02025-02-0452047Add Lead forms and Lead form responses new streams - See Limits & considerations
5.1.62025-02-0249458Update Linkedin Ads API version to 202410 for creatives stream
5.1.52025-02-0152791Update dependencies
5.1.42025-01-3052604Fix state error
5.1.32025-01-2252604Update CDK to production ^6
5.1.22025-01-2552253Update dependencies
5.1.12025-01-1547092Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
5.1.02025-01-1448863Custom streams moved to manifest implementation & URL Error Handling
5.0.02024-11-2648451Update primary keys for streams ad_campaign_analytics, Custom Ad Analytics Reports and account_users
4.1.42024-10-1246862Update dependencies
4.1.32024-10-0546433Update dependencies
4.1.22024-09-2846171Update dependencies
4.1.12024-09-2145774Update dependencies
4.1.02024-09-2044370Migrate to low-code
4.0.62024-09-1445532Update dependencies
4.0.52024-09-0745209Update dependencies
4.0.42024-08-3144950Update dependencies
4.0.32024-08-2444682Update dependencies
4.0.22024-08-1744220Update dependencies
4.0.12024-08-1043629Update dependencies
4.0.02024-08-0743359Revert low code migration
3.0.12024-08-0343087Update dependencies
3.0.02024-06-1838314Migrate to low-code
2.1.122024-07-2742728Update dependencies
2.1.112024-07-2042291Update dependencies
2.1.102024-07-1341710Update dependencies
2.1.92024-07-1041517Update dependencies
2.1.82024-07-0941315Update dependencies
2.1.72024-07-0640868Update dependencies
2.1.62024-06-2540331Update dependencies
2.1.52024-06-2239998Update dependencies
2.1.42024-06-1639442Fix README commands, change spec from json to yaml, fix schema states to object
2.1.32024-06-0639240[autopull] Upgrade base image to v1.2.2
2.1.22024-05-0736648Schema descriptions
2.1.12024-05-0738013Fix an issue where the Accounts stream did not correctly handle provided account IDs
2.1.02024-04-3037573Update API version to 202404; add cursor-based pagination
2.0.02024-04-2437531Change primary key for Analytics Streams
1.0.12024-03-2834152Proceed pagination if return less than expected
1.0.02024-04-1036927Update primary key for Analytics Streams
0.8.02024-03-1936267Pin airbyte-cdk version to ^0
0.7.02024-02-2035465Per-error reporting and continue sync on stream failures
0.6.82024-02-0935086Manage dependencies with Poetry
0.6.72024-01-1134152Prepare for airbyte-lib
0.6.62024-01-1534222Use stream slices for Analytics streams
0.6.52023-12-1533530Fix typo in Pivot Category list
0.6.42023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
0.6.32023-10-1331396Fix pagination for reporting
0.6.22023-08-2331221Increase max time between messages to 24 hours
0.6.12023-08-2329600Update field descriptions
0.6.02023-08-2229721Add Conversions stream
0.5.02023-08-1429175Add Custom report Constructor
0.4.02023-08-0829175Add analytics streams
0.3.12023-08-0829189Fix empty accounts field
0.3.02023-08-0729045Add new fields to schemas; convert datetime fields to rfc3339
0.2.12023-05-3026780Reduce records limit for Creatives Stream
0.2.02023-05-2326372Migrate to LinkedIn API version: May 2023
0.1.162023-05-2426512Removed authSpecification from spec.json in favour of advancedAuth
0.1.152023-02-1322940Specified date formatting in specification
0.1.142023-02-0322361Turn on default HttpAvailabilityStrategy
0.1.132023-01-2722013For adDirectSponsoredContents stream skip accounts which are part of organization
0.1.122022-10-1818111For adDirectSponsoredContents stream skip accounts which are part of organization
0.1.112022-10-0717724Retry 429/5xx errors when refreshing access token
0.1.102022-09-2817326Migrate to per-stream states.
0.1.92022-07-2114924Remove additionalProperties field from schemas
0.1.82022-06-0713495Fixed base-normalization issue on Destination Redshift caused by wrong casting of pivot column
0.1.72022-05-0412482Update input configuration copy
0.1.62022-04-0411690Small documentation corrections
0.1.52021-12-218984Update connector fields title/description
0.1.42021-12-028382Modify log message in rate-limit cases
0.1.32021-11-117839Added OAuth support
0.1.22021-11-087499Remove base-python dependencies
0.1.12021-10-026610Fix for Campaigns/targetingCriteria transformation, coerced Creatives/variables/values to string by default
0.1.02021-09-055285Initial release of Native LinkedIn Ads connector for Airbyte
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.