> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bridgly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Search ads in the Meta Ad Library

> Search ads running on Facebook, Instagram and Meta’s other apps by keyword or advertiser, with filters for country, active status, ad category, media type, platform, language and dates. Each ad includes its text, images, videos, carousel cards, link, call to action, run dates, platforms and advertiser, plus spend, impressions and the paid-for-by disclaimer for ads about social issues, elections or politics. Costs 1 credit per result returned, with a minimum of 1 credit per request.



## OpenAPI

````yaml /openapi.json post /meta-ads/search
openapi: 3.1.0
info:
  title: Bridgly API
  description: >-
    Web scraping API for LinkedIn, X (Twitter), Reddit, GitHub, Instagram and
    TikTok. Authenticated endpoints accept a Bridgly API key (`bgly_…`) via
    `Authorization: Bearer <token>`.
  version: 1.0.0
servers:
  - url: https://api.bridgly.app
    description: Production
security: []
tags:
  - name: LinkedIn
    description: Scrape LinkedIn profiles, companies, posts, and search.
  - name: Reddit
    description: Scrape Reddit posts, subreddits, users, and search.
  - name: X (Twitter)
    description: Scrape tweets and search X.
  - name: GitHub
    description: >-
      Fetch GitHub profiles, pinned repos, contributions, repositories, stars,
      and projects via GitHub's GraphQL API.
  - name: Instagram
    description: Scrape Instagram profiles, posts, followers, and search.
  - name: TikTok
    description: Fetch TikTok profiles.
  - name: Meta Ads
    description: >-
      Search the Meta Ad Library: ads, ad details, and advertisers on Facebook
      and Instagram.
