# 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. Base URL: `https://api.publicadsapi.com` · Auth: `authorization: Bearer ` · Web version: https://publicadsapi.com/docs/api/linkedin - **Ads a page**: about 24. One page per call; `next_cursor` for more. - **Credits**: 2 credits a page. Only when the page has ads. Empty pages, errors and the sandbox are free. - **Covers**: Every country, the last 12 months. Search by `q`, `company_id` or `company`. ## Request cURL: ```bash curl "https://api.publicadsapi.com/v1/linkedin/ads?company=Contoso" \ -H "authorization: Bearer $PADS_API_KEY" ``` Node.js: ```js const res = await fetch('https://api.publicadsapi.com/v1/linkedin/ads?company=Contoso', { headers: { authorization: `Bearer ${process.env.PADS_API_KEY}` }, }); const result = await res.json(); if (!res.ok) throw new Error(`${result.error.code}: ${result.error.message}`); console.log(result.ads.length, 'ads; next page:', result.next_cursor); ``` Python: ```python import os import requests res = requests.get( "https://api.publicadsapi.com/v1/linkedin/ads?company=Contoso", headers={"authorization": f"Bearer {os.environ['PADS_API_KEY']}"}, timeout=60, ) result = res.json() if not res.ok: raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}") print(len(result["ads"]), "ads; next page:", result["next_cursor"]) ``` ## 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. - `Authorization` (header, string, required): `Bearer `. Keys starting `pads_test_` get the sandbox (sample ads, never charged); keys starting `pads_live_` read the platform and use credits. - `q` (query, string, send one of q, company_id, company): A keyword, matched against the ad's text. Also accepted as `query` or `keyword`. Example: `q=analytics` - `company_id` (query, string, send one of q, company_id, company): LinkedIn's numeric company id, the `advertiser.id` of any of its ads. Example: `company_id=80000001` - `company` (query, string, send one of q, company_id, company): A company name, matched as LinkedIn's advertiser search does. Example: `company=Contoso` - `countries` (query, comma-separated): 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_from` (query, YYYY-MM-DD): 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_to` (query, YYYY-MM-DD): Ads shown on or before this day, `YYYY-MM-DD`. Within the last year. Example: `date_to=2026-10-21` - `cursor` (query, string): 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`. - `include` (query, comma-separated): `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): ```json { "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](https://publicadsapi.com/docs/api/ads.md). See also: [TikTok](https://publicadsapi.com/docs/api/tiktok.md) · [One ad](https://publicadsapi.com/docs/api/ads.md)