superagnt-com Facebook: Meta Ads Library Search API

openapi: 3.2.0
info:
  title: 'superagnt Facebook: Meta Ads Library Search API'
  description: Unified API for social media data. Access LinkedIn, YouTube, TikTok, X, Instagram, Reddit, and Facebook through a single API key.
  version: 1.0.0
  contact:
    name: superagnt
    url: https://superagnt.com
servers:
- url: https://api.superagnt.com
  description: superagnt API
security:
- ApiKeyAuth: []
tags:
- name: 'Facebook: Meta Ads Library Search'
  description: The Meta Ads Library Search allows you to search and retrieve detailed information from Meta’s Ad Library, providing insights into active and inactive ad campaigns across Facebook and Instagram. This tool is ideal for marketing analysis, competitor research, and understanding ad strategies.
paths:
  /v1/data/facebook/fetch_archive_ad_details:
    get:
      operationId: Fetch_Archive_Ad_Details
      summary: Fetch Archive Ad Details
      description: This endpoint allows you to retrieve detailed information about a specific ad in the archive based on its archive ID. You can filter the results by page ID, country, and flags indicating whether the ad is non-political or AAA-eligible.
      tags:
      - 'Facebook: Meta Ads Library Search'
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
      - name: ad_archive_id
        in: query
        required: true
        schema:
          type: string
          default: '870923648247659'
      - name: page_id
        in: query
        required: false
        schema:
          type: string
          default: '144939265372419'
      - name: is_ad_not_aaa_eligible
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
      - name: is_ad_non_political
        in: query
        required: false
        schema:
          type: boolean
          default: 'true'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized - invalid API key
        '429':
          description: Rate limit exceeded
      security:
      - ApiKeyAuth: []
  /v1/data/facebook/fetch_page_ad_details:
    get:
      operationId: Fetch_Page_Ad_Details
      summary: Fetch Page Ad Details
      description: This endpoint retrieves detailed information about a specific Facebook page based on the provided page ID. This includes key page details such as name, profile URL, verification status, and more, but does not return ad data directly.
      tags:
      - 'Facebook: Meta Ads Library Search'
      parameters:
      - name: page_id
        in: query
        required: true
        schema:
          type: string
          default: '144939265372419'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized - invalid API key
        '429':
          description: Rate limit exceeded
      security:
      - ApiKeyAuth: []
  /v1/data/facebook/fetch_search_ads_pages:
    get:
      operationId: Fetch_Search_Ads_Pages__GET
      summary: Fetch Search Ads Pages (GET)
      description: This endpoint retrieves detailed information about ad pages based on a search query, returning up to 26 ads per request. Use the end_cursor parameter to retrieve additional ads if needed.
      tags:
      - 'Facebook: Meta Ads Library Search'
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
      - name: after_time
        in: query
        required: false
        schema:
          type: string
      - name: before_time
        in: query
        required: false
        schema:
          type: string
      - name: ad_page_id
        in: query
        required: false
        schema:
          type: string
        description: Facebook AD Page ID. Used only if `query` is not provided.
      - name: activeStatus
        in: query
        required: false
        schema:
          type: string
      - name: end_cursor
        in: query
        required: false
        schema:
          type: string
      - name: query
        in: query
        required: false
        schema:
          type: string
          default: for kids
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized - invalid API key
        '429':
          description: Rate limit exceeded
      security:
      - ApiKeyAuth: []
    post:
      operationId: Fetch_Search_Ads_Pages__POST
      summary: Fetch Search Ads Pages (POST)
      description: This endpoint retrieves detailed information about ad pages based on a search query, returning up to 26 ads per request. Use the end_cursor parameter to retrieve additional ads if needed.
      tags:
      - 'Facebook: Meta Ads Library Search'
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized - invalid API key
        '429':
          description: Rate limit exceeded
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  default: ''
                  description: Search query string
                ad_page_id:
                  type: string
                  default: '1633779800049051'
                  description: Facebook Ad Page ID. Used only if query is not provided.
                country:
                  type: string
                  default: ALL
                  description: Country filter (e.g. ALL, US, GB)
                activeStatus:
                  type: string
                  default: ALL
                  description: Filter by active status (e.g. ALL, ACTIVE, INACTIVE)
                end_cursor:
                  type: string
                  default: ''
                  description: Pagination cursor for next page of results
                after_time:
                  type: string
                  default: ''
                  description: Filter ads created after this time
                before_time:
                  type: string
                  default: ''
                  description: Filter ads created before this time
                sort_data:
                  type: string
                  default: ''
                  description: Sort order for results
            example:
              query: ''
              ad_page_id: '1633779800049051'
              country: ALL
              activeStatus: ALL
              end_cursor: ''
              after_time: ''
              before_time: ''
              sort_data: ''
      security:
      - ApiKeyAuth: []
  /v1/data/facebook/get_supported_countries:
    get:
      operationId: Get_Supported_Countries
      summary: Get Supported Countries
      description: The get_supported_countries endpoint retrieves a list of all available country codes that can be used in other endpoints, such as filtering ads by country. This ensures that you are using valid country codes when making requests.
      tags:
      - 'Facebook: Meta Ads Library Search'
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized - invalid API key
        '429':
          description: Rate limit exceeded
      security:
      - ApiKeyAuth: []
  /v1/data/facebook/fetch_search_ads_keywords:
    get:
      operationId: Fech_Search_Ads_Keywords
      summary: Fech Search Ads Keywords
      description: The Fetch Search Ads Keywords endpoint allows you to search for ads based on a specified query. You can filter ads by country, status (Active or Inactive), and ad type.
      tags:
      - 'Facebook: Meta Ads Library Search'
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
      - name: query
        in: query
        required: true
        schema:
          type: string
          default: cars
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized - invalid API key
        '429':
          description: Rate limit exceeded
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Bearer token. Pass your agntdata API key as: Authorization: Bearer agnt_live_...'