---
title: "Search ads"
method: GET
path: "/v1/linkedin/ads/search"
tags: ["LinkedIn Ads Library"]
---

# Search ads

`GET /v1/linkedin/ads/search`

## Request

- Base URL: `https://api.scrapeatlas.com`
- URL: `https://api.scrapeatlas.com/v1/linkedin/ads/search`
- Auth: API key in header `x-api-key`

Search one page by company, payer, keyword, company ID, countries, date preset or date pair, impression range and targeting facets, sorted newest or oldest first. Each card is enriched from its detail page. Pass the returned token with the same filters for continuation. Individual source failures are explicit partial results. Each successful request costs 1 account credit, including partial results. Failed requests cost 0 credits.

## Query parameters

- `company` string
- `keyword` string
- `companyId` string
- `countries` string
- `payer` string
- `startDate` string
- `endDate` string
- `dateOption` 'last-30-days' | 'current-month' | 'current-year' | 'last-year'
- `sortOrder` 'DESCENDING' | 'ASCENDING'
- `minImpressions` string
- `maxImpressions` string
- `includedTargeting` string
- `excludedTargeting` string
- `paginationToken` string
- `cursor` string

## Response `200`

Inspect the response status and failure or coverage fields.

- union
  - object
    - `requestId` string, uuid, required
    - `accounting` object, required
      - `upstreamRequests` integer, required
      - `responseBytes` integer, required
      - `durationMs` number, required
    - `success` true, required
    - `status` 'success' | 'partial', required
    - `sourceUrl` string, uri, required
    - `fetchedAt` string, date-time, required
    - `coverage` object, required
      - `source` 'public_page', required
      - `complete` boolean, required
      - `warnings` string[], required
    - `data` union, required
      - object
        - `ads` object[], required
          - `id` string, required
          - `url` string, uri, required
          - `description` string, nullable, required
          - `headline` string, nullable, required
          - `adType` string, nullable, required
          - `poster` string, nullable, required
          - `posterTitle` string, nullable, required
          - `promotedBy` string, nullable, required
          - `advertiser` object, required
            - `name` string, nullable, required
            - `pageUrl` string, nullable, required
          - `targeting` object, required
            - `language` string, nullable, required
            - `location` string, nullable, required
            - `company` string, nullable, required
            - `audience` string, nullable, required
          - `creative` object, required
            - `imageUrl` string, nullable, required
            - `videoUrl` string, nullable, required
            - `carouselImageUrls` string[], required
            - `cta` string, nullable, required
            - `destinationUrl` string, nullable, required
          - `duration` object, required
            - `label` string, nullable, required
            - `startedAt` string, nullable, required
            - `endedAt` string, nullable, required
          - `impressions` object, required
            - `total` string, nullable, required
            - `byCountry` object[], required
              - …
        - `totalAds` number, nullable, required
        - `page` object, required
          - `nextCursor` string, nullable, required
          - `hasMore` boolean, required
      - object
        - `items` object[], required
          - `id` string, required
          - `url` string, uri, required
          - `description` string, nullable, required
          - `headline` string, nullable, required
          - `poster` string, nullable, required
          - `posterTitle` string, nullable, required
          - `promotedBy` string, nullable, required
          - `paidForBy` string, nullable, required
          - `targeting` object, required
          - `targetingDetails` object, required
          - `image` string, nullable, required
          - `video` string, nullable, required
          - `videoSources` object[], required
            - `url` string, required
            - `bitrate` number, nullable, required
          - `carouselImages` string[], required
          - `creativeType` string, nullable, required
          - `thumbnail` string, nullable, required
          - `preRollVideo` string, nullable, required
          - `organicVideo` string, nullable, required
          - `preRollAdvertiser` string, nullable, required
          - `sponsoredMessageSender` string, nullable, required
          - `sponsoredMessageSenderAvatar` string, nullable, required
          - `sponsoredMessageText` string, nullable, required
          - `document` object, nullable, required
            - `title` string, nullable, required
            - `previewPageCount` integer, required
            - `totalPageCount` integer, nullable, required
            - `coverImageUrls` string[], required
            - `manifestUrl` string, nullable, required
          - `sponsoredMessageButtons` object[], required
            - `text` string, required
            - `type` string, nullable, required
            - `url` string, nullable, required
          - `landingPage` string, nullable, required
          - `adType` string, nullable, required
          - `advertiser` string, nullable, required
          - `advertiserLinkedinPage` string, nullable, required
          - `advertiserLogo` string, nullable, required
          - `cta` string, nullable, required
          - `destinationUrl` string, nullable, required
          - `adDuration` string, nullable, required
          - `startDate` string, nullable, required
          - `endDate` string, nullable, required
          - `totalImpressions` string, nullable, required
          - `impressionsByCountry` object[], required
            - `country` string, required
            - `impressions` string, required
        - `next_cursor` string, nullable, required
        - `dropped` integer, required
        - `total` number, nullable, required
    - `ads` object[], required
      - `id` string, required
      - `url` string, uri, required
      - `description` string, nullable, required
      - `headline` string, nullable, required
      - `poster` string, nullable, required
      - `posterTitle` string, nullable, required
      - `promotedBy` string, nullable, required
      - `paidForBy` string, nullable, required
      - `targeting` object, required
      - `targetingDetails` object, required
      - `image` string, nullable, required
      - `video` string, nullable, required
      - `videoSources` object[], required
        - `url` string, required
        - `bitrate` number, nullable, required
      - `carouselImages` string[], required
      - `creativeType` string, nullable, required
      - `thumbnail` string, nullable, required
      - `preRollVideo` string, nullable, required
      - `organicVideo` string, nullable, required
      - `preRollAdvertiser` string, nullable, required
      - `sponsoredMessageSender` string, nullable, required
      - `sponsoredMessageSenderAvatar` string, nullable, required
      - `sponsoredMessageText` string, nullable, required
      - `document` object, nullable, required
        - `title` string, nullable, required
        - `previewPageCount` integer, required
        - `totalPageCount` integer, nullable, required
        - `coverImageUrls` string[], required
        - `manifestUrl` string, nullable, required
      - `sponsoredMessageButtons` object[], required
        - `text` string, required
        - `type` string, nullable, required
        - `url` string, nullable, required
      - `landingPage` string, nullable, required
      - `adType` string, nullable, required
      - `advertiser` string, nullable, required
      - `advertiserLinkedinPage` string, nullable, required
      - `advertiserLogo` string, nullable, required
      - `cta` string, nullable, required
      - `destinationUrl` string, nullable, required
      - `adDuration` string, nullable, required
      - `startDate` string, nullable, required
      - `endDate` string, nullable, required
      - `totalImpressions` string, nullable, required
      - `impressionsByCountry` object[], required
        - `country` string, required
        - `impressions` string, required
    - `paginationToken` string, nullable, required
    - `isLastPage` boolean, required
    - `totalAds` integer, nullable, required
    - `failedAds` object[], required
      - `id` string, required
      - `code` 'invalid_request' | 'unauthorized' | 'not_found' | 'upstream_challenged' | 'upstream_rate_limited' | 'upstream_error' | 'unsupported_page' | 'restricted_page' | 'response_too_large' | 'unsafe_redirect' | 'request_limit' | 'timeout' | 'busy' | 'payload_too_complex', required
  - object
    - `requestId` string, uuid, required
    - `accounting` object, required
      - `upstreamRequests` integer, required
      - `responseBytes` integer, required
      - `durationMs` number, required
    - `success` false, required
    - `status` 'failed' | 'challenged', required
    - `failure` object, required
      - `code` 'invalid_request' | 'unauthorized' | 'not_found' | 'upstream_challenged' | 'upstream_rate_limited' | 'upstream_error' | 'unsupported_page' | 'restricted_page' | 'response_too_large' | 'unsafe_redirect' | 'request_limit' | 'timeout' | 'busy' | 'payload_too_complex', required
      - `message` string, required

## Other responses

- `400`: Request could not complete; inspect error or failure.code.
- `401`: Request could not complete; inspect error or failure.code.
- `402`: Request could not complete; inspect error or failure.code.
- `403`: Request could not complete; inspect error or failure.code.
- `404`: Request could not complete; inspect error or failure.code.
- `408`: Request could not complete; inspect error or failure.code.
- `413`: Request could not complete; inspect error or failure.code.
- `429`: Request could not complete; inspect error or failure.code.
- `500`: Request could not complete; inspect error or failure.code.
- `502`: Request could not complete; inspect error or failure.code.
- `503`: Request could not complete; inspect error or failure.code.
- `504`: Request could not complete; inspect error or failure.code.

---

[API](https://skmtc.dev/scrapeatlas/apis/scrapeatlas-api.md) · [All operations](https://skmtc.dev/scrapeatlas/apis/scrapeatlas-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scrapeatlas/apis/scrapeatlas-api/revisions/9ba049316894?raw)