Schema preview Draft
Ad schema (draft)
A public ad library entry: advertiser, creatives, run dates, placements and, where disclosed, reach and spend ranges.
Draft: not yet available. No endpoint returns ads yet. This schema may change before the first endpoint ships; don't build against it.
Draft schema
When ad endpoints ship, they will return objects shaped like this as data, next to the standard meta, the same on every platform.
| 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[] | Creative versions of the ad; [] 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. Often signed and expiring within hours. |
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. |
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). |
approximate_fields | string[] | JSON paths of values that are rounded, date-only or parsed from display text; [] when all exact. |
Item errors
Planned item-level errors, besides the request-level errors:
| 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. |