Search ad library

get

https://api.tryatria.com/open/v1/ad-library/search

Search Atria's global ad library across all platforms. Returns a paginated list of ads matching the given filters, ordered by the chosen sort order.

Use the returned cursor value as the cursor query parameter on the next request to fetch the following page. A null cursor in the response means there are no more results.

Returns: code=0 success; code=40001 invalid query parameters.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

query

string

Free-text search against ad title, body and brand name.

platform

array of strings

Filter by ad platform. Repeatable. Allowed values: facebook, instagram, messenger, audience_network, threads, whatsapp, tiktok, linkedin.

platform

display_format

array of strings

Filter by display format. Repeatable. Allowed values: image, video, carousel, multi_images, multi_videos, dco, dpa.

display_format

Allowed:

language

array of strings

Filter by ad copy language (ISO 639-1 code, e.g. en, zh).

Language

start_date

string

deprecated

Deprecated — use active_since, which this is an alias for. Despite the name it never bounded the ad's start date: it selects ads still running on or after the given date (YYYY-MM-DD). Passing it together with active_since is rejected.

end_date

string

deprecated

Deprecated — use launched_before, which this is an alias for. Despite the name it never bounded the ad's end date: it selects ads that first ran on or before the given date (YYYY-MM-DD). Passing it together with launched_before is rejected.

launched_after

string

Ads that first ran on or after this date, format YYYY-MM-DD. A launch bound, not an activity one.

launched_before

string

Ads that first ran on or before this date, format YYYY-MM-DD. Pair with launched_after to bound a launch window.

active_since

string

Ads still running on or after this date, format YYYY-MM-DD. Keeps ads launched long before it, as long as they had not stopped by then — that is what makes it different from the launch bounds. For a closed period, combine it with launched_before: 'what were they running in August' is active_since=2026-08-01 plus launched_before=2026-08-31. There is no end-date filter, so ads that stopped before a given date cannot be selected.

min_days_running

integer

≥ 0

Only ads observed running for at least this many days — the measure days_running reports. It is counted up to last_seen_date and stops advancing there, so a high bound can drop ads that are still running but were last scraped a while ago.

max_days_running

integer

≥ 0

Only ads observed running for at most this many days. Reads the same measure as min_days_running; pair the two to bound a range.

status

array of strings

Filter by ad status. Repeatable. Allowed values: active, inactive.

status

Allowed:

industry

array of strings

Filter by brand industry tag. Free-form tags from the brand's industries (e.g. apparel, sportswear, health/beauty, product/service).

Industry

video_length

array of strings

Filter video ads by duration buckets in seconds. Repeatable. Allowed buckets: 0-15, 15-30, 30-60, 60-120, 120- (60-plus seconds, open-ended).

video_length

Allowed:

brand_id

array of strings

Filter to these library brands. Repeatable. Obtain ids from any ad list endpoint's items[].brand_id.

Brand Id

unified_brand_id

array of uuids

Unified brand UUIDs from /inspo-brands/search. Repeatable; resolved to canonical brands and this workspace's tracked advertisers. Intersects brand_id and takes precedence over is_following_brand_only. Unknown or empty effective scope returns no ads. Omit this parameter to clear selection.

Unified Brand Id

is_following_brand_only

boolean

Defaults to false

When brand_id is omitted or empty, restrict to advertisers followed by this workspace. Locked follows are included. A nonempty brand_id overrides this flag without intersecting the followed scope. Explicit unified_brand_id takes precedence and intersects brand_id.

exclude_brand_id

array of strings

Drop these library brands from the results. Repeatable. Useful when a search comes back dominated by one advertiser and the question is who else runs this kind of ad.

Exclude Brand Id

media_format

array of strings

Filter by what the creative is, one step coarser than display_format. Repeatable. Allowed values: image, video, carousel, other.

media_format

Allowed:

link_url

array of strings

