# Ad

Schemas

A public ad library entry: advertiser, creatives, run dates, placements and, where disclosed, reach and spend ranges.

## Endpoints

1 endpoint returns ads on Facebook.

- [GETFacebook Ad Library Search API`/v1/facebook/search_ads`](https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md)

## Schema

Every endpoint above returns an array of these objects as `data`, with a [`page`](https://staging-fly.socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://staging-fly.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. |
| `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://staging-fly.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. | Check the URL or ID; do not retry. |

---

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