Skip to main content
POST
Bridgly SDK

Authorizations

Authorization
string
header
required

A Bridgly API key (bgly_…). Metered endpoints deduct credits from the resolved account.

Body

application/json
q
string

Keywords to search the ads’ text for, e.g. "running shoes". Leave it out to list every ad matching the other filters.

Pattern: \S
pageId
string

Only return ads from this advertiser: its Facebook Page ID, e.g. "15087023444", as returned in page.id or by the advertiser search. The Ad Library link of the advertiser’s ads (?view_all_page_id=<id>) works too.

Minimum string length: 1
exactPhrase
boolean
default:false

Match q as an exact phrase instead of matching any ad that has all its words. Defaults to false.

country
string
default:ALL

Two-letter country code to search ads shown in, e.g. "US" or "GB", or "ALL" for every country. Defaults to "ALL".

Pattern: ^([a-z]{2}|all)$
activeStatus
enum<string>
default:active

Return ads that are still running ("active"), that stopped ("inactive"), or both ("all"). Defaults to "active".

Available options:
active,
inactive,
all
adType
enum<string>
default:all

Ad category: "all", "political_and_issue_ads" (social issues, elections or politics), "housing_ads", "employment_ads" or "credit_ads". Defaults to "all".

Available options:
all,
political_and_issue_ads,
housing_ads,
employment_ads,
credit_ads
mediaType
enum<string>
default:all

Media in the ad: "all", "image", "meme", "image_and_meme", "video", or "none" for ads with no image or video. Defaults to "all".

Available options:
all,
image,
meme,
image_and_meme,
video,
none
platforms
enum<string>[]

Only return ads running on these platforms, e.g. ["instagram"]. Leave it out for every platform.

Available options:
facebook,
instagram,
messenger,
audience_network,
whatsapp,
threads
languages
string[]

Only return ads in these languages, as two-letter codes, e.g. ["en", "es"].

Pattern: ^[A-Za-z]{2}$
startDate
string<date>

Only return ads that ran on or after this date (YYYY-MM-DD), e.g. "2026-01-01".

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
endDate
string<date>

Only return ads that ran on or before this date (YYYY-MM-DD), e.g. "2026-03-31".

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
sortBy
enum<string>
default:impressions

Order of the ads: most seen first ("impressions"), or recently started ads first ("recent"), which Meta orders roughly rather than strictly by start date. Defaults to "impressions".

Available options:
impressions,
recent
count
integer
default:10

Number of results to return (1–30). Defaults to 10.

Required range: 1 <= x <= 30
cursor
string

The previous response's nextCursor, to fetch the next page. Omit it for the first page.

cacheMaxAgeHours
integer

Accept a cached result scraped up to this many hours ago. A cached result costs no credits, and its cachedAt says when it was scraped. When no cached result is that recent, the data is scraped live at the normal price. Leave it out to always scrape live, e.g. 24.

Required range: x <= 9007199254740991
cacheOnly
boolean

Return only a cached result and never scrape live. With cacheMaxAgeHours, only a result that recent is returned; without it, the latest cached result of any age. Responds 404, at no cost, when there is none, e.g. true.

Response

Default Response

timeMs
number
required

Wall-clock time the request took to complete, in milliseconds.

creditsCost
number
required

Number of account credits this request consumed.

cachedAt
string<date-time> | null
required

When the returned data was scraped, if it came from the cache. Null when it was scraped live for this request.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
data
object
required