Filter by exact destination URL. Repeatable. Matches items[].link_url verbatim — it is not a prefix or domain match, so use it to find every ad pointing at one landing page.

Link Url

cta

array of strings

Filter by call-to-action. Repeatable. Matches the normalized items[].cta_type, not the button label in items[].cta_text. others selects ads that carry a CTA outside the named values, so the options together cover every ad that has one.

cta

theme

array of strings

Filter by creative theme. Repeatable. Takes the keys listed here (e.g. problem_solution), not the labels returned in items[].themes (e.g. Problem & solution) — the two vocabularies do not interchange, so a value read off a response cannot be passed back in. Ads the tagger has not processed carry no theme and are excluded by any theme filter.

theme

min_body_length

integer

≥ 0

Only ads whose body copy is at least this many characters — the measure items[].body_length reports.

max_body_length

integer

≥ 0

Only ads whose body copy is at most this many characters. Pair with min_body_length to bound a range.

min_creative_duplicates

integer

≥ 0

Only ads whose creative is shared by at least this many ads — the count items[].creative_duplicates reports. It includes the ad itself, so 1 matches everything and 2 is the floor for 'the creative was reused at all'. The count is a snapshot taken when the creative was first observed and never recomputed, and the backfill over older ads is still running, so any bound here also excludes every ad the count has not reached yet.

max_creative_duplicates

integer

≥ 0

Only ads whose creative is shared by at most this many ads. Reads the same count as min_creative_duplicates, with the same exclusion of ads the backfill has not reached.

partner_ads

boolean

Defaults to false

Restrict to partner (branded-content) ads, where the page shown differs from the advertiser paying for it. Ads whose partner status was never disclosed are excluded, so this is not the complement of items[].is_partner_ad == false.

max_impression_rank

integer

≥ 1

Only ads ranked at or above this position within their own brand's pool, where 1 is the strongest. Reads items[].impression_rank, and which of the two ranks it reads depends on impression_rank_period. Ads that were never ranked are excluded.

max_impression_percentile

number

≤ 1

Only ads in this top fraction of their brand's pool — 0.1 is the top 10%. Lower means more impressions. Ads that were never ranked are excluded.

impression_rank_period

string

enum

Which rank the impression bounds read. current is the position held right now, which exists only while an ad runs — combined with status=inactive it returns nothing by construction. all_time is the best position the ad ever held. Modifies max_impression_rank / max_impression_percentile; passing it without one of those is rejected.

Allowed:

impression_trend

array of strings

Filter by the ad's recent impression-rank trajectory. Repeatable. Meta-only, and ads with fewer than two ranked days have no derivable trend and are excluded.

impression_trend

Allowed:

min_reach

integer

≥ 0

Only ads that reached at least this many people. Reads items[].total_reach by default, or the movement over reach_period when that is given. Reach comes from EU/UK/BR transparency disclosures, so any reach bound also drops every ad without one.

max_reach

integer

≥ 0

Only ads that reached at most this many people. Same source and same exclusion as min_reach.

reach_period

string

enum

Window the reach bounds read. Omitted means the lifetime total. Unlike the growth bounds below, the reach bounds work without a period — so this is only rejected when it arrives without one.

Allowed:

min_audience_age

integer

≥ 0

Only ads whose disclosed target audience starts at or above this age, i.e. items[].age_audience.min. Disclosure data, so ads without it are excluded.

max_audience_age

integer

≥ 0

Only ads whose disclosed target audience ends at or below this age, i.e. items[].age_audience.max. Same exclusion as min_audience_age.

audience_gender

array of strings

Filter by disclosed target gender, matched exactly. Repeatable. Women returns women-only audiences and does not include ads targeting All — pass both to get broad ones too. Ads without a disclosure are excluded.

audience_gender

Allowed:

main_country

array of strings

Filter by the country the disclosure attributes most of the reach to (ISO 3166-1 alpha-2). Repeatable. Combines with target_countries as OR, not AND.

