UnifAPI Docs

Search Facebook Ad Library ads

Searches the Meta Ad Library by keyword with country, status, media type, language and date filters. Paginate with `cursor`.

Pricing — $ · min $0.003

Minimum 3 credits ($0.003) per call. Records returned above the minimum bill 1 credit ($0.001) each.

GET
/facebook/ads/search

Authorization

bearerAuth
AuthorizationBearer <token>

UnifAPI API key. Provider credentials are managed by UnifAPI.

In: header

Query Parameters

query*string

Search query text for Facebook Ad Library ads.

Length1 <= length <= 4096
sort_by?string

Optional sort order for returned ads.

Value in

  • "impressions"
  • "most-recent"
search_type?string

Optional keyword matching mode for the search query.

Value in

  • "keyword-unordered"
  • "exact-phrase"
ad_type?string

Optional filter for all ads or political and issue ads.

Value in

  • "all"
  • "political-and-issue"
country?string

Optional country code filter. Use ALL to search all countries.

Length2 <= length <= 3
language?string

Optional ISO 639-1 language code (two letters, for example EN, ES or FR) to only return ads in that language.

Length2 <= length <= 2
status?string

Optional ad status filter.

Value in

  • "all"
  • "active"
  • "inactive"
media_type?string

Optional creative media filter.

Value in

  • "all"
  • "image"
  • "video"
  • "meme"
  • "image-and-meme"
  • "none"
start_date?string

Optional start date filter in YYYY-MM-DD format.

Length1 <= length
end_date?string

Optional end date filter in YYYY-MM-DD format.

Length1 <= length
cursor?string

Opaque pagination cursor from a previous response's pagination.next_cursor. Omit for the first page.

Length1 <= length <= 16384

Header Parameters

Unifapi-Version?"2026-07-01"

Pin the API version an integration was built against (date-based, e.g. 2026-07-01). Omit to use the current version. Public URL paths stay stable and unversioned; breaking changes ship under a new dated version and are announced with Deprecation and Sunset response headers. The served version is echoed in every response's Unifapi-Version header. Policy: https://unifapi.com/versioning.md

Default"2026-07-01"

Value in

  • "2026-07-01"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/facebook/ads/search?query=string"
{  "request_id": "string",  "data": [    {      "id": "string",      "ad_id": "string",      "url": "string",      "page": {        "id": "string",        "name": "string",        "url": "string",        "is_deleted": true,        "profile_picture_url": "string",        "like_count": 0,        "categories": [          "string"        ]      },      "campaign": {        "collation_id": "string",        "collation_count": 0      },      "is_active": true,      "publisher_platforms": [        "string"      ],      "started_at": 0,      "ended_at": 0,      "categories": [        "string"      ],      "countries": [        "string"      ],      "impressions": {        "text": "string",        "index": 0      },      "spend": {        "amount": "string",        "currency": "string"      },      "creative": {        "body_text": "string",        "title": "string",        "caption": "string",        "link_url": "string",        "link_description": "string",        "call_to_action": "string",        "call_to_action_type": "string",        "display_format": "string",        "images": [          {            "url": "string",            "resized_url": "string",            "watermarked_resized_url": "string"          }        ],        "videos": [          {            "hd_url": "string",            "sd_url": "string",            "preview_image_url": "string"          }        ],        "cards": [          {            "title": "string",            "body": "string",            "caption": "string",            "link_url": "string",            "image_url": "string",            "video_url": "string"          }        ]      },      "branded_content": {        "page_id": "string",        "page_name": "string",        "page_url": "string"      },      "eu_transparency": {        "total_reach": 0,        "age_range": {          "min": 0,          "max": 0        },        "gender": "string",        "locations": [          {            "name": "string",            "type": "string",            "is_excluded": true          }        ],        "payers": [          {            "payer": "string",            "beneficiary": "string"          }        ]      }    }  ],  "pagination": {    "has_more": true,    "next_cursor": "string"  },  "billing": {    "credits_charged": 0,    "records_charged": 0,    "balance_remaining": 0,    "truncated_due_to_balance": true  }}