Logo SearchApi

Meta Ad Library Ad Details API Documentation

GET   /api/v1/search?engine=meta_ad_library_ad_details

This API allows you to search for ads in Meta Ad Library on a given ad archive ID. It returns European Union and UK Transparency insights, including detailed information about political ads segmented by region. Use the country parameter to get region-specific transparency data via transparency_by_location.

API Parameters

Search Params

  • Name
    ad_archive_id
    Required
    Required
    Description

    Specifies the ad's unique ID. You can obtain it in two ways:

    • Use our Meta Ad Library API. The ad_archive_id is included as a key for each ad object returned by the API.
    • Visit the Meta Ad Library website. On each ad card in the UI, you'll find a “Library ID” — this is the ad_archive_id.

  • Name
    is_political
    Required
    Optional
    Description

    Specifies whether the ad is political. The default value is false

  • Name
    country
    Required
    Optional
    Description

    Specifies the country for transparency data. When set, the response includes transparency_by_location with region-specific transparency details (e.g., eu_transparency, uk_transparency). Requires page_id to be specified. See the full list of supported countries on the Meta Ad Library Countries page.

  • Name
    page_id
    Required
    Optional
    Description

    Specifies the page ID of the advertiser. Required when country is specified. You can obtain it from the Meta Ad Library API response, where each ad includes a page_id field.

Engine

  • Name
    engine
    Required
    Required
    Description

    Specifies the search engine. Must be set to meta_ad_library_ad_details.

Api Key

  • Name
    api_key
    Required
    Required
    Description

    Your API key for authentication. Include it as a query parameter (?api_key=YOUR_API_KEY) or in the Authorization header (Bearer YOUR_API_KEY).

Zero Data Retention

  • Name
    zero_retention
    Enterprise Only
    Enterprise Only
    Required
    Optional
    Description

    Set this parameter to true to disable all logging and persistent storage. No request parameters, HTML, or JSON responses are stored or logged. Suitable for high-compliance use cases. Debugging and support may be limited while enabled.

API Examples

Response with EU Transparency data

Response with EU Transparency data
GET
https://www.searchapi.io/api/v1/search?ad_archive_id=477570185419072&engine=meta_ad_library_ad_details
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "meta_ad_library_ad_details",
  "ad_archive_id": "477570185419072"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "aaa_info": {
    "targets_eu": true,
    "location_audience": [
      {
        "name": "Italy",
        "num_obfuscated": 0,
        "type": "countries"
      },
      ...
    ],
    "gender_audience": "All",
    "age_audience": {
      "min": 18,
      "max": 65
    },
    "eu_total_reach": 1613,
    "age_country_gender_reach_breakdown": [
      {
        "country": "IT",
        "age_gender_breakdowns": [
          {
            "age_range": "45-54",
            "male": 99,
            "female": 3,
            "unknown": 1
          },
          ...
        ]
      },
      ...
    ],
    "payer_beneficiary_data": [
      {
        "payer": "MEDIAPLUS ENGINE GMBH & CO. KG",
        "beneficiary": "BMW AG"
      }
    ]
  }
}

Response with UK transparency data

Response with UK transparency data
GET
https://www.searchapi.io/api/v1/search?ad_archive_id=2025473324917457&country=GB&engine=meta_ad_library_ad_details&page_id=1408382849231231
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "meta_ad_library_ad_details",
  "ad_archive_id": "2025473324917457",
  "page_id": "1408382849231231",
  "country": "GB"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "transparency_by_location": {
    "eu_transparency": {
      ...
    },
    "uk_transparency": {
      "location_audience": [
        {
          "name": "Worldwide",
          "num_obfuscated": 0,
          "type": "country_groups"
        }
      ],
      "gender_audience": "All",
      "age_audience": {
        "min": 18,
        "max": 65
      },
      "total_reach": 9135,
      "age_country_gender_reach_breakdown": [
        {
          "country": "GB",
          "age_gender_breakdowns": [
            {
              "age_range": "45-54",
              "male": 97,
              "female": 75
            },
            {
              "age_range": "65+",
              "male": 35,
              "female": 14
            },
            ...
          ]
        }
      ]
    }
  }
}

Response with political ad

Response with political ad
GET
https://www.searchapi.io/api/v1/search?ad_archive_id=958587666227752&engine=meta_ad_library_ad_details&is_political=true
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "meta_ad_library_ad_details",
  "ad_archive_id": "958587666227752",
  "is_political": "true"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "insights": {
    "age_gender_data": [
      {
        "age_range": "18-24",
        "female": 0.02
      },
      {
        "age_range": "25-34",
        "female": 0.09
      },
      ...
    ],
    "currency_matched": true,
    "location_data": [
      {
        "reach": 0,
        "region": "Alabama"
      },
      {
        "reach": 0,
        "region": "Nevada"
      },
      ...
    ],
    "single_country": "US"
  },
  "verified_voice_context": {
    "types": [
      "POLITICAL"
    ]
  }
}