---
title: "LinkedIn Ads MCP: Ad Library tools and limits"
description: "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."
---

> For AI agents: the full docs index is at [https://useproxy.dev/docs/llms.txt](https://useproxy.dev/docs/llms.txt). Append `.md` to any docs URL for Markdown.

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](https://useproxy.dev/docs/tools/linkedin-ads).

:::note
LinkedIn's library covers the past year, through yesterday. Dates outside that window are moved inside it, and the response says which range was used.
:::

## Connect

One endpoint serves every client and every platform:

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

Sign-in is OAuth, with no API keys. Steps per client are in [Connect your client](https://useproxy.dev/docs/clients), with deeper notes for [Claude](https://useproxy.dev/docs/ads-mcp-claude), [ChatGPT](https://useproxy.dev/docs/ads-mcp-chatgpt) and [Claude Code](https://useproxy.dev/docs/ads-mcp-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](https://useproxy.dev/docs/tools/analysis#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](https://useproxy.dev/docs/credits).

## 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

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

`search_linkedin_ads` with `company_name`. 1 credit.

```text
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.

```text
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.

```text
Get the next two pages of that search.
```

Two `search_linkedin_ads` calls with `pagination_token`. 2 credits.

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

Three `get_linkedin_ad_details` calls. 3 credits.

## Guides

- [How to see competitors' LinkedIn ads](https://useproxy.dev/blog/how-to-see-competitors-linkedin-ads)
- [Free ad libraries compared](https://useproxy.dev/blog/free-ad-libraries-compared)
- [Research a prospect's ads before a pitch](https://useproxy.dev/blog/research-a-prospects-ads-before-a-pitch)