Only EU, UK and Brazil values ever appear here, because only those regimes require the disclosure this reads. main_country=US is therefore always empty — use target_countries to ask which countries an ad was aimed at, which is not limited that way.

Main Country

target_countries

array of strings

Filter by countries the ad was targeted at (ISO 3166-1 alpha-2). Repeatable. Combines with main_country as OR.

Target Countries

exclude_target_countries

array of strings

Drop ads targeted at any of these countries (ISO 3166-1 alpha-2). Repeatable. Applied after the two filters above.

Exclude Target Countries

min_facebook_page_likes

integer

≥ 0

Only ads whose brand has at least this many Facebook page likes, i.e. items[].brand_likes. This is a Meta-only signal, so setting it also drops every TikTok-origin ad from the result.

min_reach_pct_change

number

Only ads whose reach grew by at least this fraction over reach_pct_change_period — 0.3 is 30% growth, and negative bounds select decline. Requires the period. Ads without enough reach history for that window are excluded.

max_reach_pct_change

number

Only ads whose reach grew by at most this fraction over reach_pct_change_period. See min_reach_pct_change.

reach_pct_change_period

string

enum

Window the reach-growth bounds read. Required alongside them, and rejected without them. There is no all-time option: a change needs a baseline, and a lifetime baseline is zero by construction.

Short windows also demand a fresh observation. The stored growth figure freezes when an ad stops being scanned, so a 1d or 7d question only counts ads observed within roughly half that window — otherwise a months-old number would read as this week's movement. Widen the window if a narrow one comes back empty.

Allowed:

min_impression_rank_delta

integer

Only ads whose rank moved by at least this many positions over impression_rank_delta_period, measured as rank(latest) - rank(baseline) — so negative numbers mean the ad climbed. max_impression_rank_delta=-5 is 'climbed five places or more'. Requires the period; ads without enough rank history for the window are excluded.

max_impression_rank_delta

integer

Only ads whose rank moved by at most this many positions over impression_rank_delta_period. See min_impression_rank_delta for the sign convention.

impression_rank_delta_period

string

enum

Window the rank-movement bounds read. Required alongside them, and rejected without them.

Allowed:

min_impression_percentile_change

number

Only ads whose percentile moved by at least this much over impression_percentile_change_period, in percentile points. Negative means the ad climbed, same convention as the rank deltas. Requires the period; ads without enough history are excluded.

max_impression_percentile_change

number

Only ads whose percentile moved by at most this much over impression_percentile_change_period. See min_impression_percentile_change.

impression_percentile_change_period

string

enum

Window the percentile-change bounds read. Required alongside them, and rejected without them.

Allowed:

order

string

enum

Defaults to newest

Sort order. newest (default) and oldest go by the ad's start date, most_active is longest currently-running, recently_ended is most recently stopped first, best_match is relevance — only meaningful with query.

most_impressions ranks by an ad's impression position within its own brand's pool, and most_saved by how many workspaces save it. Both read a signal most ads do not carry, so on the global library they also restrict the result to ads that carry it — ranked ads for the first, ever-saved ads for the second. Neither narrows a brand-scoped listing.

most_reach ranks by disclosed lifetime reach, and narrows on a stricter rule than those two: it drops the ads without a reach total only when nothing else has narrowed the search. Add a filter or a keyword and the ads without one come back, sorted last — exclude_brand_id is the exception, since dropping a few brands still leaves the sort reading almost the whole library. Reach is an EU/UK/BR disclosure, so on an untouched feed this sort shows a small slice of it.

page_size

integer

1 to 50

Defaults to 20

Items per page (1-50, default 20).

cursor

string

Opaque pagination cursor from the previous response.

Responses

200Successful Response Input validation also returns HTTP 200 with code=40001 and message.

401Authentication failed

429rate limit or quota exceeded