For AI agents: the full docs index is at /docs/llms.txt. Append .md to any docs URL for Markdown.
Skip to content
Proxy Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

LinkedIn Ads MCP: Ad Library tools and limits

How Proxy's LinkedIn Ads MCP reads the LinkedIn Ad Library: search by company or keyword, the one-year date window, paging tokens, fields and credit cost.

Proxy connects an assistant to the public LinkedIn Ad Library. It can pull any company’s LinkedIn ads or search every advertiser by keyword. It is read-only and never connects to Campaign Manager.

This page documents exactly how the two LinkedIn tools behave. For the short parameter tables, see the LinkedIn tool reference.

Connect

One endpoint serves every client and every platform:

https://mcp.useproxy.dev/mcp?ref=docs

Sign-in is OAuth, with no API keys. Steps per client are in Connect your client, with deeper notes for Claude, ChatGPT and Claude Code.

Which tool fires when

You ask for Tool chain
A company’s LinkedIn ads search_linkedin_ads with company_name
Ads about a topic search_linkedin_ads with keyword
More of the same search search_linkedin_ads with the pagination_token
Targeting or impressions for one ad get_linkedin_ad_details with the ad id

There is no separate ID lookup step. A company name goes straight into the search.

search_linkedin_ads

Parameter Default Accepted values and behaviour
company_name none Advertiser name. company is accepted as an alias
keyword none Free text, searched across all advertisers
company_id none LinkedIn company ID, for a precise match
countries all Comma-separated ISO codes, for example US,CA,MX
start_date none YYYY-MM-DD
end_date none YYYY-MM-DD
pagination_token none The paginationToken from the previous page

At least one of company_name, keyword or company_id is required. A call with none returns an error.

How dates are handled

LinkedIn needs both dates, and both must sit between 365 days ago and yesterday. So when you set either date:

  • A missing start_date becomes 365 days ago.
  • A missing end_date becomes yesterday.
  • A date outside the window is moved to its edge.

When anything was filled in or moved, the response includes “Date range used” with the actual range. With no dates at all, none are sent.

What each ad contains

Every row carries id, advertiser, poster, adType, description, has_image, has_video, has_carousel, totalImpressions, impressionsByCountry, startDate and ad_url.

  • description is cut to the first 100 characters in search results. The full text is in the ad details.
  • poster is the display name on the ad unit. It can differ from advertiser.
  • totalImpressions is a range string such as 5k-10k, never a count. It can be empty for running ads.
  • startDate can be empty for running ads.

The response also carries paginationToken and isLastPage.

get_linkedin_ad_details

Parameter Type Behaviour
ad_id string The id from a search result. One ad per call

Returns id, advertiser, poster, adType, description, headline, image, video, cta, destinationUrl, targeting, totalImpressions, impressionsByCountry, startDate, endDate and adDuration.

  • targeting can be an empty object. LinkedIn does not expose it for every ad.
  • impressionsByCountry is a list of country and share pairs. Shares are percentage strings such as 100% or less than 1%.
  • headline can be empty. Not every ad type has one.
  • startDate, endDate and adDuration can be empty for running ads.
  • An image URL can be passed to analyze_ad_image.

What it never contains

  • Spend, clicks, leads or bids.
  • Exact impression counts. Only ranges.
  • Ads last shown more than a year ago.
  • Guaranteed targeting data. Treat an empty targeting as “not exposed”, not “untargeted”.

Paging

  • Each call returns one page.
  • When isLastPage is false, pass paginationToken back as pagination_token to get the next page.
  • Keep the same search parameters when you page.

Credit cost

Call Credits
search_linkedin_ads 1 per call, so 1 per page
get_linkedin_ad_details 1 per ad

Free is 20 credits a day with no card, Pro is $50 a month for 100 a day, and Max is $100 a month for 250 a day. There is no overage billing. See Credits and plans.

Failure modes

Situation What the tool returns
No company, keyword or ID An error naming the three options
No matching ads Zero ads and a hint to use fewer filters or a shorter company name
Date outside the past year Results for the adjusted range, with “Date range used”
Wrong or removed ad_id “Failed to retrieve LinkedIn ad details” and a prompt to check the ID
Rate limit, timeout or outage A short retry hint. Raw upstream errors are never passed through

Worked prompts

Pull [company]'s LinkedIn ads and group them by the audience each one speaks to.

search_linkedin_ads with company_name. 1 credit.

Which companies advertise on LinkedIn around "SOC 2 compliance" in the US and UK?

search_linkedin_ads with keyword and countries US,GB. 1 credit.

Show [company]'s LinkedIn ads since 1 January two years ago.

search_linkedin_ads with start_date. The date is moved to 365 days ago and the response says so. 1 credit.

Get the next two pages of that search.

Two search_linkedin_ads calls with pagination_token. 2 credits.

For the three newest ads, show targeting and the country split of impressions.

Three get_linkedin_ad_details calls. 3 credits.

Guides

Was this page helpful?