List Meta ads by page URL | Meta Ads API

Lists Meta Ad Library ads for a Facebook Page given its url (page URL or username), with no numeric page_id needed. Filters and cursor pagination match Get Page Ads.

1 credit / requestBilled only on success

Authorization

ApiKeyAuth

x-api-key<token>

In: header

Query Parameters

country?string

ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.

Length2 <= length <= 2

active_status?string

Ad delivery status. all = active and inactive ads, active = currently running ads, inactive = stopped ads.

Value in

"all"
"active"
"inactive"

media_type?string

Creative format filter. all = every format, image = static images, video = videos, meme = image/text meme-style creatives.

Value in

"all"
"image"
"video"
"meme"

sort_mode?"total_impressions"

Sort by total impressions.

Value in

"total_impressions"

sort_direction?"desc"

Sort direction. Use with sort_mode.

Value in

"desc"

date_min?string

Start Date in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$

date_max?string

End Date in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$

cursor?string

Pass pageInfo.cursor from the previous response to get the next page. Omit for the first page.

page_size?integer

Number of ads to return per request. Accepted range: 1-50.

Range1 <= value <= 50

content_languages?string

Comma-separated ISO 639-1 language codes, for example en,hi.

publisher_platforms?string

Comma-separated platforms. Accepted values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER.

raw?boolean

Set to true to return the unprocessed Ad Library payload instead of the normalized response.

url*string

A public Facebook Page URL or its username/handle — for example https://www.facebook.com/nike, facebook.com/nike, or just nike. A profile.php?id= URL or a bare numeric Page ID is accepted and used as-is.

Length1 <= length <= 2000

curl -X GET "https://example.com/v1/meta/page-by-url?url=https%3A%2F%2Fwww.facebook.com%2Fnike" \  -H "x-api-key: YOUR_API_KEY"

{  "data": {    "items": [      {        "ad_archive_id": "string",        "page_id": "string",        "property1": null,        "property2": null      }    ],    "pageInfo": {      "cursor": "string",      "hasNextPage": true    }  }}