> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# LinkedIn Ads as a data source
> Bring data from LinkedIn Ads to Nekt.
LinkedIn Ads is a powerful tool for B2B marketers, offering unique targeting capabilities to reach a professional audience. With various ad formats and robust analytics, it helps businesses achieve their marketing objectives, from lead generation to brand awareness.
## Configuring LinkedIn Ads as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the LinkedIn Ads option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need your LinkedIn Ads OAuth credentials for this connection. You can generate these in your LinkedIn Developer portal. Once you have them, add the account access, then click **Next**.
* **Authorization**: Log in with a Linkedin account that has proper access to the LinkedIn Ads account you want to extract data from.
* **Account ID**: The ID for the LinkedIn Ads account you want to extract data from. This can be found on `https://www.linkedin.com/campaignmanager` right below the organization name on the left-side panel.
* **Start Date**: The earliest record date to sync. Records created or updated after the start date will be extracted.
* **Lookback window (days)**: (Default: 28) Number of days to subtract from the bookmark in incremental mode to re-fetch records. The effective start date will never be earlier than the configured start date.
Linkedin only returns up to 1-year of historical data for daily performance reports.
### 2. Select streams
Choose which data streams you want to sync - you can select all streams or pick specific ones that matter most to you.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
* Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
Optionally, you can define some additional settings:
* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from LinkedIn Ads and their corresponding fields:
Stream for fetching ad accounts information.
**Key Fields:**
| Field | Type | Description |
| :------------------------------- | :------ | :--------------------------------------------------------------------------------------------------- |
| `id` | Integer | The account ID. |
| `name` | String | The account name. |
| `type` | String | The account type. |
| `status` | String | Current status of the account. |
| `currency` | String | The account's currency. |
| `reference` | String | The LinkedIn organization reference URN. |
| `changeAuditStamps` | Object | Audit timestamps for account creation and modification, including creator, modifier, and timestamps. |
| `notifiedOnCampaignOptimization` | Boolean | Whether notifications are enabled for campaign optimization. |
| `notifiedOnCreativeApproval` | Boolean | Whether notifications are enabled for creative approvals. |
| `notifiedOnCreativeRejection` | Boolean | Whether notifications are enabled for creative rejections. |
| `notifiedOnEndOfCampaign` | Boolean | Whether notifications are enabled for campaign end. |
| `servingStatuses` | Array | List of serving statuses for the account. |
| `test` | Boolean | Whether this is a test account. |
| `version` | Object | Version information for the account. |
Stream for fetching campaign groups.
**Key Fields:**
| Field | Type | Description |
| :--------------------- | :------ | :------------------------------------------------------------- |
| `id` | Integer | Unique identifier of the record. |
| `name` | String | Name of the record. |
| `status` | String | Current status of the record. |
| `account` | String | Identifier of the associated account. |
| `runSchedule` | Object | Schedule for when the campaign group runs. |
| `changeAuditStamps` | Object | Audit timestamps for campaign group creation and modification. |
| `test` | Boolean | Whether this is a test record. |
| `servingStatuses` | Array | List of serving statuses for the campaign group. |
| `allowedCampaignTypes` | Array | List of campaign types allowed in the group. |
| `backfilled` | Boolean | Whether the campaign group was backfilled. |
Stream for fetching campaigns.
**Key Fields:**
| Field | Type | Description |
| :------------------------- | :------ | :----------------------------------------------------------------- |
| `id` | Integer | Unique identifier for the campaign. |
| `name` | String | Name of the campaign. |
| `status` | String | Current status of the campaign. |
| `type` | String | Type of campaign (e.g. SPONSORED\_UPDATES). |
| `account` | String | URN of the associated advertising account. |
| `campaignGroup` | String | URN of the campaign group. |
| `servingStatuses` | Array | Current serving status of the campaign. |
| `locale` | Object | Locale settings for the campaign, including country and language. |
| `version` | Object | Version information for the campaign. |
| `associatedEntity` | String | URN of the associated LinkedIn organization. |
| `test` | Boolean | Whether this is a test campaign. |
| `runSchedule` | Object | Campaign schedule information, including start and end timestamps. |
| `targeting` | Object | Targeting settings for the campaign. |
| `optimizationPreference` | Object | Campaign optimization preferences. |
| `optimizationTargetType` | String | Target type for campaign optimization. |
| `changeAuditStamps` | Object | Audit timestamps for campaign creation and last modification. |
| `dailyBudget` | Object | Daily budget settings, including amount and currency code. |
| `unitCost` | Object | Cost per unit settings, including amount and currency code. |
| `creativeSelection` | String | Creative selection method (e.g. OPTIMIZED). |
| `costType` | String | Cost type for the campaign (e.g. CPC). |
| `offsiteDeliveryEnabled` | Boolean | Whether offsite delivery is enabled. |
| `audienceExpansionEnabled` | Boolean | Whether audience expansion is enabled. |
Stream for fetching creatives and their associated contents.
**Key Fields:**
| Field | Type | Description |
| :------------------- | :------ | :----------------------------------------------- |
| `id` | Integer | Unique identifier for the creative. |
| `status` | String | Current status of the creative. |
| `campaign` | String | URN of the associated campaign. |
| `account` | String | URN of the associated account. |
| `createdAt` | Integer | Timestamp when the creative was created. |
| `servingHoldReasons` | Array | List of reasons why the creative is not serving. |
| `lastModifiedAt` | Integer | Timestamp when the creative was last modified. |
| `isTest` | Boolean | Whether this is a test creative. |
| `createdBy` | String | URN of the user who created the creative. |
| `isServing` | Boolean | Whether the creative is currently serving. |
| `lastModifiedBy` | String | URN of the user who last modified the creative. |
| `intendedStatus` | String | Intended status of the creative. |
| `content` | String | URN reference to the creative content. |
Stream for fetching aggregated analytics per campaign.
**Key Fields:**
| Field | Type | Description |
| :------------------------------------ | :------ | :----------------------------------------------- |
| `_id` | String | Unique identifier for the analytics data. |
| `account_id` | String | Account ID. |
| `campaign_id` | String | Campaign ID. |
| `date` | String | Date of the analytics data. |
| `impressions` | Integer | Number of impressions served. |
| `clicks` | Integer | Number of clicks received. |
| `totalEngagements` | Integer | Total engagements (clicks, likes, shares, etc.). |
| `costInLocalCurrency` | Number | Total cost in local currency. |
| `oneClickLeads` | Integer | Number of one-click leads. |
| `externalWebsitePostClickConversions` | Integer | Post-click conversions on external websites. |
| `externalWebsitePostViewConversions` | Integer | Post-view conversions on external websites. |
| `videoViews` | Integer | Number of video views. |
| `videoCompletions` | Integer | Number of completed video views. |
| `likes` | Integer | Number of likes. |
| `shares` | Integer | Number of shares. |
| `follows` | Integer | Number of follows. |
| `comments` | Integer | Number of comments. |
| `reactions` | Integer | Number of reactions. |
| `landingPageClicks` | Integer | Clicks to landing page. |
| `companyPageClicks` | Integer | Clicks to company page. |
| `sends` | Integer | Number of messages sent. |
| `opens` | Integer | Number of messages opened. |
Stream for fetching creative analytics.
**Key Fields:**
| Field | Type | Description |
| :------------------------------------ | :------ | :----------------------------------------------- |
| `_id` | String | Unique identifier for the analytics data. |
| `account_id` | String | Account ID. |
| `creative_id` | String | Creative ID. |
| `date` | String | Date of the analytics data. |
| `impressions` | Integer | Number of impressions served. |
| `clicks` | Integer | Number of clicks received. |
| `totalEngagements` | Integer | Total engagements (clicks, likes, shares, etc.). |
| `costInLocalCurrency` | Number | Total cost in local currency. |
| `oneClickLeads` | Integer | Number of one-click leads. |
| `externalWebsitePostClickConversions` | Integer | Post-click conversions on external websites. |
| `externalWebsitePostViewConversions` | Integer | Post-view conversions on external websites. |
| `videoViews` | Integer | Number of video views. |
| `videoCompletions` | Integer | Number of completed video views. |
| `likes` | Integer | Number of likes. |
| `shares` | Integer | Number of shares. |
| `follows` | Integer | Number of follows. |
| `comments` | Integer | Number of comments. |
| `reactions` | Integer | Number of reactions. |
| `landingPageClicks` | Integer | Clicks to landing page. |
| `companyPageClicks` | Integer | Clicks to company page. |
| `sends` | Integer | Number of messages sent. |
| `opens` | Integer | Number of messages opened. |
# Data Model
The following diagram illustrates the relationships between the core data streams in LinkedIn Ads. The arrows indicate the join keys that link the different entities.
```mermaid theme={null}
graph TD;
subgraph "Core Entities"
AdAccounts("Ad Accounts");
CampaignGroups("Campaign Groups");
Campaigns("Campaigns");
Creatives("Creatives");
end
subgraph "Performance Data"
CampaignAnalytics("Campaign Analytics");
CreativeAnalytics("Creative Analytics");
end
CampaignGroups -- "account" --> AdAccounts;
Campaigns -- "campaignGroup" --> CampaignGroups;
Campaigns -- "account" --> AdAccounts;
Creatives -- "campaign" --> Campaigns;
Creatives -- "account" --> AdAccounts;
CampaignAnalytics -- "account_id" --> AdAccounts;
CampaignAnalytics -- "campaign_id" --> Campaigns;
CreativeAnalytics -- "account_id" --> AdAccounts;
CreativeAnalytics -- "creative_id" --> Creatives;
```
## Implementation Notes
### API Resilience and Retries
The connector features built-in retry mechanisms and connection pooling for fetching creative content (such as InMail contents and sponsored conversation flows). These requests are routed through a robust SDK session utilizing backoff decorators. This ensures that transient network failures (e.g., "Network is unreachable" or general `ConnectionError` statuses) are automatically retried instead of crashing your sync process.
### API Limitations
* LinkedIn restricts daily performance reports to a maximum of **1-year of historical data**. If your start date requests records older than one year for analytics streams, only the past 365 days will be returned. Ensure your initial backfill expectations align with this API limitation.
## Skills for agents
LinkedIn Ads connector documentation as plain markdown, for use in AI agent contexts.