LinkedIn Ads CLI Skill

You have access to

linkedin-ads-cli

, a read-only CLI for the LinkedIn Marketing API (REST API, version 202603). Use it to query ad accounts, pull performance analytics with pivot breakdowns, inspect creatives, explore audiences and targeting facets, retrieve lead form submissions, and get budget and delivery forecasts.

Quick start

# Check if the CLI is available
linkedin-ads-cli --help

# Get authenticated user info
linkedin-ads-cli me

# List organizations you administer
linkedin-ads-cli organization-acls

# List ad accounts
linkedin-ads-cli accounts

If the CLI is not installed, install it:

npm install -g linkedin-ads-cli

Authentication

The CLI requires a LinkedIn OAuth2 Bearer token. Credentials are resolved in this order:

1. --credentials <path>

   flag (per-command)
2. Environment variable:

   LINKEDIN_ADS_ACCESS_TOKEN

3. Auto-detected file:

   ~/.config/linkedin-ads-cli/credentials.json

Required OAuth scopes depend on the commands used:

• r_ads

  -- read ad accounts and campaigns

• r_ads_reporting

  -- read ad analytics

• r_organization_social

  -- read organization data

Before running any command, verify credentials are configured by running

linkedin-ads-cli me

. If it fails with a credentials error, ask the user to set up authentication.

Entity hierarchy

Organization (Company Page)
 +-- Ad Account (urn:li:sponsoredAccount:XXXXX)
      +-- Campaign Group
      |    +-- Campaign
      |         +-- Creative
      +-- Matched Audience (DMP Segment)
      +-- Conversion Rule
      +-- Insight Tag
      +-- Lead Gen Form

LinkedIn uses URN format for IDs (e.g.,

urn:li:sponsoredAccount:123456

). The CLI accepts both full URNs and plain numeric IDs for all commands that take entity IDs.

When chaining commands, extract the numeric ID from URNs (the part after the last colon). For example,

organization-acls

returns organization URNs like

urn:li:organization:12345678

-- use

12345678

with the

organization

command.

Most list commands require the parent entity ID. Start with

me

to get your profile, then

organization-acls

to find organizations you manage, then

accounts

to find ad accounts.

Monetary values

The analytics API returns monetary fields as-is from LinkedIn. The

costInLocalCurrency

field is in the account's local currency and

costInUsd

is in USD. Both are returned as decimal string values from the API in the major currency unit (e.g.

"244.85000"

).

Output format

All commands output pretty-printed JSON by default. Use

--format compact

for single-line JSON (useful for piping).

Two pagination styles exist depending on the command:

• Token-based: uses

  --page-size

  and

  --page-token

  (look for

  pageToken

  in the response for the next page)
• Offset-based: uses

  --count

  and

  --start

  (increment

  --start

  by

  --count

  for the next page)

Commands reference

User & organization discovery

# Authenticated user profile
linkedin-ads-cli me

# Get an organization (company page) by numeric ID
linkedin-ads-cli organization 12345678

# List organizations the authenticated user administers
linkedin-ads-cli organization-acls
linkedin-ads-cli organization-acls --role ADMINISTRATOR
linkedin-ads-cli organization-acls --count 50 --start 0

organization-acls

options:

• --count <n>

  -- results per page (default 100)

• --start <n>

  -- start index (default 0)

• --role <role>

  -- filter by role: ADMINISTRATOR, DIRECT_SPONSORED_CONTENT_POSTER, etc.

Ad accounts

# List ad accounts
linkedin-ads-cli accounts
linkedin-ads-cli accounts --search "My Company"
linkedin-ads-cli accounts --page-size 50

# Get a specific ad account (numeric ID or full URN)
linkedin-ads-cli account 123456789
linkedin-ads-cli account urn:li:sponsoredAccount:123456789

# List users with access to an ad account
linkedin-ads-cli account-users 123456789
linkedin-ads-cli account-users 123456789 --count 50 --start 0

accounts

options (token-based pagination):

• --page-size <n>

  -- results per page (default 100)

• --page-token <token>

  -- page token for pagination

• --search <query>

  -- search by account name or ID

account-users

options (offset-based pagination):

• --count <n>

  -- results per page (default 100)

• --start <n>

  -- start index (default 0)

Campaign groups & campaigns

# List campaign groups for an ad account
linkedin-ads-cli campaign-groups 123456789
linkedin-ads-cli campaign-groups 123456789 --page-size 50

# Get a specific campaign group
linkedin-ads-cli campaign-group 987654321

