taskType ADS with platform linkedin_ad_library, and action picks what to read. To choose between the ad libraries, see Ad libraries compared.
search(default) lists ads by a keyword inquery, by an advertiser’s name inadvertiserName, by who paid inpayer, or by a combination. Each ad carries its advertiser, format, title, text and media, and the response ends with asummaryof the ads it returned.adopens one ad: the advertiser, who paid, the landing page, and where the library publishes it, the run dates, the impressions, the countries it reached and its targeting.
action advertisers is rejected with 400 VALIDATION_ERROR. Find a competitor with advertiserName in a search.
A search costs 0.5 credits for every 30 ads it returns. ad costs 0.5 credits.
Request
GET /v1/async/task/{id} or receive its webhook. See Async tasks. The library limits how fast it reads, so a search of 120 ads takes about half a minute.
Analyze a competitor’s ads
Three requests cover a competitor analysis:searchwith the competitor’s name inadvertiserNamelists its ads.advertiserNamematches part of a name, so checkadvertiserNameon each ad. Addqueryto narrow the ads to a topic, andsortByoldestto start from the oldest ads.adwith an ad’slibraryIdreturns who paid, the landing page and, for ads shown in the EU, the run dates, the impressions and the targeting.searchwithpayerlists the ads an agency or company paid for, whichever page runs them.
Parameters
action:search(default) orad.query: A keyword in the ad’s text.searchneedsquery,advertiserNameorpayer.advertiserName: A name, matched as part of the advertiser’s name, such assamsung.payer: The name of who paid for the ad, matched as part of the name, such asStarcom.libraryId: The numeric ID of an ad, such as1638962914.adrequires it.country: Where the ads were shown, as a two-letter country code, orALLfor every country (default).startDate,endDate:YYYY-MM-DD, sent together, within the last year. Keeps the ads shown between the two days.sortBy:newest(default) oroldest.limit: 1 to 120 ads. Default 30.cursor: ThenextCursorof an earlier response, to read the ads after it.
search reads every field above except libraryId, and ad reads libraryId only. A Meta Ad Library filter (pageId, pageIds, activeStatus, searchType, adType, mediaType, publisherPlatforms or contentLanguages), a value the library cannot search, or a field the action does not read is rejected with 400 VALIDATION_ERROR, and details names the field.
Read more ads
A response with more ads to read carriesnextCursor. Send it as cursor with the same search to receive the next ads, again up to limit. nextCursor is null once the library has no more. A cursor works only with the search that returned it: a different query, advertiserName, payer, country, date range or sortBy is rejected with 400 VALIDATION_ERROR, while limit can change.
Search response
- The response echoes
platform,action,country,query,advertiserName,payer,sortByand the dates it was given.returnedCountcounts the ads inads,hasMoreistruewhen the library has more, whichnextCursorreads, andlibraryUrlopens the same search in the Ad Library.totalCountisnull, because the library gives no count. - Each ad is a card:
position,libraryId,libraryUrl,advertiserName,advertiserLogoUrl,creativeType(such asSPONSORED_STATUS_UPDATEorSPONSORED_VIDEO),format,title,body,imagesandvideos(the video’s poster inpreviewUrl), andplatforms(LINKEDIN).formatisIMAGE,VIDEO,CAROUSEL,DOCUMENT,ARTICLE,MESSAGE,JOB,SPOTLIGHTorFOLLOW_COMPANY. - Message ads and thought leader ads carry
member, the sender of the message or the member whose post the ad promotes, asnameandurl;adreturns it in the same shape.memberisnullon other ads. - A card carries the first 120 characters of the text, and
bodyTruncatedistruewhen the text is longer.adreturns the full text. advertiserId,payer,startDate,endDate,activeDays,linkUrl,landingDomain,impressions,targeting,ctaTextandutmarenullon a card.adfills them where the library has them.isActiveisnull, because the library does not tell whether an ad still runs.summarycounts the ads of this response:ads,advertisers(the 10 with the most ads:advertiserName,ads),formatsandplatforms. Its date fields (oldestStartDate,newestStartDate,medianActiveDays,launchesByWeekandlongestRunning) stay empty ornull, because cards carry no dates.- A search with no matching ads completes with an empty
adsand asummaryof0ads.
What the library keeps
- Every ad’s creative, advertiser and payer are available for every country.
- The run dates, the impressions range, the share of impressions by country and the targeting are available only for ads shown in the EU.
- The library keeps ads for about 12 months, and its date filter takes only the last year.
Open one ad
action ad opens the ad with the libraryId you send, from a search or from the Ad Library address /ad-library/detail/<libraryId>.
adhas the fields of a search card with the full text, plusadvertiserId,advertiserUrl,advertiserType(companyorperson),payer(who paid for the ad),linkUrl,landingDomain,ctaText,startDate,endDate,activeDays,impressions,targetingandreachedCountries.impressionsis the range the library publishes (min,max).targetinglists the languages and locations the advertiser included or excluded (language,location) and the targeting parameters (parameters:parameter,targeted,excluded). The dates,impressions,targetingandreachedCountriesarenullfor an ad that was not shown in the EU, such as the Adobe ad1698237666. The payer and the advertiser are there for every ad.videoslists each video withurl(the file with the highest bitrate),files(every mp4:url,type,bitrate) andpreviewUrl. A carousel ad addscards(title,imageUrl) and a document ad addsdocument(its title, page count and page covers).advertiseris the page behind the ad:advertiserId,advertiserName,url,typeandlogoUrl.transparencyisnullfor an ad not shown in the EU. For an ad shown in the EU it holdsimpressions,impressionsText(the library’s text, such as50k-100k) andreachByCountry, the share of the impressions in each country (country,countryCode,share,shareText), outside the EU too.variantslists the other versions of the ad where the library shows more than one, and isnullotherwise.- Media URLs of creatives stay open for years. The URLs of carousel cards expire after about a week, and advertiser logos after about two and a half weeks. Save the files you need.
- A
libraryIdthe library has no ad for fails withPAGE_UNAVAILABLE.
Price
A search holds 0.5 credits for every 30 ads itslimit asks for, and is charged 0.5 credits for every 30 ads it returns, at least 0.5 credits. The default search of 30 ads costs 0.5 credits, and a search with limit 120 holds 2 credits. ad costs 0.5 credits. Only completed requests are charged.