# Ad

Schemas

Public ad library entries with their advertiser, creatives, run dates, placements and, where disclosed, reach and spend ranges.

## Endpoints

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

- [GETFacebook Ad Library Ad API`/v1/facebook/ad`](https://socialtap.dev/docs/reference/facebook/ad/index.md)
- [GETFacebook Ad Library Advertiser Ads API`/v1/facebook/ads`](https://socialtap.dev/docs/reference/facebook/ads/index.md)
- [GETFacebook Ad Library Search API`/v1/facebook/search_ads`](https://socialtap.dev/docs/reference/facebook/search_ads/index.md)
- [GETGoogle Ads Transparency Center Ad API`/v1/google/ad`](https://socialtap.dev/docs/reference/google/ad/index.md)
- [GETGoogle Ads Transparency Center Advertiser Ads API`/v1/google/ads`](https://socialtap.dev/docs/reference/google/ads/index.md)
- [GETGoogle Ads Transparency Center Ads by Website API`/v1/google/search_ads`](https://socialtap.dev/docs/reference/google/search_ads/index.md)
- [GETLinkedIn Ad Library Ad API`/v1/linkedin/ad`](https://socialtap.dev/docs/reference/linkedin/ad/index.md)
- [GETLinkedIn Ad Library Search API`/v1/linkedin/search_ads`](https://socialtap.dev/docs/reference/linkedin/search_ads/index.md)
- [GETTikTok Ad Library Ad API`/v1/tiktok/ad`](https://socialtap.dev/docs/reference/tiktok/ad/index.md)
- [GETTikTok Ad Library Search API`/v1/tiktok/search_ads`](https://socialtap.dev/docs/reference/tiktok/search_ads/index.md)
- [GETTikTok Top Ads API`/v1/tiktok/top_ads`](https://socialtap.dev/docs/reference/tiktok/top_ads/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#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.<br>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.<br>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. |
| `platform_specific.tiktok` | `object` or `null` | A TikTok ad's own fields. |
| `platform_specific.tiktok.is_removed` | `boolean` or `null` | TikTok took the ad down (its rules or local law), in some or all regions. |
| `platform_specific.tiktok.removal_reasons` | `string[]` | TikTok's reasons for the takedown; \[\] when none (in unknown_fields when not shown). |
| `platform_specific.tiktok.category` | `string` or `null` | The ad's topic as TikTok files it (Apps, Food & Beverage). |
| `platform_specific.tiktok.objective` | `string` or `null` | The campaign objective (Reach, Traffic). |
| `platform_specific.tiktok.removal_country_codes` | `string[]` | Countries where TikTok took the ad down (ISO 3166-1 alpha-2); \[\] when it was not taken down (in unknown_fields when not shown). |
| `platform_specific.tiktok.targeting` | `object` or `null` | Whom the advertiser targeted and whom the ad reached, per country; null when not shown. |
| `platform_specific.tiktok.targeting.countries` | `object[]` | Per country it ran in: the ages and genders targeted and the unique users reached. |
| `platform_specific.tiktok.targeting.countries[].country_code` | `string` | ISO 3166-1 alpha-2 country code. |
| `platform_specific.tiktok.targeting.countries[].reach` | `object` or `null` | Unique users the ad reached there (rounded: approximate_fields); null when not shown. |
| `platform_specific.tiktok.targeting.countries[].reach.lower_bound` | `integer` | Inclusive lower bound. |
| `platform_specific.tiktok.targeting.countries[].reach.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `platform_specific.tiktok.targeting.countries[].age_ranges` | `string[]` | Age ranges targeted (13-17, 18-24, 25-34, 35-44, 45-54, 55+); \[\] when not shown. |
| `platform_specific.tiktok.targeting.countries[].genders` | `string[]` | Genders targeted (female, male, unknown); \[\] when not shown. |
| `platform_specific.tiktok.targeting.countries[].breakdown` | `object[]` | Unique users reached there by age range and gender, the segments TikTok shows a number for; \[\] when none. |
| `platform_specific.tiktok.targeting.countries[].breakdown[].age_range` | `string` | Age range (18-24, 55+). |
| `platform_specific.tiktok.targeting.countries[].breakdown[].gender` | `string` | female, male or unknown. |
| `platform_specific.tiktok.targeting.countries[].breakdown[].reach` | `object` | Unique users reached (rounded: approximate_fields). |
| `platform_specific.tiktok.targeting.countries[].breakdown[].reach.lower_bound` | `integer` | Inclusive lower bound. |
| `platform_specific.tiktok.targeting.countries[].breakdown[].reach.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `platform_specific.tiktok.targeting.interests` | `string[]` | Interest categories targeted; \[\] when none. |
| `platform_specific.tiktok.targeting.video_interactions` | `string[]` | Video interaction categories targeted; \[\] when none. |
| `platform_specific.tiktok.targeting.creator_interactions` | `string[]` | Creator interaction categories targeted; \[\] when none. |
| `platform_specific.tiktok.targeting.provinces` | `string[]` | Provinces or states targeted within the countries; \[\] when none. |
| `platform_specific.tiktok.targeting.cities` | `string[]` | Cities targeted; \[\] when none. |
| `platform_specific.tiktok.targeting.device_models` | `string[]` | Device models targeted; \[\] when any. |
| `platform_specific.tiktok.targeting.operating_systems` | `string[]` | Operating systems targeted; \[\] when any. |
| `platform_specific.tiktok.targeting.is_custom_audience` | `boolean` or `null` | The advertiser targeted a custom audience (its own customer list or a lookalike). |
| `platform_specific.tiktok.targeting.is_audience_excluded` | `boolean` or `null` | The advertiser excluded a custom audience. |
| `platform_specific.tiktok.targeting.is_high_spending_power` | `boolean` or `null` | Targeted at users TikTok rates as high spenders. |
| `platform_specific.tiktok.advertiser_business_id` | `string` or `null` | The advertiser's TikTok business ID (search_ads advertiser_id). |
| `platform_specific.tiktok.advertiser_registry_location` | `string` or `null` | Where the advertiser is registered (Italy). |
| `platform_specific.tiktok.rank` | `integer` or `null` | Place on Creative Center's Top Ads board, 1 first; null off the board. |
| `platform_specific.tiktok.like_count` | `integer` or `null` | Likes the ad drew, as Creative Center counts them; null off the board. |
| `platform_specific.tiktok.ctr_top_percent` | `number` or `null` | Click-through rate rank: the ad is in the top this many percent of ads (4 = top 4%); null off the board. |
| `platform_specific.tiktok.budget` | `string` or `null` | Creative Center's budget level; null off the board. New values may be added; treat unknown values as other.<br>One of `low`, `medium`, `high` |
| `platform_specific.google` | `object` or `null` | A Google ad's own fields. |
| `platform_specific.google.days_shown` | `integer` or `null` | Days the ad was shown (the center's "Ran for"); null when not shown. |
| `platform_specific.google.topic` | `string` or `null` | The ad's topic as Google labels it (Sports & Fitness); null when not shown. |
| `platform_specific.google.product_category` | `string` or `null` | The product category Google files a Shopping ad under (Apparel & Accessories); null otherwise. |
| `platform_specific.google.is_synthetic` | `boolean` or `null` | The advertiser disclosed synthetic (digitally altered or generated) content, as the ad's page labels it; false when it shows no such label. |
| `platform_specific.google.regions` | `object[]` | Per country it was shown in: when, how often and on which Google services; \[\] when not shown (in unknown_fields). |
| `platform_specific.google.regions[].country_code` | `string` | ISO 3166-1 alpha-2 country code. |
| `platform_specific.google.regions[].first_shown_at` | `string` (date-time) or `null` | First day shown there, RFC 3339 UTC (date-only: approximate_fields); null when not shown. |
| `platform_specific.google.regions[].last_shown_at` | `string` (date-time) or `null` | Last day shown there, RFC 3339 UTC (date-only: approximate_fields); null when not shown. |
| `platform_specific.google.regions[].impressions` | `object` or `null` | Times shown there, Google's range; null when not disclosed. |
| `platform_specific.google.regions[].impressions.lower_bound` | `integer` | Inclusive lower bound. |
| `platform_specific.google.regions[].impressions.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `platform_specific.google.regions[].services` | `object[]` | Times shown there on each Google service; \[\] when not disclosed. |
| `platform_specific.google.regions[].services[].service` | `string` | The Google service. New values may be added; treat unknown values as other.<br>One of `google_search`, `google_maps`, `google_play`, `google_shopping`, `youtube`, `other` |
| `platform_specific.google.regions[].services[].impressions` | `object` or `null` | Times shown on it, Google's range (a lower bound of 0 when Google shows only "under" an upper bound). |
| `platform_specific.google.regions[].services[].impressions.lower_bound` | `integer` | Inclusive lower bound. |
| `platform_specific.google.regions[].services[].impressions.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `platform_specific.google.targeting` | `object` or `null` | Whom the advertiser selected; null when not disclosed. |
| `platform_specific.google.targeting.age_ranges` | `string[]` | Age ranges included (18-24, 25-34, 35-44, 45-54, 55-64, 65+, unknown); \[\] when none. |
| `platform_specific.google.targeting.excluded_age_ranges` | `string[]` | Age ranges excluded; \[\] when none. |
| `platform_specific.google.targeting.genders` | `string[]` | Genders included (male, female, unknown); \[\] when none. |
| `platform_specific.google.targeting.excluded_genders` | `string[]` | Genders excluded; \[\] when none. |
| `platform_specific.google.targeting.locations` | `object[]` | Locations included; \[\] when none. |
| `platform_specific.google.targeting.locations[].criterion_id` | `string` | Google Ads geo target criterion ID (2840 is the United States). |
| `platform_specific.google.targeting.locations[].name` | `string` or `null` | The location's name (California); null when Google did not resolve it. |
| `platform_specific.google.targeting.locations[].full_name` | `string` or `null` | The name with the regions it lies in (California, United States); null when not resolved. |
| `platform_specific.google.targeting.locations[].country_code` | `string` or `null` | ISO 3166-1 alpha-2 code of its country; null when not resolved. |
| `platform_specific.google.targeting.excluded_locations` | `object[]` | Locations excluded; \[\] when none. |
| `platform_specific.google.targeting.excluded_locations[].criterion_id` | `string` | Google Ads geo target criterion ID (2840 is the United States). |
| `platform_specific.google.targeting.excluded_locations[].name` | `string` or `null` | The location's name (California); null when Google did not resolve it. |
| `platform_specific.google.targeting.excluded_locations[].full_name` | `string` or `null` | The name with the regions it lies in (California, United States); null when not resolved. |
| `platform_specific.google.targeting.excluded_locations[].country_code` | `string` or `null` | ISO 3166-1 alpha-2 code of its country; null when not resolved. |
| `platform_specific.google.targeting.criteria` | `object[]` | The kinds of criteria the advertiser included or excluded (the EU disclosure); \[\] when not disclosed. |
| `platform_specific.google.targeting.criteria[].category` | `string` | The kind of criteria. New values may be added; treat unknown values as other.<br>One of `demographics`, `locations`, `contextual`, `topics_of_interest`, `customer_lists` |
| `platform_specific.google.targeting.criteria[].is_included` | `boolean` | Criteria of this kind were included in the audience. |
| `platform_specific.google.targeting.criteria[].is_excluded` | `boolean` | Criteria of this kind were excluded from the audience. |
| `platform_specific.facebook` | `object` or `null` | A Meta Ad Library ad's own fields. |
| `platform_specific.facebook.cta_type` | `string` or `null` | The call to action's type (shop_now, learn_more), whatever language cta_text is in; null when the ad has none. |
| `platform_specific.facebook.link_caption` | `string` or `null` | The link caption shown under the creative (usually the destination's domain); null when none. |
| `platform_specific.facebook.special_ad_categories` | `string[]` | Meta's special ad categories the ad is filed under (political, housing, employment, credit); \[\] for an ordinary ad. |
| `platform_specific.facebook.collation_id` | `string` or `null` | The group of ads that share this creative and text; null when not shown. |
| `platform_specific.facebook.collation_count` | `integer` or `null` | How many ads share this creative and text; null when not shown. |
| `platform_specific.facebook.partner` | `object` or `null` | The creator whose post a branded content ad promotes for the advertiser; null for other ads. |
| `platform_specific.facebook.partner.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `platform_specific.facebook.partner.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `platform_specific.facebook.partner.display_name` | `string` or `null` | Display name shown on the profile. |
| `platform_specific.facebook.partner.url` | `string` (uri) or `null` | Canonical profile URL. |
| `platform_specific.facebook.partner.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `platform_specific.facebook.partner.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `platform_specific.facebook.advertiser_like_count` | `integer` or `null` | The advertiser's page likes; null when not shown. |
| `platform_specific.facebook.advertiser_categories` | `string[]` | The advertiser page's categories (Wine/spirits); \[\] when not shown (in unknown_fields when not shown). |
| `platform_specific.facebook.is_advertiser_deleted` | `boolean` or `null` | The advertiser's page has since been deleted; null when not shown. |
| `platform_specific.facebook.advertiser_instagram` | `object` or `null` | The advertiser's Instagram account, when Meta links one; null otherwise or outside the ad's details. |
| `platform_specific.facebook.advertiser_instagram.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `platform_specific.facebook.advertiser_instagram.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `platform_specific.facebook.advertiser_instagram.display_name` | `string` or `null` | Display name shown on the profile. |
| `platform_specific.facebook.advertiser_instagram.url` | `string` (uri) or `null` | Canonical profile URL. |
| `platform_specific.facebook.advertiser_instagram.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `platform_specific.facebook.advertiser_instagram.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `platform_specific.facebook.advertiser_instagram_follower_count` | `integer` or `null` | Followers of the advertiser's Instagram account; null when not shown. |
| `platform_specific.facebook.beneficiary` | `string` or `null` | Whom the ad benefits, as disclosed for ads shown in the EU; null when not disclosed. |
| `platform_specific.facebook.is_synthetic` | `boolean` or `null` | The advertiser disclosed digitally created or altered media (an AI disclosure); null when not shown. |
| `platform_specific.facebook.is_removed` | `boolean` or `null` | Meta took the ad down for breaking its standards; null when not shown. |
| `platform_specific.facebook.removal_reasons` | `string[]` | Meta's reasons for taking it down; \[\] when none (in unknown_fields when not shown). |
| `platform_specific.facebook.targeting` | `object[]` | 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). |
| `platform_specific.facebook.targeting[].region` | `string` | The disclosing region. New values may be added.<br>One of `eu`, `uk` |
| `platform_specific.facebook.targeting[].reach` | `integer` or `null` | Unique accounts the ad reached in the region; null when not shown. |
| `platform_specific.facebook.targeting[].genders` | `string[]` | Genders targeted (female, male); \[\] when all. |
| `platform_specific.facebook.targeting[].age_min` | `integer` or `null` | Youngest age targeted; null when not shown. |
| `platform_specific.facebook.targeting[].age_max` | `integer` or `null` | Oldest age targeted (65 means 65 and over); null when not shown. |
| `platform_specific.facebook.targeting[].locations` | `object[]` | Places the advertiser targeted or excluded; \[\] when not shown. |
| `platform_specific.facebook.targeting[].locations[].name` | `string` | The place as Meta names it (United Kingdom, Berlin). |
| `platform_specific.facebook.targeting[].locations[].type` | `string` or `null` | The kind of place (countries, regions, cities); null when not shown. |
| `platform_specific.facebook.targeting[].locations[].is_excluded` | `boolean` | The advertiser excluded the place rather than targeting it. |
| `platform_specific.facebook.targeting[].reach_by_country` | `object[]` | Unique accounts reached per country, by age range and gender; \[\] when not shown. |
| `platform_specific.facebook.targeting[].reach_by_country[].country_code` | `string` | ISO 3166-1 alpha-2 country code. |
| `platform_specific.facebook.targeting[].reach_by_country[].ages` | `object[]` | Unique accounts reached there per age range. |
| `platform_specific.facebook.targeting[].reach_by_country[].ages[].age_range` | `string` | The age range (18-24, 65+). |
| `platform_specific.facebook.targeting[].reach_by_country[].ages[].male` | `integer` or `null` | Men reached; null when not shown. |
| `platform_specific.facebook.targeting[].reach_by_country[].ages[].female` | `integer` or `null` | Women reached; null when not shown. |
| `platform_specific.facebook.targeting[].reach_by_country[].ages[].unknown` | `integer` or `null` | Accounts of unknown gender reached; null when not shown. |
| `platform_specific.facebook.impression_shares` | `object` or `null` | A political or social-issue ad's audience: its share of impressions by age and gender and by region; null for other ads. |
| `platform_specific.facebook.impression_shares.by_age_gender` | `object[]` | Share of impressions per age range, by gender (0 to 1). |
| `platform_specific.facebook.impression_shares.by_age_gender[].age_range` | `string` | The age range (18-24, 65+). |
| `platform_specific.facebook.impression_shares.by_age_gender[].male` | `number` or `null` | Share among men (0 to 1); null when not shown. |
| `platform_specific.facebook.impression_shares.by_age_gender[].female` | `number` or `null` | Share among women (0 to 1); null when not shown. |
| `platform_specific.facebook.impression_shares.by_age_gender[].unknown` | `number` or `null` | Share among people of unknown gender (0 to 1); null when not shown. |
| `platform_specific.facebook.impression_shares.by_region` | `object[]` | Share of impressions per region (0 to 1). |
| `platform_specific.facebook.impression_shares.by_region[].region` | `string` | The region as Meta names it (California). |
| `platform_specific.facebook.impression_shares.by_region[].share` | `number` or `null` | Its share (0 to 1); null when not shown. |
| `platform_specific.linkedin` | `object` or `null` | A LinkedIn Ad Library ad's own fields. |
| `platform_specific.linkedin.creative_type` | `string` or `null` | 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. |
| `platform_specific.linkedin.format` | `string` or `null` | The ad's format as the library labels it (Single Image Ad, Message Ad, Company Discovery Ad, …); null when not shown. |
| `platform_specific.linkedin.is_deleted` | `boolean` or `null` | The library says the ad was deleted; false when it shows no such notice. |
| `platform_specific.linkedin.poster` | `object` or `null` | The account the ad appears from: the advertiser, or a member whose post it promotes; null when the preview names none. |
| `platform_specific.linkedin.poster.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `platform_specific.linkedin.poster.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `platform_specific.linkedin.poster.display_name` | `string` or `null` | Display name shown on the profile. |
| `platform_specific.linkedin.poster.url` | `string` (uri) or `null` | Canonical profile URL. |
| `platform_specific.linkedin.poster.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `platform_specific.linkedin.poster.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `platform_specific.linkedin.poster_title` | `string` or `null` | The line under the poster's name (a member's headline); null when none. |
| `platform_specific.linkedin.impressions_by_country` | `object[]` | Each country's share of the ad's impressions, as the library lists them; \[\] when not shown (in unknown_fields). |
| `platform_specific.linkedin.impressions_by_country[].country` | `string` or `null` | The country's name, as the library writes it. |
| `platform_specific.linkedin.impressions_by_country[].country_code` | `string` or `null` | ISO 3166-1 alpha-2 country code; null when the name is none the library's country list has. |
| `platform_specific.linkedin.impressions_by_country[].share_percent` | `integer` or `null` | Share of the ad's impressions, a whole percent as the library rounds it; null when under one percent. |
| `platform_specific.linkedin.impressions_by_country[].is_under_one_percent` | `boolean` or `null` | The library writes the share as less than one percent. |
| `platform_specific.linkedin.targeting` | `object` or `null` | Whom the advertiser selected; null when not disclosed. |
| `platform_specific.linkedin.targeting.languages` | `object` or `null` | The profile languages targeted or excluded; null when not shown. |
| `platform_specific.linkedin.targeting.languages.included` | `string[]` | Targeted; \[\] when none are listed. |
| `platform_specific.linkedin.targeting.languages.excluded` | `string[]` | Excluded; \[\] when none are listed. |
| `platform_specific.linkedin.targeting.locations` | `object` or `null` | The locations targeted or excluded, in the language of the advertiser's account; null when not shown. |
| `platform_specific.linkedin.targeting.locations.included` | `string[]` | Targeted; \[\] when none are listed. |
| `platform_specific.linkedin.targeting.locations.excluded` | `string[]` | Excluded; \[\] when none are listed. |
| `platform_specific.linkedin.targeting.audience` | `object` or `null` | Audience criteria; null when not shown. |
| `platform_specific.linkedin.targeting.audience.is_targeted` | `boolean` or `null` | The advertiser targeted by this criterion. |
| `platform_specific.linkedin.targeting.audience.is_excluded` | `boolean` or `null` | The advertiser excluded by this criterion. |
| `platform_specific.linkedin.targeting.demographic` | `object` or `null` | Demographic criteria; null when not shown. |
| `platform_specific.linkedin.targeting.demographic.is_targeted` | `boolean` or `null` | The advertiser targeted by this criterion. |
| `platform_specific.linkedin.targeting.demographic.is_excluded` | `boolean` or `null` | The advertiser excluded by this criterion. |
| `platform_specific.linkedin.targeting.company` | `object` or `null` | Company criteria; null when not shown. |
| `platform_specific.linkedin.targeting.company.is_targeted` | `boolean` or `null` | The advertiser targeted by this criterion. |
| `platform_specific.linkedin.targeting.company.is_excluded` | `boolean` or `null` | The advertiser excluded by this criterion. |
| `platform_specific.linkedin.targeting.education` | `object` or `null` | Education criteria; null when not shown. |
| `platform_specific.linkedin.targeting.education.is_targeted` | `boolean` or `null` | The advertiser targeted by this criterion. |
| `platform_specific.linkedin.targeting.education.is_excluded` | `boolean` or `null` | The advertiser excluded by this criterion. |
| `platform_specific.linkedin.targeting.job` | `object` or `null` | Job criteria; null when not shown. |
| `platform_specific.linkedin.targeting.job.is_targeted` | `boolean` or `null` | The advertiser targeted by this criterion. |
| `platform_specific.linkedin.targeting.job.is_excluded` | `boolean` or `null` | The advertiser excluded by this criterion. |
| `platform_specific.linkedin.targeting.member_interests` | `object` or `null` | Member interests and traits criteria; null when not shown. |
| `platform_specific.linkedin.targeting.member_interests.is_targeted` | `boolean` or `null` | The advertiser targeted by this criterion. |
| `platform_specific.linkedin.targeting.member_interests.is_excluded` | `boolean` or `null` | The advertiser excluded by this criterion. |
| `platform_specific.linkedin.message` | `object` or `null` | A message ad's sender and buttons; null on every other format. |
| `platform_specific.linkedin.message.sender_name` | `string` or `null` | The person the message is sent as; null when not shown. |
| `platform_specific.linkedin.message.sender_avatar_url` | `string` (uri) or `null` | The sender's picture; null when not shown. |
| `platform_specific.linkedin.message.buttons` | `string[]` | The message's buttons, in order; \[\] when none. |
| `platform_specific.linkedin.job` | `object` or `null` | The job a job ad promotes; null on every other format. |
| `platform_specific.linkedin.job.company` | `string` or `null` | The company the job is at; null when not shown. |
| `platform_specific.linkedin.job.location` | `string` or `null` | The job's location, as written; null when not shown. |
| `platform_specific.linkedin.event` | `object` or `null` | The event an event ad promotes; null on every other format. |
| `platform_specific.linkedin.event.organizer` | `string` or `null` | Who hosts the event; null when not shown. |
| `platform_specific.linkedin.event.location` | `string` or `null` | Where it happens, as written (Online); null when not shown. |
| `platform_specific.linkedin.event.starts_at` | `string` (date-time) or `null` | When it starts, RFC 3339 UTC; null when not shown. |
| `platform_specific.linkedin.event.ends_at` | `string` (date-time) or `null` | When it ends, RFC 3339 UTC; null when not shown. |
| `platform_specific.linkedin.document` | `object` or `null` | The document a document ad shows; null on every other format. |
| `platform_specific.linkedin.document.title` | `string` or `null` | The document's title; null when not shown. |
| `platform_specific.linkedin.document.page_count` | `integer` or `null` | How many pages it has; null when not shown. |
| `platform_specific.linkedin.newsletter` | `string` or `null` | The newsletter an article ad's article belongs to; null when none. |
| `platform_specific.linkedin.company` | `object` or `null` | The company a company discovery ad presents; null on every other format. |
| `platform_specific.linkedin.company.size` | `string` or `null` | The company's size as the card writes it (10,001+ employees); null when not shown. |
| `platform_specific.linkedin.company.location` | `string` or `null` | Where the company is, as the card writes it; null when not shown. |
| `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. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) 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. |

---

[HTML version](https://socialtap.dev/resources/ad/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)