Ad API: one schema on 4 platforms

Endpoints

11 endpoints return ads on Facebook Ad Library, Google Ads Transparency Center, LinkedIn Ad Library and TikTok Ad Library.

Schema

Single-item endpoints return this object as data; list endpoints return an array of them as data with a page object. The standard meta comes with every response.

platformstring

Library owner's platform ID (facebook for Meta's library, tiktok, google, linkedin).

idstring

Library ad ID (string).

urlstring uri

Public library page of the ad.

advertiserobject

The advertising page, business or account.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

paid_bystringnullable

Disclosed payer ("Paid for by").

is_activebooleannullable

True while the ad is running.

first_shown_atstring date-timenullable

First delivery, RFC 3339 UTC (often date-only: see approximate_fields).

last_shown_atstring date-timenullable

Last delivery, RFC 3339 UTC; null while active.

typestring

Creative shape. New values may be added; treat unknown values as other.

One ofimagevideocarouseltextdynamicother

publisher_platformsstring[]

Where it ran, lowercase IDs (facebook, instagram, messenger, audience_network, youtube, …); [] if not disclosed.

creativesobject[]

The ad's creatives: one per card of a carousel and per variation of a dynamic or catalog ad, else one for the ad itself; [] if none are shown.

Show 6 child fields

titlestringnullable

Headline.

bodystringnullable

Primary text.

link_urlstring urinullable

Destination URL.

link_descriptionstringnullable

Link description text.

cta_textstringnullable

Call-to-action label (e.g. Shop now).

mediaobject[]

Images and videos of this creative; [] if none.

Show 8 child fields

typestring

Kind of file. New values may be added; treat unknown values as other.

One ofimagevideoaudiogif

urlstring urinullable

Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at.

expires_atstring date-timenullable

When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire.

thumbnail_urlstring urinullable

Poster or preview image URL.

widthintegernullable

Width in pixels.

heightintegernullable

Height in pixels.

duration_msintegernullable

Duration in milliseconds (video and audio only).

alt_textstringnullable

Accessibility text provided by the author or platform.

languagesstring[]

BCP-47 languages of the ad; [] if not disclosed.

country_codesstring[]

ISO 3166-1 alpha-2 countries where it was shown; [] if not disclosed.

is_politicalbooleannullable

Categorized as a political or social-issue ad; false when the library files it under another category, null when it shows none.

impressionsobjectnullable

Impressions or times shown range; null when not disclosed.

Show 2 child fields

lower_boundinteger

Inclusive lower bound.

upper_boundintegernullable

Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.

reachobjectnullable

Unique users reached range; null when not disclosed.

Show 2 child fields

lower_boundinteger

Inclusive lower bound.

upper_boundintegernullable

Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.

audience_sizeobjectnullable

Estimated target audience size range; null when not disclosed.

Show 2 child fields

lower_boundinteger

Inclusive lower bound.

upper_boundintegernullable

Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.

spendobjectnullable

Spend range; null when not disclosed.

Show 3 child fields

lower_boundinteger

Inclusive lower bound, in whole units of currency.

upper_boundintegernullable

Inclusive upper bound in whole units of currency; null when open-ended.

currencystring

ISO 4217 currency code, uppercase (USD).

platform_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

Show 4 child fields

tiktokobjectnullable

A TikTok ad's own fields.

Show 12 child fields

is_removedbooleannullable

TikTok took the ad down (its rules or local law), in some or all regions.

removal_reasonsstring[]

TikTok's reasons for the takedown; [] when none (in unknown_fields when not shown).

categorystringnullable

The ad's topic as TikTok files it (Apps, Food & Beverage).

objectivestringnullable

The campaign objective (Reach, Traffic).

removal_country_codesstring[]

Countries where TikTok took the ad down (ISO 3166-1 alpha-2); [] when it was not taken down (in unknown_fields when not shown).

targetingobjectnullable

Whom the advertiser targeted and whom the ad reached, per country; null when not shown.

Show 11 child fields

countriesobject[]

Per country it ran in: the ages and genders targeted and the unique users reached.

Show 5 child fields

country_codestring

ISO 3166-1 alpha-2 country code.

reachobjectnullable

Unique users the ad reached there (rounded: approximate_fields); null when not shown.

Show 2 child fields

lower_boundinteger

Inclusive lower bound.

upper_boundintegernullable

Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.

age_rangesstring[]

Age ranges targeted (13-17, 18-24, 25-34, 35-44, 45-54, 55+); [] when not shown.

gendersstring[]

Genders targeted (female, male, unknown); [] when not shown.

