Skip to documentation
Docs
Sign in Get an API key API key
Browse documentation
For AI agents

Connect your agent to live platform data.

Open in
Facebook Ad Library API Capability

Search ads

Searches the public Facebook Ad Library by keyword and returns raw creative and transparency metadata. Supports validated country, language, publisher-platform, media, status, date, and sort filters.

Capability ID fb-adlibrary.ad.search
Maximum runtime 120 seconds
View raw

POST /execute Shared execution endpoint

Input parameters

active string optional

Filter by delivery status Allowed values: `all`, `active`, `inactive`. Default: `all`.

Available values allactiveinactive
country string optional

Two-letter uppercase ISO country code or ALL for worldwide Default: `US`.

Example US
cursor string optional

Opaque scoped continuation token returned as next_cursor; restart from the beginning if the source changed

end_date string optional

Optional latest impression date (YYYY-MM-DD)

languages array<string> optional

Optional JSON array of content-language codes, for example ["en","es"]

limit integer optional

Maximum number of ads to return From 1 to 100. Default: `50`.

Example 5
media_type string optional

Filter by creative media type Allowed values: `all`, `image`, `video`, `meme`, `none`. Default: `all`.

Available values allimagevideomemenone
platforms array<string> optional

Optional JSON array of publisher platforms Allowed values: `facebook`, `instagram`, `messenger`, `audience_network`, `threads`, `whatsapp`.

Available values facebookinstagrammessengeraudience_networkthreadswhatsapp
query string required

Non-empty search keyword or phrase (maximum 200 characters)

Example nike
sort_by string optional

Sort the returned creatives Allowed values: `impressions`, `relevance`, `date`. Default: `impressions`.

Available values impressionsrelevancedate
start_date string optional

Optional earliest impression date (YYYY-MM-DD)

Response

Successful output is returned in results[0].data.

Raw platform output is intentionally open-ended and may evolve with the upstream source.

Illustrative sample The example response is shown in the response panel.

Illustrative output fields

Values illustrate one response. Read the guidance above for missing values and limits; fields can vary with the requested operation and the data available.

PathObserved typeExample
items array 3 items
items array 3 items
next_cursor string [redacted:token]
total_items integer 5

Execution behavior

A 200 response completed inline. A 202 response was queued; poll GET /jobs/:id until the job reaches completed or failed.