API reference

LinkedIn Ad Library: GET /v1/linkedin/ads

Search the LinkedIn Ad Library by keyword, company id or company name, filtered by the countries an ad was shown in and dates within the last year.

Ads a pageabout 24One page per call; next_cursor for more.

Credits2 credits a pageOnly when the page has ads. Empty pages, errors and the sandbox are free.

CoversEvery country, the last 12 monthsSearch by q, company_id or company.

Request

curl "https://api.publicadsapi.com/v1/linkedin/ads?company=Contoso" \
  -H "authorization: Bearer $PADS_API_KEY"

Parameters

Every filter here is the library's own, run by the platform, so pages are full and total_estimate counts what matches. Anything else is 400 INVALID_INPUT naming it.

Authorizationstringheaderrequired

Bearer <key>. Keys starting pads_test_ get the sandbox (sample ads, never charged); keys starting pads_live_ read the platform and use credits.

qstringquerysend one of q, company_id, company

A keyword, matched against the ad's text. Also accepted as query or keyword.

Example: q=analytics

company_idstringquerysend one of q, company_id, company

LinkedIn's numeric company id, the advertiser.id of any of its ads.

Example: company_id=80000001

companystringquerysend one of q, company_id, company

A company name, matched as LinkedIn's advertiser search does.

Example: company=Contoso

countriescomma-separatedquery

Comma-separated ISO 3166-1 alpha-2 codes: ads shown in any of them. Left out: every country. Two letters that are no country (ZZ) are refused. Also accepted as country or country_code.

Example: countries=GB,NL

date_fromYYYY-MM-DDquery

Ads shown on or after this day, YYYY-MM-DD. Within the last year: LinkedIn's library goes back no further.

Example: date_from=2026-01-01

date_toYYYY-MM-DDquery

Ads shown on or before this day, YYYY-MM-DD. Within the last year.

Example: date_to=2026-10-21

cursorstringquery

The next_cursor of the page before. Send it with exactly the same other parameters: a cursor from a different search is 400 INVALID_INPUT.

includecomma-separatedquery

raw adds each ad's own record from the platform as raw, for fields we don't map. Values: raw.

Example: include=raw

Response

200 OK (sandbox; the first ad of the page)

{
  "platform": "linkedin",
  "query": {
    "q": null,
    "company_id": null,
    "company": "Contoso",
    "countries": null,
    "date_from": null,
    "date_to": null
  },
  "ads": [
    {
      "id": "linkedin_500000001",
      "platform": "linkedin",
      "platform_ad_id": "500000001",
      "library_url": "https://www.linkedin.com/ad-library/detail/500000001",
      "advertiser": {
        "id": "80000001",
        "name": "Contoso Analytics",
        "domain": null,
        "library_url": "https://www.linkedin.com/ad-library/search?companyIds=80000001"
      },
      "status": "unknown",
      "first_shown": "2026-07-01T00:00:00Z",
      "last_shown": "2026-10-15T00:00:00Z",
      "format": "image",
      "text": {
        "headline": "Dashboards your finance team will actually open",
        "body": "See how 300 finance teams close the month two days sooner.",
        "description": null,
        "cta": "Request demo"
      },
      "text_source": "platform",
      "link_url": "https://contoso-analytics.example/demo",
      "media": [
        {
          "type": "image",
          "url": "https://example.com/sandbox-media/linkedin-dash.png",
          "preview_url": null,
          "width": 1200,
          "height": 627
        }
      ],
      "placements": [
        "linkedin"
      ],
      "regions": [
        "GB",
        "NL"
      ],
      "metrics": {
        "impressions": {
          "min": 50000,
          "max": 100000
        },
        "reach": null,
        "spend": null
      },
      "variants": null
    }
  ],
  "total_estimate": 3,
  "has_more": false,
  "next_cursor": null,
  "credits_used": 0,
  "credits_remaining": null
}

What LinkedIn ads carry

advertiser.id is LinkedIn's company id: pass it as company_id for that company's ads.
metrics.impressions is LinkedIn's total impressions range for ads shown in the EU, else null.
regions lists the countries LinkedIn gives impressions for. status is unknown.

Limits to know

A LinkedIn call uses 2 credits: LinkedIn blocks about half of all lookups, and we retry each on a new connection. That also makes it the slowest of the four.
When every retry is blocked, the answer is 503 UPSTREAM_BLOCKED with Retry-After, and nothing is charged. Wait, then send it again.
Dates must be within the last year: LinkedIn's library goes back no further.
A page holds about 24 ads.

One ad with its detail

GET /v1/ads/{id} with an id from this search (2 credits). Who paid ("Paid for by"), the dates it ran and the full text. For ads shown in the EU, also the impressions range, impressions by country and the top targeting (language, location, audience). An ad shown only outside the EU, in the US for example, gives its advertiser and payer only. See One ad.