facebookAdLibrary

Search

Search the Facebook (Meta) Ad Library by keyword. GET requests are capped at approximately 1,500 results due to cursor size limits. For larger result sets, use this endpoint as a POST request with the query parameters passed in the request body.

get/v1/scrape/facebook-ad-library/search

Request

  • Base URL: https://api.sociavault.com
  • URL: https://api.sociavault.com/v1/scrape/facebook-ad-library/search
  • Auth: API key in header X-API-Key

Query parameters

querystring required
Example:running

Keyword to search for

sort_by'total_impressions' | 'relevancy_monthly_grouped'
Example:total_impressions

Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.

search_type'keyword_unordered' | 'keyword_exact_phrase'
Example:keyword_unordered

If you want to search by exact phrase or not

ad_type'all' | 'political_and_issue_ads'
Example:all

Search for all ads or only political and issue ads

countrystring
Example:ALL

This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.

status'ALL' | 'ACTIVE' | 'INACTIVE'
Example:ACTIVE

Status of the ad. Defaults to ACTIVE.

media_type'ALL' | 'IMAGE' | 'VIDEO' | 'MEME' | 'IMAGE_AND_MEME' | 'NONE'
Example:ALL

Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme.

start_datestring
Example:2025-01-05

Impressions start date. Needs to be in YYYY-MM-DD format.

end_datestring
Example:2025-02-16

Impressions end date. Needs to be in YYYY-MM-DD format.

cursorstring
Example:AQHRYLVDkoMkvGv7yK1rcce-vJmKiKv330R4v3j9KHSOaYvmF1bq1QkotG0rgW8Fkrj-

Cursor to paginate through results

trimboolean

Set to true for a trimmed down version of the response

Response

Successful response

Key Response Fields:

  • is_active: Whether the ad is currently running
  • ad_archive_id: The actual ad id

Changes

No recorded changes to this operation across all 1 revision of this API.