breakdownobject[]

Unique users reached there by age range and gender, the segments TikTok shows a number for; [] when none.

Show 3 child fields

age_rangestring

Age range (18-24, 55+).

genderstring

female, male or unknown.

reachobject

Unique users reached (rounded: approximate_fields).

Show 2 child fields

lower_boundinteger

Inclusive lower bound.

upper_boundintegernullable

Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.

interestsstring[]

Interest categories targeted; [] when none.

video_interactionsstring[]

Video interaction categories targeted; [] when none.

creator_interactionsstring[]

Creator interaction categories targeted; [] when none.

provincesstring[]

Provinces or states targeted within the countries; [] when none.

citiesstring[]

Cities targeted; [] when none.

device_modelsstring[]

Device models targeted; [] when any.

operating_systemsstring[]

Operating systems targeted; [] when any.

is_custom_audiencebooleannullable

The advertiser targeted a custom audience (its own customer list or a lookalike).

is_audience_excludedbooleannullable

The advertiser excluded a custom audience.

is_high_spending_powerbooleannullable

Targeted at users TikTok rates as high spenders.

advertiser_business_idstringnullable

The advertiser's TikTok business ID (search_ads advertiser_id).

advertiser_registry_locationstringnullable

Where the advertiser is registered (Italy).

rankintegernullable

Place on Creative Center's Top Ads board, 1 first; null off the board.

like_countintegernullable

Likes the ad drew, as Creative Center counts them; null off the board.

ctr_top_percentnumbernullable

Click-through rate rank: the ad is in the top this many percent of ads (4 = top 4%); null off the board.

budgetstringnullable

Creative Center's budget level; null off the board. New values may be added; treat unknown values as other.

One oflowmediumhigh

googleobjectnullable

A Google ad's own fields.

Show 6 child fields

days_shownintegernullable

Days the ad was shown (the center's "Ran for"); null when not shown.

topicstringnullable

The ad's topic as Google labels it (Sports & Fitness); null when not shown.

product_categorystringnullable

The product category Google files a Shopping ad under (Apparel & Accessories); null otherwise.

is_syntheticbooleannullable

The advertiser disclosed synthetic (digitally altered or generated) content, as the ad's page labels it; false when it shows no such label.

regionsobject[]

Per country it was shown in: when, how often and on which Google services; [] when not shown (in unknown_fields).

Show 5 child fields

country_codestring

ISO 3166-1 alpha-2 country code.

first_shown_atstring date-timenullable

First day shown there, RFC 3339 UTC (date-only: approximate_fields); null when not shown.

last_shown_atstring date-timenullable

Last day shown there, RFC 3339 UTC (date-only: approximate_fields); null when not shown.

impressionsobjectnullable

Times shown there, Google's range; null when not disclosed.

Show 2 child fields

lower_boundinteger

Inclusive lower bound.

upper_boundintegernullable

Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.

servicesobject[]

Times shown there on each Google service; [] when not disclosed.

Show 2 child fields

servicestring

The Google service. New values may be added; treat unknown values as other.

One ofgoogle_searchgoogle_mapsgoogle_playgoogle_shoppingyoutubeother

impressionsobjectnullable

Times shown on it, Google's range (a lower bound of 0 when Google shows only "under" an upper bound).

Show 2 child fields

lower_boundinteger

Inclusive lower bound.

upper_boundintegernullable

Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.

targetingobjectnullable

Whom the advertiser selected; null when not disclosed.

Show 7 child fields

age_rangesstring[]

Age ranges included (18-24, 25-34, 35-44, 45-54, 55-64, 65+, unknown); [] when none.

excluded_age_rangesstring[]

Age ranges excluded; [] when none.

gendersstring[]

Genders included (male, female, unknown); [] when none.

excluded_gendersstring[]

Genders excluded; [] when none.

locationsobject[]

Locations included; [] when none.

Show 4 child fields

criterion_idstring

Google Ads geo target criterion ID (2840 is the United States).

namestringnullable

The location's name (California); null when Google did not resolve it.

full_namestringnullable

The name with the regions it lies in (California, United States); null when not resolved.

country_codestringnullable

ISO 3166-1 alpha-2 code of its country; null when not resolved.

excluded_locationsobject[]

Locations excluded; [] when none.

Show 4 child fields

criterion_idstring

Google Ads geo target criterion ID (2840 is the United States).

namestringnullable

The location's name (California); null when Google did not resolve it.

full_namestringnullable

The name with the regions it lies in (California, United States); null when not resolved.

country_codestringnullable

ISO 3166-1 alpha-2 code of its country; null when not resolved.

criteriaobject[]

The kinds of criteria the advertiser included or excluded (the EU disclosure); [] when not disclosed.

Show 3 child fields

categorystring

The kind of criteria. New values may be added; treat unknown values as other.

One ofdemographicslocationscontextualtopics_of_interestcustomer_lists

is_includedboolean

Criteria of this kind were included in the audience.

is_excludedboolean

Criteria of this kind were excluded from the audience.

facebookobjectnullable

A Meta Ad Library ad's own fields.

Show 17 child fields

cta_typestringnullable

The call to action's type (shop_now, learn_more), whatever language cta_text is in; null when the ad has none.

link_captionstringnullable

The link caption shown under the creative (usually the destination's domain); null when none.

special_ad_categoriesstring[]

Meta's special ad categories the ad is filed under (political, housing, employment, credit); [] for an ordinary ad.

collation_idstringnullable

The group of ads that share this creative and text; null when not shown.

collation_countintegernullable

How many ads share this creative and text; null when not shown.

partnerobjectnullable

The creator whose post a branded content ad promotes for the advertiser; null for other ads.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

advertiser_like_countintegernullable

The advertiser's page likes; null when not shown.

advertiser_categoriesstring[]

The advertiser page's categories (Wine/spirits); [] when not shown (in unknown_fields when not shown).

is_advertiser_deletedbooleannullable

The advertiser's page has since been deleted; null when not shown.

advertiser_instagramobjectnullable

The advertiser's Instagram account, when Meta links one; null otherwise or outside the ad's details.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

advertiser_instagram_follower_countintegernullable

Followers of the advertiser's Instagram account; null when not shown.

beneficiarystringnullable

Whom the ad benefits, as disclosed for ads shown in the EU; null when not disclosed.

is_syntheticbooleannullable

The advertiser disclosed digitally created or altered media (an AI disclosure); null when not shown.

is_removedbooleannullable

Meta took the ad down for breaking its standards; null when not shown.

removal_reasonsstring[]

Meta's reasons for taking it down; [] when none (in unknown_fields when not shown).

targetingobject[]

Whom the advertiser targeted and whom the ad reached, per region that discloses it (the EU, the UK); [] when not disclosed (in unknown_fields when not shown).

Show 7 child fields

regionstring

The disclosing region. New values may be added.

One ofeuuk

reachintegernullable

Unique accounts the ad reached in the region; null when not shown.

gendersstring[]

Genders targeted (female, male); [] when all.

age_minintegernullable

Youngest age targeted; null when not shown.

age_maxintegernullable

Oldest age targeted (65 means 65 and over); null when not shown.

locationsobject[]

Places the advertiser targeted or excluded; [] when not shown.

Show 3 child fields

namestring

The place as Meta names it (United Kingdom, Berlin).

typestringnullable

The kind of place (countries, regions, cities); null when not shown.

is_excludedboolean

The advertiser excluded the place rather than targeting it.

reach_by_countryobject[]

Unique accounts reached per country, by age range and gender; [] when not shown.

Show 2 child fields

country_codestring

ISO 3166-1 alpha-2 country code.

agesobject[]

Unique accounts reached there per age range.

Show 4 child fields

age_rangestring

The age range (18-24, 65+).

maleintegernullable

Men reached; null when not shown.

femaleintegernullable

Women reached; null when not shown.

unknownintegernullable

Accounts of unknown gender reached; null when not shown.

impression_sharesobjectnullable

A political or social-issue ad's audience: its share of impressions by age and gender and by region; null for other ads.

Show 2 child fields

by_age_genderobject[]

Share of impressions per age range, by gender (0 to 1).

Show 4 child fields

age_rangestring

The age range (18-24, 65+).

malenumbernullable

Share among men (0 to 1); null when not shown.

femalenumbernullable

Share among women (0 to 1); null when not shown.

unknownnumbernullable

Share among people of unknown gender (0 to 1); null when not shown.

by_regionobject[]

Share of impressions per region (0 to 1).

Show 2 child fields

regionstring

The region as Meta names it (California).

sharenumbernullable

Its share (0 to 1); null when not shown.

linkedinobjectnullable

A LinkedIn Ad Library ad's own fields.

Show 13 child fields

creative_typestringnullable

LinkedIn's code for the ad's format (SPONSORED_STATUS_UPDATE, SPONSORED_VIDEO, SPONSORED_INMAILS, JOBS_V2, …), finer than type; null when the library shows none.

formatstringnullable

The ad's format as the library labels it (Single Image Ad, Message Ad, Company Discovery Ad, …); null when not shown.

is_deletedbooleannullable

The library says the ad was deleted; false when it shows no such notice.

posterobjectnullable

The account the ad appears from: the advertiser, or a member whose post it promotes; null when the preview names none.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

poster_titlestringnullable

The line under the poster's name (a member's headline); null when none.

impressions_by_countryobject[]

Each country's share of the ad's impressions, as the library lists them; [] when not shown (in unknown_fields).

Show 4 child fields

countrystringnullable

The country's name, as the library writes it.

country_codestringnullable

ISO 3166-1 alpha-2 country code; null when the name is none the library's country list has.

share_percentintegernullable

Share of the ad's impressions, a whole percent as the library rounds it; null when under one percent.

is_under_one_percentbooleannullable

The library writes the share as less than one percent.

targetingobjectnullable

Whom the advertiser selected; null when not disclosed.

Show 8 child fields

languagesobjectnullable

The profile languages targeted or excluded; null when not shown.

Show 2 child fields

includedstring[]

Targeted; [] when none are listed.

excludedstring[]

Excluded; [] when none are listed.

locationsobjectnullable

The locations targeted or excluded, in the language of the advertiser's account; null when not shown.

Show 2 child fields

includedstring[]

Targeted; [] when none are listed.

excludedstring[]

Excluded; [] when none are listed.

audienceobjectnullable

Audience criteria; null when not shown.

Show 2 child fields

is_targetedbooleannullable

The advertiser targeted by this criterion.

is_excludedbooleannullable

The advertiser excluded by this criterion.

demographicobjectnullable

Demographic criteria; null when not shown.

Show 2 child fields

is_targetedbooleannullable

The advertiser targeted by this criterion.

is_excludedbooleannullable

The advertiser excluded by this criterion.

companyobjectnullable

Company criteria; null when not shown.

Show 2 child fields

is_targetedbooleannullable

The advertiser targeted by this criterion.

is_excludedbooleannullable

The advertiser excluded by this criterion.

educationobjectnullable

Education criteria; null when not shown.

Show 2 child fields

is_targetedbooleannullable

The advertiser targeted by this criterion.

is_excludedbooleannullable

The advertiser excluded by this criterion.

jobobjectnullable

Job criteria; null when not shown.

Show 2 child fields

is_targetedbooleannullable

The advertiser targeted by this criterion.

is_excludedbooleannullable

The advertiser excluded by this criterion.

member_interestsobjectnullable

Member interests and traits criteria; null when not shown.

Show 2 child fields

is_targetedbooleannullable

The advertiser targeted by this criterion.

is_excludedbooleannullable

The advertiser excluded by this criterion.

messageobjectnullable

A message ad's sender and buttons; null on every other format.

Show 3 child fields

sender_namestringnullable

The person the message is sent as; null when not shown.

sender_avatar_urlstring urinullable

The sender's picture; null when not shown.

buttonsstring[]

The message's buttons, in order; [] when none.

jobobjectnullable

The job a job ad promotes; null on every other format.

Show 2 child fields

companystringnullable

The company the job is at; null when not shown.

locationstringnullable

The job's location, as written; null when not shown.

eventobjectnullable

The event an event ad promotes; null on every other format.

Show 4 child fields

organizerstringnullable

Who hosts the event; null when not shown.

locationstringnullable

Where it happens, as written (Online); null when not shown.

starts_atstring date-timenullable

When it starts, RFC 3339 UTC; null when not shown.

ends_atstring date-timenullable

When it ends, RFC 3339 UTC; null when not shown.

documentobjectnullable

The document a document ad shows; null on every other format.

Show 2 child fields

titlestringnullable

The document's title; null when not shown.

page_countintegernullable

How many pages it has; null when not shown.

newsletterstringnullable

The newsletter an article ad's article belongs to; null when none.

companyobjectnullable

The company a company discovery ad presents; null on every other format.

Show 2 child fields

sizestringnullable

The company's size as the card writes it (10,001+ employees); null when not shown.

locationstringnullable

Where the company is, as the card writes it; null when not shown.

approximate_fieldsstring[]

JSON paths of values that are rounded, date-only or parsed from display text. A list path (external_links) means the list may be incomplete. [] when all exact.

unknown_fieldsstring[]

JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.

Item errors

Besides the request-level errors every endpoint can return, ad endpoints return:

Code	HTTP	Retry	Meaning	What to do
`not_found`	404	No	The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why).	Check the link or ID. Do not retry.