# List campaigns for an ad account
linkedin-ads-cli campaigns 123456789
linkedin-ads-cli campaigns 123456789 --status ACTIVE
linkedin-ads-cli campaigns 123456789 --campaign-group 987654321

# Get a specific campaign
linkedin-ads-cli campaign 111222333

campaign-groups

options (token-based pagination):

• --page-size <n>

  -- results per page (default 100)

• --page-token <token>

  -- page token for pagination

campaigns

options (token-based pagination):

• --page-size <n>

  -- results per page (default 100)

• --page-token <token>

  -- page token for pagination

• --status <status>

  -- filter by status: ACTIVE, PAUSED, ARCHIVED, COMPLETED, CANCELED, DRAFT

• --campaign-group <id>

  -- filter by campaign group ID

Creatives

# List creatives for an ad account
linkedin-ads-cli creatives 123456789
linkedin-ads-cli creatives 123456789 --campaign 111222333

# Get a specific creative
linkedin-ads-cli creative 444555666

creatives

options (token-based pagination):

• --page-size <n>

  -- results per page (default 100)

• --page-token <token>

  -- page token for pagination

• --campaign <campaign-id>

  -- filter by campaign ID

Analytics

The

analytics

command is the primary tool for performance analysis. It requires an account ID, a date range, and supports pivot breakdowns.

# Basic analytics for a date range
linkedin-ads-cli analytics 123456789 --start-date 2026-01-01 --end-date 2026-01-31

# Daily granularity with campaign pivot
linkedin-ads-cli analytics 123456789 --start-date 2026-01-01 --end-date 2026-01-31 --granularity DAILY --pivot CAMPAIGN

# Monthly granularity with campaign group pivot
linkedin-ads-cli analytics 123456789 --start-date 2026-01-01 --end-date 2026-06-30 --granularity MONTHLY --pivot CAMPAIGN_GROUP

# Account-level aggregate
linkedin-ads-cli analytics 123456789 --start-date 2026-01-01 --end-date 2026-01-31 --granularity ALL --pivot ACCOUNT

# Filter by specific campaigns
linkedin-ads-cli analytics 123456789 --start-date 2026-01-01 --end-date 2026-01-31 --campaign-ids 111222333,444555666

# Filter by campaign groups
linkedin-ads-cli analytics 123456789 --start-date 2026-01-01 --end-date 2026-01-31 --campaign-group-ids 987654321

# Custom metric fields
linkedin-ads-cli analytics 123456789 --start-date 2026-01-01 --end-date 2026-01-31 --fields impressions,clicks,costInUsd

analytics

options:

• --start-date <date>

  -- start date in YYYY-MM-DD format (required)

• --end-date <date>

  -- end date in YYYY-MM-DD format (required)

• --granularity <gran>

  -- time granularity: DAILY, MONTHLY, ALL (default DAILY)

• --pivot <pivot>

  -- pivot dimension: CAMPAIGN, CAMPAIGN_GROUP, CREATIVE, ACCOUNT (default CAMPAIGN)

• --campaign-ids <ids>

  -- filter by campaign IDs (comma-separated, numeric or URN)

• --campaign-group-ids <ids>

  -- filter by campaign group IDs (comma-separated, numeric or URN)

• --fields <fields>

  -- metric fields (comma-separated)

Default metric fields (when

--fields

is not specified):

impressions

,

clicks

,

costInLocalCurrency

,

costInUsd

,

externalWebsiteConversions

,

likes

,

comments

,

shares

,

follows

,

videoViews

The CLI passes

--fields

and

--pivot

values directly to the LinkedIn API without validation. Additional fields and pivot values beyond the documented defaults may be available. Refer to the LinkedIn Ad Analytics API docs for the full list.

Audiences & targeting

# List matched audiences (DMP segments) for an ad account
linkedin-ads-cli audiences 123456789
linkedin-ads-cli audiences 123456789 --count 50 --start 0

# Get estimated audience size for targeting criteria
linkedin-ads-cli audience-counts 123456789

# List available targeting facets (industries, job titles, locations, etc.)
linkedin-ads-cli targeting-facets

audiences

options (offset-based pagination):

• --count <n>

  -- results per page (default 100)

• --start <n>

  -- start index (default 0)

audience-counts

takes only the account ID argument (no additional options).

targeting-facets

takes no arguments.

Conversions & tracking

# List conversion rules for an ad account
linkedin-ads-cli conversion-rules 123456789
linkedin-ads-cli conversion-rules 123456789 --count 50

# List LinkedIn Insight Tags for an ad account
linkedin-ads-cli insight-tags 123456789
linkedin-ads-cli insight-tags 123456789 --count 50

conversion-rules

options (offset-based pagination):

