openapi: 3.0.0
info:
  title: Meta Ad Library Page Info API
  description: |
    The Meta Ad Library Page Info API retrieves detailed information about a Facebook page from the Meta Ad Library.

    It returns page metadata including name, category, likes, verification status, confirmed page owner, transparency info (creation date, name changes, admin locations), Instagram details, related pages, and ad spend data.

    **Cross-linking**: The `page_id` parameter can be obtained from the Meta Ad Library Page Search API (search pages by name) or from ads returned by the Meta Ad Library API. To retrieve the ads run by a page, pass the same `page_id` to the Meta Ad Library API.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Meta Ad Library Page Info Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to 'meta_ad_library_page_info' for Meta Ad Library Page Info search
          schema:
            type: string
            enum: ["meta_ad_library_page_info"]
            default: "meta_ad_library_page_info"
        - name: page_id
          in: query
          required: true
          description: Facebook page ID to retrieve information for. Can be obtained from the Meta Ad Library Page Search API or from Meta Ad Library API results.
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        page:
          $ref: '#/components/schemas/Page'
        ad_library_page_info:
          $ref: '#/components/schemas/AdLibraryPageInfo'
        error:
          type: string
          description: Error message when the page with the given page_id does not exist or has been deleted
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Meta Ad Library Page Info URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Engine used for the search
        page_id:
          type: string
          description: Facebook page ID used for the search
    Page:
      type: object
      properties:
        name:
          type: string
          description: Name of the Facebook page
        id:
          type: string
          description: Facebook page ID
        url:
          type: string
          description: URL of the Facebook page
        about:
          type: object
          description: About section of the page
          properties:
            text:
              type: string
              description: About text of the page
        is_delegate_page_with_linked_primary_profile:
          type: boolean
          description: Whether the page is a delegate page with a linked primary profile
        confirmed_page_owner:
          $ref: '#/components/schemas/ConfirmedPageOwner'
        pages_transparency_info:
          $ref: '#/components/schemas/PagesTransparencyInfo'
        shared_disclaimer_info:
          type: object
          description: Shared disclaimer information for the page
          properties:
            shared_disclaimer_pages:
              type: array
              description: Pages sharing the same disclaimer
              items:
                type: object
    ConfirmedPageOwner:
      type: object
      properties:
        name:
          type: string
          description: Name of the confirmed page owner
        id:
          type: string
          description: Identifier of the confirmed page owner
        information:
          type: object
          description: Contact information of the confirmed page owner
          properties:
            address:
              type: object
              description: Address of the confirmed page owner
              properties:
                city:
                  type: string
                  description: City of the owner's address
                state:
                  type: string
                  description: State of the owner's address
                country:
                  type: string
                  description: Country of the owner's address
                postal_code:
                  type: string
                  description: Postal code of the owner's address
            phone_number:
              type: string
              description: Phone number of the confirmed page owner
    PagesTransparencyInfo:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the transparency record
        history_items:
          type: array
          description: Page history events such as creation and name changes
          items:
            type: object
            properties:
              event_time:
                type: string
                format: date-time
                description: Timestamp of the history event
              item_type:
                type: string
                description: 'Type of the history event, such as CREATION or NAME_CHANGE'
        admin_locations:
          type: object
          description: Locations of the people who manage the page
          properties:
            admin_country_counts:
              type: array
              description: Number of page admins per country
              items:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of admins in the country
                  country:
                    type: object
                    description: Country of the admins
                    properties:
                      iso_name:
                        type: string
                        description: Name of the country
                      id:
                        type: string
                        description: Identifier of the country
        state_media_country_label:
          type: string
          description: Country label when the page is state-controlled media
    AdLibraryPageInfo:
      type: object
      properties:
        page_info:
          $ref: '#/components/schemas/PageInfo'
        page_spend:
          $ref: '#/components/schemas/PageSpend'
    PageInfo:
      type: object
      properties:
        page_name:
          type: string
          description: Name of the page
        page_id:
          type: string
          description: Facebook page ID
        page_alias:
          type: string
          description: Alias (username) of the page
        page_profile_uri:
          type: string
          description: URL of the page profile
        profile_photo:
          type: string
          description: URL of the page profile photo
        page_category:
          type: string
          description: Category of the page
        page_verification:
          type: string
          description: 'Verification status of the page, such as BLUE_VERIFIED or NOT_VERIFIED'
        entity_type:
          type: string
          description: Type of the page entity
        likes:
          type: integer
          description: Number of likes the page has
        page_is_deleted:
          type: boolean
          description: Whether the page has been deleted
        page_is_actioned:
          type: boolean
          description: Whether the page has been actioned by Meta
        has_blank_ads:
          type: boolean
          description: Whether the page has blank ads
        hidden_ads:
          type: integer
          description: Number of hidden ads for the page
        ig_username:
          type: string
          description: Instagram username linked to the page
        ig_followers:
          type: integer
          description: Number of Instagram followers
        ig_verification:
          type: boolean
          description: Whether the linked Instagram account is verified
        related_pages:
          type: array
          description: Pages related to this page
          items:
            $ref: '#/components/schemas/RelatedPage'
    RelatedPage:
      type: object
      properties:
        page_id:
          type: string
          description: Facebook page ID of the related page
        page_name:
          type: string
          description: Name of the related page
        category_name:
          type: string
          description: Category of the related page
        country:
          type: string
          description: Country code of the related page
        country_name:
          type: string
          description: Country name of the related page
        page_verification:
          type: string
          description: Verification status of the related page
        profile_image_uri:
          type: string
          description: URL of the related page profile image
    PageSpend:
      type: object
      properties:
        current_week:
          type: object
          description: Ad spend data for the current week
        lifetime_by_disclaimer:
          type: array
          description: Lifetime ad spend grouped by disclaimer
          items:
            type: object
        weekly_by_disclaimer:
          type: array
          description: Weekly ad spend grouped by disclaimer
          items:
            type: object
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong