Ad API for Facebook: the ad schema

Endpoints

1 endpoint returns ads on Facebook.

GETFacebook Ad Library Search API/v1/facebook/search_ads

Schema

Every endpoint above returns an array of these objects as data, with a page object. The standard meta comes with every response.

Field	Type	Description
`platform`	`string`	Library owner's platform ID (facebook for Meta's library, tiktok, google, linkedin).
`id`	`string`	Library ad ID (string).
`url`	`string` (uri)	Public library page of the ad.
`advertiser`	`object`	The advertising page, business or account.
`advertiser.id`	`string` or `null`	Platform-native account ID; null when only the handle is known.
`advertiser.username`	`string` or `null`	Handle without the @; null when the account has none.
`advertiser.display_name`	`string` or `null`	Display name shown on the profile.
`advertiser.url`	`string` (uri) or `null`	Canonical profile URL.
`advertiser.avatar_url`	`string` (uri) or `null`	Profile picture URL. Platform CDN URLs can expire within hours.
`advertiser.is_verified`	`boolean` or `null`	Platform verification badge; null where the platform has no badge.
`paid_by`	`string` or `null`	Disclosed payer ("Paid for by").
`is_active`	`boolean` or `null`	True while the ad is running.
`first_shown_at`	`string` (date-time) or `null`	First delivery, RFC 3339 UTC (often date-only: see approximate_fields).
`last_shown_at`	`string` (date-time) or `null`	Last delivery, RFC 3339 UTC; null while active.
`type`	`string`	Creative shape. New values may be added; treat unknown values as other. One of `image`, `video`, `carousel`, `text`, `dynamic`, `other`
`publisher_platforms`	`string[]`	Where it ran, lowercase IDs (facebook, instagram, messenger, audience_network, youtube, …); [] if not disclosed.
`creatives`	`object[]`	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.
`creatives[].title`	`string` or `null`	Headline.
`creatives[].body`	`string` or `null`	Primary text.
`creatives[].link_url`	`string` (uri) or `null`	Destination URL.
`creatives[].link_description`	`string` or `null`	Link description text.
`creatives[].cta_text`	`string` or `null`	Call-to-action label (e.g. Shop now).
`creatives[].media`	`object[]`	Images and videos of this creative; [] if none.
`creatives[].media[].type`	`string`	Kind of file. New values may be added; treat unknown values as other. One of `image`, `video`, `audio`, `gif`
`creatives[].media[].url`	`string` (uri) or `null`	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.
`creatives[].media[].expires_at`	`string` (date-time) or `null`	When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire.
`creatives[].media[].thumbnail_url`	`string` (uri) or `null`	Poster or preview image URL.
`creatives[].media[].width`	`integer` or `null`	Width in pixels.
`creatives[].media[].height`	`integer` or `null`	Height in pixels.
`creatives[].media[].duration_ms`	`integer` or `null`	Duration in milliseconds (video and audio only).
`creatives[].media[].alt_text`	`string` or `null`	Accessibility text provided by the author or platform.
`languages`	`string[]`	BCP-47 languages of the ad; [] if not disclosed.
`country_codes`	`string[]`	ISO 3166-1 alpha-2 countries where it was shown; [] if not disclosed.
`is_political`	`boolean` or `null`	Categorized as a political or social-issue ad; false when the library files it under another category, null when it shows none.
`impressions`	`object` or `null`	Impressions or times shown range; null when not disclosed.
`impressions.lower_bound`	`integer`	Inclusive lower bound.
`impressions.upper_bound`	`integer` or `null`	Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.
`reach`	`object` or `null`	Unique users reached range; null when not disclosed.
`reach.lower_bound`	`integer`	Inclusive lower bound.
`reach.upper_bound`	`integer` or `null`	Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.
`audience_size`	`object` or `null`	Estimated target audience size range; null when not disclosed.
`audience_size.lower_bound`	`integer`	Inclusive lower bound.
`audience_size.upper_bound`	`integer` or `null`	Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact.
`spend`	`object` or `null`	Spend range; null when not disclosed.
`spend.lower_bound`	`integer`	Inclusive lower bound, in whole units of currency.
`spend.upper_bound`	`integer` or `null`	Inclusive upper bound in whole units of currency; null when open-ended.
`spend.currency`	`string`	ISO 4217 currency code, uppercase (USD).
`platform_specific`	`object`	Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.
`approximate_fields`	`string[]`	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_fields`	`string[]`	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.

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.

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.	Check the URL or ID; do not retry.

not_found (see error codes).