> ## 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.

# Fetch an ad from the Meta Ad Library by its ID

> Get one ad from the Meta Ad Library by its Library ID or link: its creative, run dates, platforms and advertiser, who paid for it and who it benefits, and where Meta publishes them, its targeting, reach by country, age and gender, and the audience of ads about social issues, elections or politics. Costs 1 credit per request.



## OpenAPI

````yaml /openapi.json post /meta-ads/get-ad-details
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/get-ad-details:
    post:
      tags:
        - Meta Ads
      summary: Fetch an ad from the Meta Ad Library by its ID
      description: >-
        Get one ad from the Meta Ad Library by its Library ID or link: its
        creative, run dates, platforms and advertiser, who paid for it and who
        it benefits, and where Meta publishes them, its targeting, reach by
        country, age and gender, and the audience of ads about social issues,
        elections or politics. Costs 1 credit per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                adId:
                  type: string
                  minLength: 1
                  description: >-
                    Ad Library ID of the ad, or its Ad Library link, e.g.
                    "1806650610330561" or
                    "https://www.facebook.com/ads/library/?id=1806650610330561".
                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
              required:
                - adId
      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:
                      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.
                      advertiser:
                        anyOf:
                          - type: object
                            properties:
                              id:
                                type: string
                                description: Facebook Page ID of the advertiser.
                              name:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Name of the advertiser’s page.
                              username:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Username of the page, e.g. "nike".
                              url:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Link to the advertiser’s page.
                              profilePictureUrl:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Profile picture of the page.
                              likes:
                                anyOf:
                                  - type: number
                                  - type: 'null'
                                description: Number of likes on the page.
                              category:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Category of the page.
                              isVerified:
                                anyOf:
                                  - type: boolean
                                  - type: 'null'
                                description: Whether the page has a verified badge.
                              instagramUsername:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Instagram account linked to the page.
                              instagramFollowers:
                                anyOf:
                                  - type: number
                                  - type: 'null'
                                description: Followers of the linked Instagram account.
                              instagramVerified:
                                anyOf:
                                  - type: boolean
                                  - type: 'null'
                                description: >-
                                  Whether the linked Instagram account is
                                  verified.
                              isDeleted:
                                anyOf:
                                  - type: boolean
                                  - type: 'null'
                                description: Whether the page has since been deleted.
                            required:
                              - id
                              - name
                              - username
                              - url
                              - profilePictureUrl
                              - likes
                              - category
                              - isVerified
                              - instagramUsername
                              - instagramFollowers
                              - instagramVerified
                              - isDeleted
                            additionalProperties: false
                          - type: 'null'
                        description: >-
                          The advertiser’s page and its linked Instagram
                          account.
                      payer:
                        anyOf:
                          - type: object
                            properties:
                              name:
                                type: string
                                description: Name of the person or organization.
                              website:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Their website, when declared.
                              location:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  Their country as a two-letter code, when
                                  declared.
                            required:
                              - name
                              - website
                              - location
                            additionalProperties: false
                          - type: 'null'
                        description: Who paid for the ad, when the advertiser declared it.
                      beneficiary:
                        anyOf:
                          - type: object
                            properties:
                              name:
                                type: string
                                description: Name of the person or organization.
                              website:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Their website, when declared.
                              location:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  Their country as a two-letter code, when
                                  declared.
                            required:
                              - name
                              - website
                              - location
                            additionalProperties: false
                          - type: 'null'
                        description: Who the ad benefits, when the advertiser declared it.
                      targeting:
                        anyOf:
                          - type: object
                            properties:
                              locations:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    name:
                                      type: string
                                      description: Name of the place, e.g. "Germany".
                                    type:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: >-
                                        Kind of place, e.g. "countries",
                                        "regions" or "cities".
                                    excluded:
                                      type: boolean
                                      description: >-
                                        Whether the ad was kept from people in
                                        this place.
                                  required:
                                    - name
                                    - type
                                    - excluded
                                  additionalProperties: false
                                description: Places the ad was shown in or kept from.
                              gender:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  Genders targeted, e.g. "All", "Men" or
                                  "Women".
                              ageMin:
                                anyOf:
                                  - type: number
                                  - type: 'null'
                                description: Youngest age targeted.
                              ageMax:
                                anyOf:
                                  - type: number
                                  - type: 'null'
                                description: Oldest age targeted (65 means 65 and over).
                            required:
                              - locations
                              - gender
                              - ageMin
                              - ageMax
                            additionalProperties: false
                          - type: 'null'
                        description: >-
                          Who the ad was targeted at. Published for ads shown in
                          the EU, the UK or Brazil.
                      totalReach:
                        anyOf:
                          - type: number
                          - type: 'null'
                        description: >-
                          People the ad reached. Published for ads shown in the
                          EU, the UK or Brazil.
                      reachBreakdown:
                        type: array
                        items:
                          type: object
                          properties:
                            country:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Country as a two-letter code, e.g. "DE".
                            ageRange:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Age range, e.g. "18-24".
                            gender:
                              type: string
                              description: '"Male", "Female" or "Unknown".'
                            reach:
                              type: number
                              description: People reached in this group.
                          required:
                            - country
                            - ageRange
                            - gender
                            - reach
                          additionalProperties: false
                        description: >-
                          People reached by country, age range and gender.
                          Published for ads shown in the EU, the UK or Brazil.
                      audience:
                        anyOf:
                          - type: object
                            properties:
                              country:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  Country the shares are for, as a two-letter
                                  code.
                              byAgeAndGender:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    ageRange:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Age range, e.g. "18-24".
                                    gender:
                                      type: string
                                      description: '"Male", "Female" or "Unknown".'
                                    share:
                                      type: number
                                      description: >-
                                        Share of the people reached, from 0 to
                                        1, e.g. 0.27.
                                  required:
                                    - ageRange
                                    - gender
                                    - share
                                  additionalProperties: false
                                description: >-
                                  Share of the people reached by age range and
                                  gender.
                              byRegion:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    region:
                                      type: string
                                      description: Region, e.g. "California".
                                    share:
                                      type: number
                                      description: >-
                                        Share of the people reached, from 0 to
                                        1, e.g. 0.08.
                                  required:
                                    - region
                                    - share
                                  additionalProperties: false
                                description: Share of the people reached by region.
                            required:
                              - country
                              - byAgeAndGender
                              - byRegion
                            additionalProperties: false
                          - type: 'null'
                        description: >-
                          Who saw the ad, as shares by age, gender and region.
                          Published for ads about social issues, elections or
                          politics.
                    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
                      - advertiser
                      - payer
                      - beneficiary
                      - targeting
                      - totalReach
                      - reachBreakdown
                      - audience
                    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.getAdDetails({
              adId: "string",
            });
            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.