• --count <n>

  -- results per page (default 100)

• --start <n>

  -- start index (default 0)

insight-tags

options (offset-based pagination):

• --count <n>

  -- results per page (default 100)

• --start <n>

  -- start index (default 0)

Lead gen

# List Lead Gen forms for an ad account
linkedin-ads-cli lead-gen-forms 123456789
linkedin-ads-cli lead-gen-forms 123456789 --count 50

# List form responses (submissions) for an ad account
linkedin-ads-cli lead-form-responses 123456789
linkedin-ads-cli lead-form-responses 123456789 --form 777888999
linkedin-ads-cli lead-form-responses 123456789 --start-time 1709251200000 --end-time 1711929600000

lead-gen-forms

options (offset-based pagination):

• --count <n>

  -- results per page (default 100)

• --start <n>

  -- start index (default 0)

lead-form-responses

options (offset-based pagination):

• --count <n>

  -- results per page (default 100)

• --start <n>

  -- start index (default 0)

• --form <form-id>

  -- filter by form ID (numeric or URN)

• --start-time <time>

  -- filter responses after this time (epoch milliseconds)

• --end-time <time>

  -- filter responses before this time (epoch milliseconds)

Forecasting

# Get budget recommendations for a campaign
linkedin-ads-cli budget-recommendations 111222333

# Get ad delivery forecasts for an account
linkedin-ads-cli ad-forecasts 123456789

budget-recommendations

takes a campaign ID (numeric or URN). No additional options.

ad-forecasts

takes an account ID (numeric or URN). No additional options.

Workflow guidance

When the user asks for a quick overview

1. Run

   linkedin-ads-cli accounts

   to find accessible ad accounts
2. Use

   analytics

   with a recent date range and

   --granularity ALL --pivot ACCOUNT

   for a performance snapshot
3. Present the data with key metrics (impressions, clicks, cost, conversions)

When the user asks for deep analysis

1. Start with account-level analytics using

   --granularity ALL --pivot ACCOUNT

2. Add

   --pivot CAMPAIGN_GROUP

   to identify top/bottom campaign groups
3. Drill down with

   --pivot CAMPAIGN

   for individual campaign performance
4. Use

   --granularity DAILY

   with

   --pivot CAMPAIGN

   for daily trends to spot anomalies
5. Filter specific campaigns with

   --campaign-ids

   for detailed analysis
6. Cross-reference with

   creatives

   to review ad content

When the user asks about creative performance

1. Run

   analytics

   with

   --pivot CREATIVE

   to get creative-level metrics
2. Use

   creatives

   to list creatives for the account
3. Use

   creative

   to inspect the actual creative content

When the user asks about audience and targeting

1. Use

   audiences

   to see matched audiences (DMP segments) and their details
2. Use

   audience-counts

   to get estimated audience size for targeting criteria
3. Use

   targeting-facets

   to explore available targeting dimensions (industries, job titles, locations)

When the user asks about conversion tracking

1. Run

   conversion-rules

   to list conversion rules for the account
2. Run

   insight-tags

   to check active Insight Tags
3. Use

   analytics

   with

   externalWebsiteConversions

   in

   --fields

   to see conversion metrics

When the user asks about lead gen

1. Use

   lead-gen-forms

   with the account ID to list forms
2. Use

   lead-form-responses

   with the account ID to retrieve submissions
3. Filter by specific form with

   --form

   or by time range with

   --start-time

   /

   --end-time

When the user asks about budget planning

1. Use

   budget-recommendations

   with a campaign ID to get LinkedIn's budget suggestions
2. Use

   ad-forecasts

   with an account ID to get delivery forecasts
3. Combine with

   analytics

   historical data to compare forecasts against actual performance

Error handling

• Authentication errors -- ask the user to verify their access token and OAuth scopes
• "No credentials found" -- the user needs to set

  LINKEDIN_ADS_ACCESS_TOKEN

  , use

  --credentials

  , or place credentials at

  ~/.config/linkedin-ads-cli/credentials.json

• Empty analytics -- check the date range, ensure the account had active campaigns in the period, and verify the pivot dimension is appropriate
• Permission errors -- different commands require different scopes (

  r_ads

  ,

  r_ads_reporting

  ,

  r_organization_social

  ); check the required scopes list above
• URN format issues -- the CLI accepts both plain numeric IDs and full URN format (e.g.,

  123456789

  or

  urn:li:sponsoredAccount:123456789

  )

API documentation references

• linkedin-ads-cli documentation
• LinkedIn Marketing API overview
• Ad Accounts API
• Ad Analytics API
• Campaign Management
• Lead Gen Forms API