# LinkedIn Ad Library Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/linkedinadlibrary/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/linkedinadlibrary-search |

## Description

Search the LinkedIn Ad Library by advertiser, keyword, country, and date. Returns ad cards and pagination (2 credits).

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/linkedinadlibrary/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Airbus advertiser search

```json
{
  "results": [
    {
      "url": "https://www.linkedin.com/ad-library/detail/1585536544",
      "ad_id": "1585536544",
      "format": "image",
      "headline": "Airbus is Hiring",
      "image_url": "https://media.licdn.com/dms/image/v2/D4E10AQFZ54-UGWaraQ/image_627_1200/B56Z6EWmiMG0AU-/0/1780336978225/Airbus2026Q2Kinston1200x627jpg",
      "description": "Airbus is hiring in Kinston, NC where we are building advanced composite structures for the A350.",
      "advertiser_name": "Airbus",
      "advertiser_image_url": "https://media.licdn.com/dms/image/v2/C4D0BAQF2j_LDG_TOzg/company-logo_100_100/company-logo_100_100/0/1631375371456/airbusgroup_logo"
    }
  ],
  "pagination": {
    "next": "https://www.linkedin.com/ad-library/search?accountOwner=airbus&paginationToken=1585433394-1790883234944",
    "page": 1,
    "cursor": "1585433394-1790883234944",
    "per_page": 24,
    "total_pages": 54,
    "total_results": 1293
  }
}
```

## Documentation

## Overview
Search the LinkedIn Ad Library. Pass an **advertiser name** (`airbus`), a **keyword**, or a **full Ad Library search URL**. **2 credits** per call.

Each card includes the ad id, advertiser, format, headline, description, and preview image. Pagination is `{ results, pagination }`. Open `results[].url` with the ad endpoint for the full creative.

## Quickstart
```
GET https://api.piloterr.com/v2/linkedinadlibrary/search?account_owner=airbus
GET https://api.piloterr.com/v2/linkedinadlibrary/search?query=https://www.linkedin.com/ad-library/search?accountOwner=airbus
GET https://api.piloterr.com/v2/linkedinadlibrary/search?keyword=aerospace&countries=US
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | no* | Full search URL, or a keyword when `account_owner` is empty |
| `account_owner` | string | no* | Advertiser / company name (`accountOwner`) |
| `keyword` | string | no | Keyword filter on ad copy |
| `countries` | string | no | Comma-separated ISO codes, or `ALL` |
| `date_option` | string | no | `last-30-days`, `current-month`, `current-year`, `last-year`, `custom-date-range` |
| `start_date` / `end_date` | string | no | `YYYY-MM-DD` for a custom range |
| `cursor` | string | no | Opaque cursor from `pagination.cursor` |

*Provide a search target via `query` and/or `account_owner` (and optionally `keyword`).

## Response fields
| Field | Type | Description |
|---|---|---|
| `results[]` | array | Ad cards |
| `results[].ad_id` | string | Numeric LinkedIn ad id |
| `results[].advertiser_name` | string \| null | Advertiser shown on the card |
| `results[].url` | string | Detail URL. Pass it to the ad endpoint |
| `results[].format` | string | `image`, `video`, `carousel`, `event`, `document`, or `text` |
| `results[].headline` / `description` / `image_url` | string \| null | Creative preview |
| `pagination.per_page` | integer | Page size (24) |
| `pagination.total_results` / `total_pages` | integer \| null | Count when LinkedIn reports it |
| `pagination.next` / `cursor` | string \| null | Next page URL and opaque cursor |

## Notes
- A detail URL passed to search returns `400`. Use the ad endpoint.
- An empty result returns `404`, not an empty `200`.
- `format` is lowercase in the response.

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing target, detail URL, or unknown date option |
| `403` | LinkedIn auth wall |
| `404` | No ads for these filters |
| `500` | The Ad Library request failed |

## Related endpoints
- [LinkedIn Ad Library Ad](https://www.piloterr.com/library/linkedinadlibrary-ad)

## Main use cases
- List creatives an advertiser has run on LinkedIn
- Page through results with `pagination.cursor`
- Open each card with the ad endpoint for CTA, payer, and targeting