paths:
  /meta-ads/search:
    post:
      tags:
        - Meta Ads
      summary: Search ads in the Meta Ad Library
      description: >-
        Search ads running on Facebook, Instagram and Meta’s other apps by
        keyword or advertiser, with filters for country, active status, ad
        category, media type, platform, language and dates. Each ad includes its
        text, images, videos, carousel cards, link, call to action, run dates,
        platforms and advertiser, plus spend, impressions and the paid-for-by
        disclaimer for ads about social issues, elections or politics. Costs 1
        credit per result returned, with a minimum of 1 credit per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  description: >-
                    Keywords to search the ads’ text for, e.g. "running shoes".
                    Leave it out to list every ad matching the other filters.
                  type: string
                  pattern: \S
                pageId:
                  description: >-
                    Only return ads from this advertiser: its Facebook Page ID,
                    e.g. "15087023444", as returned in `page.id` or by the
                    advertiser search. The Ad Library link of the advertiser’s
                    ads (`?view_all_page_id=<id>`) works too.
                  type: string
                  minLength: 1
                exactPhrase:
                  default: false
                  description: >-
                    Match `q` as an exact phrase instead of matching any ad that
                    has all its words. Defaults to false.
                  type: boolean
                country:
                  default: ALL
                  description: >-
                    Two-letter country code to search ads shown in, e.g. "US" or
                    "GB", or "ALL" for every country. Defaults to "ALL".
                  type: string
                  pattern: ^([a-z]{2}|all)$
                activeStatus:
                  default: active
                  description: >-
                    Return ads that are still running ("active"), that stopped
                    ("inactive"), or both ("all"). Defaults to "active".
                  type: string
                  enum:
                    - active
                    - inactive
                    - all
                adType:
                  default: all
                  description: >-
                    Ad category: "all", "political_and_issue_ads" (social
                    issues, elections or politics), "housing_ads",
                    "employment_ads" or "credit_ads". Defaults to "all".
                  type: string
                  enum:
                    - all
                    - political_and_issue_ads
                    - housing_ads
                    - employment_ads
                    - credit_ads
                mediaType:
                  default: all
                  description: >-
                    Media in the ad: "all", "image", "meme", "image_and_meme",
                    "video", or "none" for ads with no image or video. Defaults
                    to "all".
                  type: string
                  enum:
                    - all
                    - image
                    - meme
                    - image_and_meme
                    - video
                    - none
                platforms:
                  description: >-
                    Only return ads running on these platforms, e.g.
                    ["instagram"]. Leave it out for every platform.
                  type: array
                  items:
                    type: string
                    enum:
                      - facebook
                      - instagram
                      - messenger
                      - audience_network
                      - whatsapp
                      - threads
                languages:
                  description: >-
                    Only return ads in these languages, as two-letter codes,
                    e.g. ["en", "es"].
                  type: array
                  items:
                    type: string
                    pattern: ^[A-Za-z]{2}$
                startDate:
                  description: >-
                    Only return ads that ran on or after this date (YYYY-MM-DD),
                    e.g. "2026-01-01".
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                endDate:
                  description: >-
                    Only return ads that ran on or before this date
                    (YYYY-MM-DD), e.g. "2026-03-31".
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                sortBy:
                  default: impressions
                  description: >-
                    Order of the ads: most seen first ("impressions"), or
                    recently started ads first ("recent"), which Meta orders
                    roughly rather than strictly by start date. Defaults to
                    "impressions".
                  type: string
                  enum:
                    - impressions
                    - recent
                count:
                  default: 10
                  description: Number of results to return (1–30). Defaults to 10.
                  type: integer
                  minimum: 1
                  maximum: 30
                cursor:
                  description: >-
                    The previous response's `nextCursor`, to fetch the next
                    page. Omit it for the first page.
                  type: string
                cacheMaxAgeHours:
                  description: >-
                    Accept a cached result scraped up to this many hours ago. A
                    cached result costs no credits, and its `cachedAt` says when
                    it was scraped. When no cached result is that recent, the
                    data is scraped live at the normal price. Leave it out to
                    always scrape live, e.g. 24.
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                cacheOnly:
                  description: >-
                    Return only a cached result and never scrape live. With
                    `cacheMaxAgeHours`, only a result that recent is returned;
                    without it, the latest cached result of any age. Responds
                    404, at no cost, when there is none, e.g. true.
                  type: boolean
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  timeMs:
                    type: number
                    description: >-
                      Wall-clock time the request took to complete, in
                      milliseconds.
                  creditsCost:
                    type: number
                    description: Number of account credits this request consumed.
                  cachedAt:
                    anyOf:
                      - type: string
                        format: date-time
                        pattern: >-
                          ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                      - type: 'null'
                    description: >-
                      When the returned data was scraped, if it came from the
                      cache. Null when it was scraped live for this request.
                  data:
                    type: object
                    properties:
                      nextCursor:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: >-
                          Pass as `cursor` to fetch the next page; null when
                          there are no more results. A page can hold fewer
                          results than asked for, so keep paging until it is
                          null. Fetch the next page soon: a cursor starting with
                          `bridgly_page_` stays valid for a day, and a list that
                          changes in between can shift results across pages.
                      ads:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: >-
                                Ad Library ID of the ad. Pass it as `adId` to
                                fetch the ad.
                            url:
                              type: string
                              description: Link to the ad in the Meta Ad Library.
                            isActive:
                              anyOf:
                                - type: boolean
                                - type: 'null'
                              description: Whether the ad is still running.
                            startDate:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Date the ad started running (YYYY-MM-DD).
                            endDate:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                Last date the ad ran (YYYY-MM-DD). For an ad
                                that is still running, the most recent day it
                                ran.
                            page:
                              anyOf:
                                - type: object
                                  properties:
                                    id:
                                      type: string
                                      description: >-
                                        Facebook Page ID of the advertiser. Pass
                                        it as `pageId` to search this
                                        advertiser’s ads or fetch the
                                        advertiser.
                                    name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Name of the advertiser’s page.
                                    url:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Link to the advertiser’s Facebook page.
                                    profilePictureUrl:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: >-
                                        Profile picture of the advertiser’s
                                        page.
                                    likes:
                                      anyOf:
                                        - type: number
                                        - type: 'null'
                                      description: Number of likes on the page.
                                    categories:
                                      anyOf:
                                        - type: array
                                          items:
                                            type: string
                                        - type: 'null'
                                      description: >-
                                        Page categories, e.g. ["Sportswear
                                        Store"].
                                    isDeleted:
                                      anyOf:
                                        - type: boolean
                                        - type: 'null'
                                      description: Whether the page has since been deleted.
                                  required:
                                    - id
                                    - name
                                    - url
                                    - profilePictureUrl
                                    - likes
                                    - categories
                                    - isDeleted
                                  additionalProperties: false
                                - type: 'null'
                              description: The advertiser.
                            partnerPage:
                              anyOf:
                                - type: object
                                  properties:
                                    id:
                                      type: string
                                      description: Facebook Page ID of the partner.
                                    name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Name of the partner’s page.
                                    url:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Link to the partner’s Facebook page.
                                  required:
                                    - id
                                    - name
                                    - url
                                  additionalProperties: false
                                - type: 'null'
                              description: >-
                                The partner of a paid partnership (branded
                                content) ad.
                            paidForBy:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                Who paid for the ad, as shown on ads about
                                social issues, elections or politics.
                            displayFormat:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                Format of the ad, e.g. "IMAGE", "VIDEO",
                                "CAROUSEL", "DCO" (dynamic creative) or "DPA"
                                (product catalog).
                            title:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Headline of the ad.
                            body:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Main text of the ad.
                            caption:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Display link of the ad, e.g. "nike.com".
                            linkUrl:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Where the ad links to.
                            linkDescription:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Description under the ad’s headline.
                            ctaText:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Call-to-action button text, e.g. "Shop now".
                            ctaType:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Call-to-action type, e.g. "SHOP_NOW".
                            images:
                              type: array
                              items:
                                type: string
                              description: Images of the ad.
                            videos:
                              type: array
                              items:
                                type: object
                                properties:
                                  hdUrl:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: HD video file.
                                  sdUrl:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: SD video file.
                                  previewImageUrl:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: Still image shown before the video plays.
                                required:
                                  - hdUrl
                                  - sdUrl
                                  - previewImageUrl
                                additionalProperties: false
                              description: Videos of the ad.
                            cards:
                              type: array
                              items:
                                type: object
                                properties:
                                  title:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: Headline of the card.
                                  body:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: Text of the card.
                                  caption:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: Display link of the card, e.g. "nike.com".
                                  linkUrl:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: Where the card links to.
                                  linkDescription:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: Description under the card’s headline.
                                  ctaText:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: >-
                                      Call-to-action button text, e.g. "Shop
                                      now".
                                  ctaType:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: Call-to-action type, e.g. "SHOP_NOW".
                                  imageUrl:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: Image of the card.
                                  video:
                                    anyOf:
                                      - type: object
                                        properties:
                                          hdUrl:
                                            anyOf:
                                              - type: string
                                              - type: 'null'
                                            description: HD video file.
                                          sdUrl:
                                            anyOf:
                                              - type: string
                                              - type: 'null'
                                            description: SD video file.
                                          previewImageUrl:
                                            anyOf:
                                              - type: string
                                              - type: 'null'
                                            description: >-
                                              Still image shown before the video
                                              plays.
                                        required:
                                          - hdUrl
                                          - sdUrl
                                          - previewImageUrl
                                        additionalProperties: false
                                      - type: 'null'
                                    description: Video of the card.
                                required:
                                  - title
                                  - body
                                  - caption
                                  - linkUrl
                                  - linkDescription
                                  - ctaText
                                  - ctaType
                                  - imageUrl
                                  - video
                                additionalProperties: false
                              description: >-
                                The cards of a carousel, dynamic creative or
                                catalog ad, each with its own text, link and
                                media.
                            textVariations:
                              type: array
                              items:
                                type: string
                              description: >-
                                Other versions of the ad’s text that Meta
                                rotates in for a dynamic creative ad.
                            linkVariations:
                              type: array
                              items:
                                type: string
                              description: >-
                                Other links that Meta rotates in for a dynamic
                                creative ad.
                            platforms:
                              type: array
                              items:
                                type: string
                              description: >-
                                Where the ad runs, e.g. ["facebook",
                                "instagram", "messenger", "audience_network",
                                "threads"].
                            categories:
                              type: array
                              items:
                                type: string
                              description: >-
                                Ad categories Meta assigned, e.g. ["POLITICAL"]
                                or ["HOUSING"].
                            collationId:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                ID shared by ads that use the same creative and
                                text.
                            collationCount:
                              anyOf:
                                - type: number
                                - type: 'null'
                              description: >-
                                Number of ads that use the same creative and
                                text.
                            targetedCountries:
                              type: array
                              items:
                                type: string
                              description: >-
                                Countries the ad targeted or reached, as
                                two-letter codes, when Meta publishes them.
                            impressions:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                Range of times the ad was seen, e.g. "500K -
                                600K". Published for ads about social issues,
                                elections or politics.
                            spend:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                Range the advertiser spent on the ad, e.g. "$2K
                                - $2.5K". Published for ads about social issues,
                                elections or politics.
                            currency:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Currency of `spend`, e.g. "USD".
                            reachEstimate:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                Range of people the ad reached, e.g. ">1M".
                                Published for ads about social issues, elections
                                or politics.
                            disclaimer:
                              anyOf:
                                - type: object
                                  properties:
                                    verification:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: >-
                                        How Meta confirmed the advertiser, e.g.
                                        "This information was confirmed using an
                                        employer identification number (EIN)."
                                    submittedOn:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: >-
                                        When the details were submitted, as Meta
                                        words it.
                                    phone:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Phone number of the advertiser.
                                    email:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Email address of the advertiser.
                                    website:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Website of the advertiser.
                                    address:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Address of the advertiser.
                                  required:
                                    - verification
                                    - submittedOn
                                    - phone
                                    - email
                                    - website
                                    - address
                                  additionalProperties: false
                                - type: 'null'
                              description: >-
                                Contact details the advertiser gave Meta, shown
                                on ads about social issues, elections or
                                politics.
                            stateMediaLabel:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                Label Meta shows on ads from state-controlled
                                media, e.g. "China state-controlled media".
                            containsDigitallyCreatedMedia:
                              anyOf:
                                - type: boolean
                                - type: 'null'
                              description: >-
                                Whether the advertiser disclosed the ad was
                                digitally created or altered.
                          required:
                            - id
                            - url
                            - isActive
                            - startDate
                            - endDate
                            - page
                            - partnerPage
                            - paidForBy
                            - displayFormat
                            - title
                            - body
                            - caption
                            - linkUrl
                            - linkDescription
                            - ctaText
                            - ctaType
                            - images
                            - videos
                            - cards
                            - textVariations
                            - linkVariations
                            - platforms
                            - categories
                            - collationId
                            - collationCount
                            - targetedCountries
                            - impressions
                            - spend
                            - currency
                            - reachEstimate
                            - disclaimer
                            - stateMediaLabel
                            - containsDigitallyCreatedMedia
                          additionalProperties: false
                        description: Matching ads on this page.
                    required:
                      - nextCursor
                      - ads
                    additionalProperties: false
                required:
                  - timeMs
                  - creditsCost
                  - cachedAt
                  - data
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                    description: Human-readable description of what went wrong.
                required:
                  - status
                  - message
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                    description: Human-readable description of what went wrong.
                required:
                  - status
                  - message
                additionalProperties: false
        '402':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                    description: Human-readable description of what went wrong.
                required:
                  - status
                  - message
                additionalProperties: false
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                    description: Human-readable description of what went wrong.
                required:
                  - status
                  - message
                additionalProperties: false
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                    description: Human-readable description of what went wrong.
                required:
                  - status
                  - message
                additionalProperties: false
        '422':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                    description: Human-readable description of what went wrong.
                required:
                  - status
                  - message
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                    description: Human-readable description of what went wrong.
                required:
                  - status
                  - message
                additionalProperties: false
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: typescript
          label: Bridgly SDK
          source: |-
            import { Bridgly } from '@bridgly/sdk';

            const client = new Bridgly({ apiKey: process.env.BRIDGLY_API_KEY });

            const res = await client.metaAds.search({
              exactPhrase: false,
              country: "ALL",
              activeStatus: "active",
              adType: "all",
              mediaType: "all",
              sortBy: "impressions",
              count: 10,
            });
            if (res.type === 'success') console.log(res.data);
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A Bridgly API key (`bgly_…`). Metered endpoints deduct credits from the
        resolved account.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.