Meta Ads Library API
Search the Meta Ad Library: ads by keyword or advertiser, advertiser page details, archived ad details and supported countries.
Base URL https://api.socialapis.io. Every call needs your API key in the x-api-token header.
List Ad Countries
Get list of supported country codes for Meta Ads Library filtering.
Endpoint
GET /facebook/ads/countries
Parameters
None.
Pricing
Per call: 1 credit.
Example Request
curl --request GET \
--url 'https://api.socialapis.io/facebook/ads/countries' \
--header 'x-api-token: YOUR_API_KEY'
Search Ads
Search ads in the Meta Ad Library by keyword or page ID with filters.
Endpoint
GET /facebook/ads/search
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | No | Search keyword for ads |
| ad_page_id | string | No | Facebook AD Page ID. Used only if query is not provided. |
| country | string | No | ISO country code or ALL |
| activeStatus | string | No | Filter by ad status: ALL, Active, or Inactive |
| after_time | string | No | Filter ads after this date (YYYY-MM-DD) |
| before_time | string | No | Filter ads before this date (YYYY-MM-DD) |
| sort_data | string | No | Sort: impressions (high to low) or recent (most recent) |
| end_cursor | string | No | Pagination cursor |
Pricing
Per call: 1 credit.
Example Request
curl --request GET \
--url 'https://api.socialapis.io/facebook/ads/search' \
--header 'x-api-token: YOUR_API_KEY'
Get Advertiser Page Details
Get detailed info about a specific Facebook page from the Ads Library.
Endpoint
GET /facebook/ads/page-details
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| page_id | string | Yes | Facebook Page ID |
Pricing
Per call: 1 credit.
Example Request
curl --request GET \
--url 'https://api.socialapis.io/facebook/ads/page-details?page_id=YOUR_PAGE_ID' \
--header 'x-api-token: YOUR_API_KEY'
Get Ad Archive Details
Get detailed info about a specific archived ad by archive ID.
Endpoint
GET /facebook/ads/archive-details
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| ad_archive_id | string | Yes | Ad Archive ID |
| page_id | string | No | Facebook Page ID |
| country | string | No | ISO country code or ALL |
| is_ad_non_political | boolean | No | Filter non-political ads |
| is_ad_not_aaa_eligible | boolean | No | Filter AAA eligibility |
Pricing
Per call: 1 credit.
Example Request
curl --request GET \
--url 'https://api.socialapis.io/facebook/ads/archive-details?ad_archive_id=YOUR_AD_ARCHIVE_ID' \
--header 'x-api-token: YOUR_API_KEY'
Find Advertisers by Keyword
Search for ads by keyword with optional country filter.
Endpoint
GET /facebook/ads/keywords
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Search keyword |
| country | string | No | ISO country code or ALL |
Pricing
Per call: 1 credit.
Example Request
curl --request GET \
--url 'https://api.socialapis.io/facebook/ads/keywords?query=coffee' \
--header 'x-api-token: YOUR_API_KEY'
Verifying what you were charged
Every paid response carries an X-SocialAPIs-Credits-Deducted header with the exact credit amount charged for that request. Variable-priced endpoints (page and group posts, media download) report the resolved amount here, so you can reconcile usage without checking the dashboard. Prices on this page come from the live endpoint catalog when the docs were built; socialapis.io/openapi.json always has the current ones.