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.

API Parameters

Search Params

  • Name
    ad_details_token
    Required
    Optional
    Description

    Recommended. Obtain it from the ad_details_token field on each ad returned by the Meta Ad Library API. Using ad_details_token provides better results for extracting political ads and eu_transparency or uk_transparency data. Using ad_archive_id alone may not return results for all ads.

  • Name
    ad_archive_id
    Required
    Optional
    Description

    Specifies the ad's unique ID. Required when ad_details_token is not provided. 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.

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.org/api/v1/search?ad_archive_id=477570185419072&engine=meta_ad_library_ad_details
Request
import requests

url = "https://www.searchapi.org/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.org/api/v1/search?ad_details_token=eyJhZF9hcmNoaXZlX2lkIjoiMjAyNTQ3MzMyNDkxNzQ1NyIsInBhZ2VfaWQiOiIxNDA4MzgyODQ5MjMxMjMxIiwiY291bnRyeSI6IkdCIiwiaXNfcG9saXRpY2FsIjoiZmFsc2UifQ&engine=meta_ad_library_ad_details
Request
import requests

url = "https://www.searchapi.org/api/v1/search"
params = {
  "engine": "meta_ad_library_ad_details",
  "ad_details_token": "eyJhZF9hcmNoaXZlX2lkIjoiMjAyNTQ3MzMyNDkxNzQ1NyIsInBhZ2VfaWQiOiIxNDA4MzgyODQ5MjMxMjMxIiwiY291bnRyeSI6IkdCIiwiaXNfcG9saXRpY2FsIjoiZmFsc2UifQ"
}

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.org/api/v1/search?ad_details_token=eyJhZF9hcmNoaXZlX2lkIjoiOTMxMzk0MzY2MjQxODU4IiwicGFnZV9pZCI6IjEwMTA5MDU1OTI5NTY5NiIsImNvdW50cnkiOiJVUyIsImlzX3BvbGl0aWNhbCI6InRydWUifQ&engine=meta_ad_library_ad_details
Request
import requests

url = "https://www.searchapi.org/api/v1/search"
params = {
  "engine": "meta_ad_library_ad_details",
  "ad_details_token": "eyJhZF9hcmNoaXZlX2lkIjoiOTMxMzk0MzY2MjQxODU4IiwicGFnZV9pZCI6IjEwMTA5MDU1OTI5NTY5NiIsImNvdW50cnkiOiJVUyIsImlzX3BvbGl0aWNhbCI6InRydWUifQ"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "advertiser": {
    "page": {
      "about": {
        "text": "Unifying the Church under primary doctrine..."
      },
      "id": "101090559295696"
    },
    "ad_library_page_info": {
      "page_spend": {
        "lifetime_by_disclaimer": [
          {
            "disclaimer": "TURNING POINT USA NFP",
            "spend": 96301
          }
        ],
        "weekly_by_disclaimer": [
          {
            "disclaimer": "TURNING POINT USA NFP",
            "spend": 840
          }
        ],
        "is_political_page": true
      },
      "page_info": {
        "page_id": "101090559295696",
        "page_name": "TPUSA Faith",
        "page_category": "Nonprofit organization",
        "ig_followers": 575572,
        "ig_username": "tpusafaith",
        "likes": 456618,
        ...
      }
    }
  },
  "insights": {
    "age_gender_data": [
      {
        "age_range": "18-24",
        "female": 0.05,
        "male": 0.09
      },
      {
        "age_range": "25-34",
        "female": 0.03,
        "male": 0.07
      },
      ...
    ],
    "currency_matched": true,
    "location_data": [
      {
        "reach": 0.13,
        "region": "California"
      },
      {
        "reach": 0.09,
        "region": "Texas"
      },
      {
        "reach": 0.08,
        "region": "Florida"
      },
      ...
    ],
    "single_country": "US"
  },
  "verified_voice_context": {
    "types": [
      "POLITICAL"
    ]
  }
}