API Reference
  1. Atria Open API
  2. Ad Library

List saved library ads

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

List ads the calling workspace has saved from the global ad library. Each item carries the standard ad fields plus a saved_details block (saved_at, boards, tags).

Scoped to the workspace bound to your API key. Use the response cursor to paginate.

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

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
string

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

platform
array of objects

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

platform
display_format
array of objects

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).

Language
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.

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.

string

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

string

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

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.

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.

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 objects

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

status
Allowed:
boards
array of strings

Restrict to ads saved in the given board(s). Pass board_id values from GET /open/v1/boards. Repeatable.

Boards
tags
array of strings

Restrict to ads tagged with any of the given tag names.

Tags
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 objects

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

media_format
Allowed:

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.

cta
array of objects

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 objects

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
integer
≥ 0

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

integer
≥ 0

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

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.

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.

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.

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.

number
0 to 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.

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 objects

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:
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.

integer
≥ 0

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

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:
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.

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 objects

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
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.

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.

number

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

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:
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.

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.

string
enum

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

Allowed:
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.

number

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

string
enum

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

Allowed:
string
enum
Defaults to saved_newest

Sort order. saved_newest/saved_oldest use save time; newest/oldest use the ad's start date; most_active is longest currently-running; recently_ended is most recently stopped first.

most_impressions ranks by an ad's impression position within its own brand's pool, most_reach by disclosed lifetime reach, and most_saved by how many workspaces save it. Unlike on the global search, none of the three drops ads that lack the signal — they sort last instead.

integer
1 to 50
Defaults to 20

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

string

Opaque pagination cursor from the previous response.

Responses

Updated 4 months ago

Did this page help you?
Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 4 months ago

Did this page help you?