> ## 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 advertisers in the Meta Ad Library

> Find advertisers in the Meta Ad Library by brand or page name. Each result includes the Page ID to search the advertiser’s ads with, the page’s name, username, category, likes, verification and country, and its linked Instagram account. Returns up to 15 advertisers; this list is not paginated. Costs 1 credit per request.



## OpenAPI

````yaml /openapi.json post /meta-ads/search-companies
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-companies:
    post:
      tags:
        - Meta Ads
      summary: Search advertisers in the Meta Ad Library
      description: >-
        Find advertisers in the Meta Ad Library by brand or page name. Each
        result includes the Page ID to search the advertiser’s ads with, the
        page’s name, username, category, likes, verification and country, and
        its linked Instagram account. Returns up to 15 advertisers; this list is
        not paginated. Costs 1 credit per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  type: string
                  pattern: \S
                  description: Name of the brand or advertiser to look for, e.g. "nike".
                country:
                  default: ALL
                  description: >-
                    Two-letter country code to favor advertisers from, e.g.
                    "US", or "ALL". Defaults to "ALL".
                  type: string
                  pattern: ^([a-z]{2}|all)$
                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:
                - q
      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:
                      companies:
                        type: array
                        items:
                          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".
                            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.
                            country:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                Country the page is set up for, as a two-letter
                                code, when it has one.
                          required:
                            - id
                            - name
                            - username
                            - profilePictureUrl
                            - likes
                            - category
                            - isVerified
                            - instagramUsername
                            - instagramFollowers
                            - instagramVerified
                            - isDeleted
                            - country
                          additionalProperties: false
                        description: Advertisers matching the search, best match first.
                    required:
                      - companies
                    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.searchCompanies({
              q: "string",
              country: "ALL",
            });
            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.