openapi: 3.0.0 info: title: LinkedIn Ad Library API description: | Search for ads on LinkedIn's Ad Library to gain insights into advertising campaigns, creative content, and advertiser strategies. Filter ads by keyword, advertiser, country, and time period. **Pagination**: The `pagination.next_page_token` returned in the response can be passed as the `next_page_token` parameter to fetch the next page of results. **Cross-linking**: Ads whose `link` points at an `/ad-library/detail/` page include an `id` that can be passed as the `ad_id` parameter to the LinkedIn Ad Library Ad Details API (`engine=linkedin_ad_library_ad_details`) to fetch that detail page, including run dates, estimated impressions, impressions by country, and ad targeting. Employer-brand ads link to a different page the detail engine cannot fetch. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: LinkedIn Ad Library Search security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Set to `linkedin_ad_library` for LinkedIn Ad Library search schema: type: string default: "linkedin_ad_library" enum: ["linkedin_ad_library"] - name: q in: query required: false description: Search query to filter ads by keyword. At least one of `q`, `advertiser`, `country`, or `time_period` is required. schema: type: string - name: advertiser in: query required: false description: Filter ads by advertiser (account owner) name. At least one of `q`, `advertiser`, `country`, or `time_period` is required. schema: type: string - name: country in: query required: false description: Filter ads by the country where they were shown, using two-letter country codes (e.g. `US`, `GB`). Multiple values can be comma-separated (e.g. `US,GB`). Use `ALL` for all countries. At least one of `q`, `advertiser`, `country`, or `time_period` is required. schema: type: string pattern: '^(ALL|AF|AX|AL|DZ|AS|AD|AO|AI|AQ|AG|AR|AM|AW|AU|AT|AZ|BS|BH|BD|BB|BY|BE|BZ|BJ|BM|BT|BO|BA|BW|BV|BR|IO|BN|BG|BF|BI|KH|CM|CA|CV|CB|KY|CF|TD|CL|CN|CX|CC|CO|KM|CG|CK|CR|CI|HR|CU|CY|CZ|CD|DK|DJ|DM|DO|TP|EC|EG|SV|GQ|ER|EE|ET|FK|FO|FM|FJ|FI|FR|GF|PF|TF|GA|GM|GE|DE|GH|GI|GR|GL|GD|GP|GU|GT|GG|GN|GW|GY|HT|HM|HN|HK|HU|IS|IN|ID|IR|IQ|IE|IM|IL|IT|JM|JP|JE|JO|KZ|KE|KI|KR|KP|KO|KW|KG|LA|LV|LB|LS|LR|LY|LI|LT|LU|MO|MK|MG|MW|MY|MV|ML|MT|MH|MQ|MR|MU|YT|MX|MD|MC|MN|ME|MS|MA|MZ|MM|NA|NR|NP|NL|AN|NC|NZ|NI|NE|NG|NU|NF|MP|NO|PK|PW|PS|PA|PG|PY|PE|PH|PN|PL|PT|PR|QA|RE|RO|RU|RW|GS|SH|KN|LC|PM|VC|WS|SM|ST|SA|SN|RS|CS|SC|SL|SG|SK|SI|SB|SO|ZA|SS|ES|LK|SD|OM|SR|SJ|SZ|SE|CH|SY|TW|TJ|TZ|TH|TL|TG|TK|TO|TT|TN|TR|TM|TC|TV|UG|UA|AE|GB|US|UY|UZ|VU|VA|VE|VN|VG|VI|WF|EH|YE|YU|ZM|ZW)(,(ALL|AF|AX|AL|DZ|AS|AD|AO|AI|AQ|AG|AR|AM|AW|AU|AT|AZ|BS|BH|BD|BB|BY|BE|BZ|BJ|BM|BT|BO|BA|BW|BV|BR|IO|BN|BG|BF|BI|KH|CM|CA|CV|CB|KY|CF|TD|CL|CN|CX|CC|CO|KM|CG|CK|CR|CI|HR|CU|CY|CZ|CD|DK|DJ|DM|DO|TP|EC|EG|SV|GQ|ER|EE|ET|FK|FO|FM|FJ|FI|FR|GF|PF|TF|GA|GM|GE|DE|GH|GI|GR|GL|GD|GP|GU|GT|GG|GN|GW|GY|HT|HM|HN|HK|HU|IS|IN|ID|IR|IQ|IE|IM|IL|IT|JM|JP|JE|JO|KZ|KE|KI|KR|KP|KO|KW|KG|LA|LV|LB|LS|LR|LY|LI|LT|LU|MO|MK|MG|MW|MY|MV|ML|MT|MH|MQ|MR|MU|YT|MX|MD|MC|MN|ME|MS|MA|MZ|MM|NA|NR|NP|NL|AN|NC|NZ|NI|NE|NG|NU|NF|MP|NO|PK|PW|PS|PA|PG|PY|PE|PH|PN|PL|PT|PR|QA|RE|RO|RU|RW|GS|SH|KN|LC|PM|VC|WS|SM|ST|SA|SN|RS|CS|SC|SL|SG|SK|SI|SB|SO|ZA|SS|ES|LK|SD|OM|SR|SJ|SZ|SE|CH|SY|TW|TJ|TZ|TH|TL|TG|TK|TO|TT|TN|TR|TM|TC|TV|UG|UA|AE|GB|US|UY|UZ|VU|VA|VE|VN|VG|VI|WF|EH|YE|YU|ZM|ZW))*$' - name: time_period in: query required: false description: 'Filter ads by time period. Valid options are `last_year`, `this_year`, `this_month`, `last_30_days`, or a custom date range in YYYY-MM-DD..YYYY-MM-DD format. The start date cannot be earlier than one year ago, and dates cannot be in the future. At least one of `q`, `advertiser`, `country`, or `time_period` is required.' schema: type: string - name: next_page_token in: query required: false description: Token to retrieve the next page of results. Use the value of `pagination.next_page_token` from a previous response. schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' search_information: $ref: '#/components/schemas/SearchInformation' ads: type: array description: Array of LinkedIn ads matching the search criteria items: $ref: '#/components/schemas/Ad' pagination: $ref: '#/components/schemas/Pagination' error: type: string description: Error message when no results are found or the pagination token has expired SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: "Unique identifier for the search request" status: type: string description: "Status of the search request" created_at: type: string format: date-time description: "Timestamp when the search was created" request_time_taken: type: number description: "Time taken to make the request in seconds" parsing_time_taken: type: number description: "Time taken to parse the results in seconds" total_time_taken: type: number description: "Total time taken for the search in seconds" request_url: type: string description: "LinkedIn Ad Library URL for this search" html_url: type: string description: "URL to view HTML results" json_url: type: string description: "URL to view JSON results" SearchParameters: type: object properties: engine: type: string description: Search engine used q: type: string description: Search query used advertiser: type: string description: Advertiser filter applied country: type: string description: Country filter applied time_period: type: string description: Time period filter applied next_page_token: type: string description: Pagination token used SearchInformation: type: object properties: total_results: type: integer description: Total number of ads matching the search criteria Pagination: type: object properties: next_page_token: type: string description: Token to pass as the `next_page_token` parameter to fetch the next page of results Ad: type: object required: [position, ad_type, link, id] properties: position: type: integer description: Position of the ad in the results advertiser: $ref: '#/components/schemas/Advertiser' ad_type: type: string description: Type of the ad enum: ["image", "video", "carousel", "multi_image", "event", "document", "article", "message", "job", "employer_brand", "text"] content: $ref: '#/components/schemas/AdContent' link: type: string description: URL of the ad's page on LinkedIn Ad Library, an `/ad-library/detail/` page for standard ads or an employer-brand page for employer-brand ads id: type: string description: Unique identifier for the ad. For ads whose `link` points at an `/ad-library/detail/` page, pass it as the `ad_id` parameter with `engine=linkedin_ad_library_ad_details` to fetch the detail page, including run dates, impressions, and targeting. Employer-brand ads use a different page the detail engine cannot fetch. Advertiser: type: object required: [name, thumbnail] properties: name: type: string description: Name of the advertiser position: type: string description: Tagline or description shown below the advertiser name promotor: type: string description: Name of the person or entity promoting the ad thumbnail: type: string description: URL of the advertiser's profile image AdContent: type: object description: Ad creative content. Available fields depend on the `ad_type`. properties: headline: type: string description: Headline or commentary text of the ad headline_links: type: array description: URLs of links found in the headline text items: type: string image: type: string description: 'URL of the main media image. Present for `image`, `video`, `event`, `article`, and `employer_brand` ad types.' cta: type: string description: 'Headline of the creative''s link card (LinkedIn''s Headline field). Present for `image` and `video` ad types.' description: type: string description: 'Description text. Present for `image`, `video`, `article`, `job`, and `employer_brand` ad types.' items: type: array description: 'Carousel cards, or the photos of a multi-photo post. Present for `carousel` and `multi_image` ad types.' items: $ref: '#/components/schemas/CarouselItem' title: type: string description: 'Title of the document or article. Present for `document` and `article` ad types.' pages: type: array description: 'URLs of the document page preview images. Present for `document` ad type.' items: type: string time: type: string description: 'Date and time of the event. Present for `event` ad type.' name: type: string description: 'Name of the event. Present for `event` ad type.' organizer: type: string description: 'Organizer of the event. Present for `event` ad type.' location: type: string description: 'Location of the event. Present for `event` ad type.' user: type: string description: 'Name of the message sender. Present for `message` ad type.' text: type: string description: 'Text of the sponsored message. Present for `message` ad type.' CarouselItem: type: object properties: image: type: string description: URL of the carousel card image cta: type: string description: Headline of the creative's link card (LinkedIn's Headline field) of the carousel card ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong