# Search LinkedIn ads

> Search LinkedIn's public Ad Library by advertiser or keyword.

- **Request:** `GET https://api.lurkapi.com/v1/linkedin/ads/search`
- **Auth:** `x-api-key` header ([get a free key](https://lurkapi.com/login?next=/dashboard))
- **Cost:** 1 credit per call. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)).
- **MCP tool:** `linkedin_search_ads` on `https://api.lurkapi.com/mcp`
- **Freshness:** responses are cached for up to 1 hour
- **Try it live:** https://lurkapi.com/docs/linkedin/search-ads#try (no signup)
- **Platform:** [LinkedIn](https://lurkapi.com/docs/linkedin.md) (linkedin.com)
- **Web page:** https://lurkapi.com/docs/linkedin/search-ads

## When to use this

One page of Ad Library previews, up to about 24 ads. Pass company (advertiser name), keyword, or both. Search previews may truncate ad text; use ad details to inspect one creative and its disclosures. Each page costs one credit and does not fetch the individual ad detail pages. Pass paginationToken with the same filters for the next page. Country codes are comma-separated and run dates use YYYY-MM-DD. LinkedIn covers roughly the last year; delivery and targeting disclosures depend on the ad and region. A missing total on pagination pages is null. Block pages and malformed pagination metadata are upstream failures.

## Parameters

All parameters go in the query string.

| Name | Type | Required | Default | Allowed values | Description | Example |
| --- | --- | --- | --- | --- | --- | --- |
| `company` | string | no |  |  | Advertiser name to search, e.g. HubSpot. |  |
| `keyword` | string | no |  |  | Words in the ad copy. | `hubspot` |
| `countries` | string | no |  |  | Only ads delivered in these countries, as comma-separated two-letter codes such as DE,FR. EU is not supported as a country filter. |  |
| `startDate` | string | no |  |  | First date of the custom date range, YYYY-MM-DD. Supply endDate too; LinkedIn covers roughly the past year. |  |
| `endDate` | string | no |  |  | Last date of the custom date range, YYYY-MM-DD. Supply startDate too. |  |
| `paginationToken` | string | no |  |  | Token from the previous page. Keep company, keyword, countries and dates the same. |  |

## Example request

Replace `YOUR_API_KEY` with your key, or set `LURKAPI_KEY` for the code. [Get a free key](https://lurkapi.com/login?next=/dashboard).

curl:

```bash
curl "https://api.lurkapi.com/v1/linkedin/ads/search?keyword=hubspot" \
  -H "x-api-key: YOUR_API_KEY"
```

JavaScript:

```js
const params = new URLSearchParams({
  keyword: "hubspot",
});
const res = await fetch(`https://api.lurkapi.com/v1/linkedin/ads/search?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.ads);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/linkedin/ads/search",
    params={
        "keyword": "hubspot",
    },
    headers={"x-api-key": os.environ["LURKAPI_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["ads"])
```

## Example response

A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in `…`.

200 OK (application/json):

```json
{
  "success": true,
  "credits_remaining": 999997,
  "credits_charged": 1,
  "ads": [
    {
      "id": "1629910236",
      "adLibraryUrl": "https://www.linkedin.com/ad-library/detail/1629910236",
      "advertiser": {
        "name": "SparkGrid Software",
        "url": null
      },
      "creativeType": "SPONSORED_STATUS_UPDATE",
      "format": "Single Image Ad",
      "text": "Keep sensitive files in Box while HubSpot workflows create folders, send…",
      "headline": "Governed Box document workflows, run from HubSpot.",
      "images": [
        "https://media.licdn.com/dms/image/v2/D5610AQEL3M7oKHGAzw/image-shrink_12…"
      ],
      "videos": [],
      "cta": null
    },
    {
      "id": "1578246174",
      "adLibraryUrl": "https://www.linkedin.com/ad-library/detail/1578246174",
      "advertiser": {
        "name": "Bill Stathopoulos",
        "url": null
      },
      "creativeType": "SPONSORED_STATUS_UPDATE",
      "format": "Single Image Ad",
      "text": "My team ran outbound campaigns on signals and got 53 positive replies fr…",
      "headline": null,
      "images": [
        "https://media.licdn.com/dms/image/v2/D4D22AQGvafUbekf-RQ/feedshare-shrin…"
      ],
      "videos": [],
      "cta": null
    }
  ],
  "total": 52399,
  "isLastPage": false,
  "paginationToken": "1578246174-1790604283338"
}
```

## Response fields

Every field of a successful response. `[]` marks a list: `a[].b` is the `b` of each item in `a`. **nullable** fields can be `null`; **optional** fields can be missing.

| Field | Type | Description |
| --- | --- | --- |
| `success` | `true` | Always true here; errors have `success: false`. |
| `credits_remaining` | `number` | Your balance after this call. On anonymous playground calls: free tries left today. |
| `credits_charged` | `number` | Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1). |
| `ads` | `object[]` | Ad previews in LinkedIn's search order. |
| `ads[].id` | `string` | LinkedIn Ad Library ad id. |
| `ads[].adLibraryUrl` | `string` | Public detail page for this ad. |
| `ads[].advertiser` | `object` | The advertiser shown on the ad. |
| `ads[].advertiser.name` | `string`, nullable | Advertiser name shown on the preview. |
| `ads[].advertiser.url` | `string`, nullable | Advertiser's LinkedIn page, when linked. |
| `ads[].creativeType` | `string`, nullable | Raw creative type LinkedIn publishes in its preview markup. |
| `ads[].format` | `string`, nullable | Human-readable ad format shown by LinkedIn, when available. |
| `ads[].text` | `string`, nullable | Visible ad copy. Search previews may truncate it; use ad details for the full public copy. |
| `ads[].headline` | `string`, nullable | Ad headline when the preview exposes one. |
| `ads[].images` | `string[]` | Preview and carousel image URLs in source order. URLs can expire. |
| `ads[].videos` | `object[]` | Video variants from the ad preview, or an empty list. |
| `ads[].videos[].url` | `string` | Playable video source URL. |
| `ads[].videos[].bitrate` | `number`, nullable | Source bitrate in bits per second when supplied by LinkedIn. |
| `ads[].cta` | `string`, nullable | Call-to-action text shown on the preview. |
| `total` | `number`, nullable | Total matching ads, when shown on the first search page; null on fragments without a count. |
| `paginationToken` | `string`, nullable | Token for the next page; null when LinkedIn supplies none. |
| `isLastPage` | `boolean` | True when LinkedIn reports the final page or a confirmed empty search. |

## Caching and freshness

Responses are cached for up to 1 hour, so a repeat call within that window can return the same data. It still costs 1 credit.

## Errors

Errors return `{ success: false, error, code, docs }` with the HTTP status below. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)). [All error codes](https://lurkapi.com/docs.md#errors).

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `missing_api_key` | No API key. Send it in the `x-api-key` header. |
| 401 | `invalid_api_key` | The key is unknown or was revoked. |
| 402 | `insufficient_credits` | Not enough credits for this call. Buy a pack or wait for tomorrow's top-up. |
| 405 | `method_not_allowed` | Endpoints take GET with query params. |
| 429 | `rate_limited` | Too many calls at once. Wait for the `retry-after` seconds, then retry. |
| 500 | `internal_error` | Something broke on our side. Retry; 5xx errors are free. |
| 502 | `upstream_error` | The platform didn't give a usable answer. Retry; 5xx errors are free. |
| 503 | `upstream_busy` | All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free. |
| 504 | `upstream_timeout` | The platform took over 30 seconds to answer. Retry; timeouts are free. |

## Use it in Claude

Once LurkAPI is [connected to Claude](https://lurkapi.com/docs.md#claude), this endpoint is the `linkedin_search_ads` tool. Ask in plain English, for example:

Ask Claude:

```text
Use LurkAPI's linkedin_search_ads with keyword "hubspot" and summarize what you find.
```

Claude calls `linkedin_search_ads` with arguments like these, and each call costs 1 credit:

Tool arguments:

```json
{
  "keyword": "hubspot"
}
```

Tool results skip nulls and empty lists to save tokens.

---

Previous: [LinkedIn company posts](https://lurkapi.com/docs/linkedin/company-posts.md) · Next: [LinkedIn ad details](https://lurkapi.com/docs/linkedin/ad.md)