UnifAPI Docs

List ads a Facebook Page is running

Returns ads from the Meta Ad Library for one advertiser Page id, with country, status, media type, language and date filters. Find Page ids with /facebook/advertisers/search. 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/advertisers/{id}/ads

Authorization

bearerAuth
AuthorizationBearer <token>

UnifAPI API key. Provider credentials are managed by UnifAPI.

In: header

Path Parameters

id*string

Advertiser Facebook Page id.

Length1 <= length <= 500

Query Parameters

country?string

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

Length2 <= length <= 3
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"
language?string

Optional language code filter.

Length2 <= length <= 8
sort_by?string

Optional sort order for returned ads.

Value in

  • "impressions"
  • "most-recent"
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/advertisers/string/ads"
{  "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",            "width": 0,            "height": 0          }        ],        "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"      }    }  ],  "pagination": {    "has_more": true,    "next_cursor": "string"  },  "billing": {    "credits_charged": 0,    "records_charged": 0,    "balance_remaining": 0,    "truncated_due_to_balance": true  }}