{ "openapi": "3.1.0", "info": { "title": "Facebook Ad Library API", "version": "1.0.0", "description": "Public Facebook and Instagram ads, creative files, advertisers and EU transparency data exposed through FetchLayer." }, "servers": [ { "url": "https://api.fetchlayer.dev/facebook-ad-library" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search-ads": { "post": { "operationId": "search-ads", "tags": [ "Ads" ], "summary": "Search ads by keyword", "description": "Search the Facebook Ad Library for public Facebook and Instagram ads matching a keyword or phrase. Filter by country, active status, media type, publisher platform, ad language and impression date, and page through the results with a cursor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Keyword or phrase to search the Ad Library for." }, "searchType": { "type": "string", "description": "keyword_unordered or keyword_exact_phrase.", "example": "keyword_unordered" }, "pageIds": { "type": "array", "items": { "type": "string" }, "description": "Restrict the keyword search to these advertiser page ids (max 50)." }, "country": { "type": "string", "description": "Two-letter country code, or ALL.", "example": "ALL" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Several countries at once (max 20). Overrides country." }, "activeStatus": { "type": "string", "description": "active, inactive, or all.", "example": "active" }, "adType": { "type": "string", "description": "ALL or POLITICAL_AND_ISSUE_ADS.", "example": "ALL" }, "mediaType": { "type": "string", "description": "all, image, meme, image_and_meme, video, or none." }, "publisherPlatforms": { "type": "array", "items": { "type": "string" }, "description": "FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, WHATSAPP, THREADS, OCULUS, UNKNOWN." }, "contentLanguages": { "type": "array", "items": { "type": "string" }, "description": "Two-letter ad language codes, for example en or es." }, "bylines": { "type": "array", "items": { "type": "string" }, "description": "Political-ad disclaimers (\"paid for by\")." }, "startDateFrom": { "type": "string", "description": "Only ads whose impressions start on or after this YYYY-MM-DD date." }, "startDateTo": { "type": "string", "description": "Only ads whose impressions start on or before this YYYY-MM-DD date." }, "isTargetedCountry": { "type": "boolean", "description": "Restrict to ads targeting the country rather than merely reaching it." }, "limit": { "type": "number", "description": "Maximum ads returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "sortBy": { "type": "string", "description": "start_date, end_date, total_active_time, or none." }, "sortDirection": { "type": "string", "description": "asc or desc." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "project management software", "country": "US", "activeStatus": "active", "mediaType": "video", "limit": 30 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "additionalProperties": true, "description": "The filters this search actually ran with, after defaults were applied." }, "ads": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "adArchiveId": { "type": "string", "description": "Ad Library archive id — the handle for ad-detail and ad-media." }, "adLibraryUrl": { "type": "string", "description": "Public Ad Library permalink for this ad." }, "isActive": { "type": "boolean", "description": "Whether the ad was still running when it was scraped." }, "startDate": { "type": "string", "description": "First day the ad served impressions." }, "totalActiveTimeSeconds": { "type": "number", "description": "How long the ad has been live — the usual proxy for what is working." }, "publisherPlatforms": { "type": "array", "items": { "type": "string" }, "description": "Surfaces the ad ran on (Facebook, Instagram, Messenger, Threads…)." }, "advertiser": { "type": "object", "additionalProperties": true, "description": "Page id, name, URL, categories, like count, and political byline." }, "creative": { "type": "object", "additionalProperties": true, "description": "Title, body, caption, link, CTA, display format, plus videos, images and carousel cards." }, "transparency": { "type": "object", "additionalProperties": true, "description": "Spend, currency, impressions and reach bands for political and issue ads." } } }, "description": "The matching ads, newest data first unless sortBy says otherwise." }, "adCount": { "type": "number", "description": "Number of ads in this response." }, "pagesScraped": { "type": "number", "description": "Pages actually walked. Each page counts as one request against your plan." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue from where this response stopped." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "adCount": 30, "pagesScraped": 1, "hasNextPage": true, "ads": [ { "adArchiveId": "1234567890123456", "isActive": true, "startDate": "2026-07-14", "publisherPlatforms": [ "FACEBOOK", "INSTAGRAM" ], "advertiser": { "pageId": "987654321", "pageName": "Acme Software" }, "creative": { "title": "Ship faster with Acme", "ctaText": "Sign Up", "linkUrl": "https://example.com" } } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/advertiser-ads": { "post": { "operationId": "advertiser-ads", "tags": [ "Ads" ], "summary": "Get every ad one advertiser runs", "description": "Return every ad a single advertiser is running, from a page id, an Ad Library advertiser URL, or a facebook.com page URL. Accepts the same filters as a keyword search, plus an optional query to narrow the results within that advertiser's ads.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser": { "type": "string", "description": "Advertiser page id, Ad Library advertiser URL, or facebook.com page URL." }, "query": { "type": "string", "description": "Optional keyword to filter within the advertiser's ads." }, "country": { "type": "string", "description": "Two-letter country code, or ALL.", "example": "ALL" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Several countries at once (max 20). Overrides country." }, "activeStatus": { "type": "string", "description": "active, inactive, or all.", "example": "active" }, "adType": { "type": "string", "description": "ALL or POLITICAL_AND_ISSUE_ADS.", "example": "ALL" }, "mediaType": { "type": "string", "description": "all, image, meme, image_and_meme, video, or none." }, "publisherPlatforms": { "type": "array", "items": { "type": "string" }, "description": "FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, WHATSAPP, THREADS, OCULUS, UNKNOWN." }, "contentLanguages": { "type": "array", "items": { "type": "string" }, "description": "Two-letter ad language codes, for example en or es." }, "bylines": { "type": "array", "items": { "type": "string" }, "description": "Political-ad disclaimers (\"paid for by\")." }, "startDateFrom": { "type": "string", "description": "Only ads whose impressions start on or after this YYYY-MM-DD date." }, "startDateTo": { "type": "string", "description": "Only ads whose impressions start on or before this YYYY-MM-DD date." }, "isTargetedCountry": { "type": "boolean", "description": "Restrict to ads targeting the country rather than merely reaching it." }, "limit": { "type": "number", "description": "Maximum ads returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "sortBy": { "type": "string", "description": "start_date, end_date, total_active_time, or none." }, "sortDirection": { "type": "string", "description": "asc or desc." } }, "additionalProperties": false, "required": [ "advertiser" ] }, "examples": { "default": { "value": { "advertiser": "https://www.facebook.com/ads/library/?view_all_page_id=987654321", "activeStatus": "active", "pages": 3 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageId": { "type": "string", "description": "The resolved advertiser page id." }, "pageName": { "type": "string", "description": "The advertiser’s page name." }, "ads": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "adArchiveId": { "type": "string", "description": "Ad Library archive id — the handle for ad-detail and ad-media." }, "adLibraryUrl": { "type": "string", "description": "Public Ad Library permalink for this ad." }, "isActive": { "type": "boolean", "description": "Whether the ad was still running when it was scraped." }, "startDate": { "type": "string", "description": "First day the ad served impressions." }, "totalActiveTimeSeconds": { "type": "number", "description": "How long the ad has been live — the usual proxy for what is working." }, "publisherPlatforms": { "type": "array", "items": { "type": "string" }, "description": "Surfaces the ad ran on (Facebook, Instagram, Messenger, Threads…)." }, "advertiser": { "type": "object", "additionalProperties": true, "description": "Page id, name, URL, categories, like count, and political byline." }, "creative": { "type": "object", "additionalProperties": true, "description": "Title, body, caption, link, CTA, display format, plus videos, images and carousel cards." }, "transparency": { "type": "object", "additionalProperties": true, "description": "Spend, currency, impressions and reach bands for political and issue ads." } } }, "description": "The matching ads, newest data first unless sortBy says otherwise." }, "adCount": { "type": "number", "description": "Number of ads in this response." }, "pagesScraped": { "type": "number", "description": "Pages actually walked. Each page counts as one request against your plan." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue from where this response stopped." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "pageId": "987654321", "pageName": "Acme Software", "adCount": 84, "pagesScraped": 3, "hasNextPage": false, "ads": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/search-advertisers": { "post": { "operationId": "search-advertisers", "tags": [ "Advertisers" ], "summary": "Find advertisers by name", "description": "Look up advertisers by brand or page name. Returns the page id, ad count, page categories, follower count and Ad Library link for each match — use it to get the page id that an advertiser lookup needs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Advertiser or brand name to look up." }, "country": { "type": "string", "description": "Two-letter country code, or ALL.", "example": "ALL" }, "adType": { "type": "string", "description": "ALL or POLITICAL_AND_ISSUE_ADS.", "example": "ALL" }, "limit": { "type": "number", "description": "Maximum advertisers returned (max 500), or -1 for everything available.", "example": "30" } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "Acme Software", "country": "US", "limit": 10 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "advertisers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "pageId": { "type": "string", "description": "Page id — the handle for advertiser-ads and advertiser-profile." }, "pageName": { "type": "string", "description": "Public page name." }, "adCount": { "type": "number", "description": "How many ads the page is running." }, "pageCategories": { "type": "array", "items": { "type": "string" }, "description": "Categories the page lists itself under." }, "pageLikeCount": { "type": "number", "description": "Follower count on the page." } } }, "description": "Matching advertiser pages." }, "advertiserCount": { "type": "number", "description": "Number of advertisers in this response." }, "derivedFromAds": { "type": "boolean", "description": "Whether the matches were derived from ad results rather than a direct page search." } }, "additionalProperties": false }, "examples": { "default": { "value": { "advertiserCount": 2, "advertisers": [ { "pageId": "987654321", "pageName": "Acme Software", "adCount": 84, "pageLikeCount": 120400 } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/advertiser-profile": { "post": { "operationId": "advertiser-profile", "tags": [ "Advertisers" ], "summary": "Get an advertiser's profile", "description": "Read an advertiser's public Ad Library profile: page name and alias, category, verification status, follower count, linked Instagram account and follower count, about text, and — for political pages — spend broken down by disclaimer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser": { "type": "string", "description": "Advertiser page id, Ad Library advertiser URL, or facebook.com page URL." }, "country": { "type": "string", "description": "Two-letter country code, or ALL." } }, "additionalProperties": false, "required": [ "advertiser" ] }, "examples": { "default": { "value": { "advertiser": "987654321" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "additionalProperties": true, "description": "The advertiser’s public profile record.", "properties": { "pageId": { "type": "string", "description": "Page id." }, "pageName": { "type": "string", "description": "Public page name." }, "pageCategory": { "type": "string", "description": "Category the page lists itself under." }, "pageVerification": { "type": "string", "description": "Verification status of the page." }, "likes": { "type": "number", "description": "Follower count." }, "igUsername": { "type": "string", "description": "Linked Instagram handle, when the page has one." }, "igFollowers": { "type": "number", "description": "Follower count on the linked Instagram account." }, "isPoliticalPage": { "type": "boolean", "description": "Whether the page runs political or issue ads." }, "spendByDisclaimer": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Political spend grouped by \"paid for by\" disclaimer." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "profile": { "pageId": "987654321", "pageName": "Acme Software", "pageCategory": "Software company", "likes": 120400, "igUsername": "acmesoftware", "isPoliticalPage": false } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/ad-detail": { "post": { "operationId": "ad-detail", "tags": [ "Ads" ], "summary": "Get one ad in full", "description": "Read a single ad completely: full copy, call to action, destination link, display format, every other creative version running under the same ad group, the advertiser profile, and EU transparency data — total reach plus age, gender and location audience breakdowns.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ad": { "type": "string", "description": "Ad archive id, or an Ad Library URL containing one." }, "country": { "type": "string", "description": "Two-letter country code, or ALL." }, "includeVariations": { "type": "boolean", "description": "Also fetch every other creative version in the same ad group.", "example": "true" } }, "additionalProperties": false, "required": [ "ad" ] }, "examples": { "default": { "value": { "ad": "1234567890123456", "includeVariations": true } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "adArchiveId": { "type": "string", "description": "The resolved ad archive id." }, "ad": { "type": "object", "additionalProperties": true, "description": "The full ad record, including its creative." }, "advertiserProfile": { "type": "object", "additionalProperties": true, "description": "Profile of the page running the ad." }, "euTransparency": { "type": "object", "additionalProperties": true, "description": "Total reach and age, gender and location audience breakdowns, where Meta publishes them." }, "variations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every other creative version running under the same ad group." }, "variationCount": { "type": "number", "description": "How many creative versions the ad group carries." }, "violationTypes": { "type": "array", "items": { "type": "string" }, "description": "Policy violations Meta has recorded against the ad." } }, "additionalProperties": false }, "examples": { "default": { "value": { "adArchiveId": "1234567890123456", "variationCount": 4, "ad": { "creative": { "title": "Ship faster with Acme", "body": "Try Acme free for 14 days.", "ctaText": "Sign Up" } } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/ad-media": { "post": { "operationId": "ad-media", "tags": [ "Media" ], "summary": "Get an ad's videos and images", "description": "Resolve an ad's creative files into downloadable asset URLs — videos, images and thumbnails, at high quality or watermarked, across every creative variation. Optionally probe each asset to confirm it is still available and report its size and content type.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ad": { "type": "string", "description": "Ad archive id, or an Ad Library URL containing one." }, "country": { "type": "string", "description": "Two-letter country code, or ALL." }, "kinds": { "type": "array", "items": { "type": "string" }, "description": "video, image, and/or thumbnail.", "example": "all three" }, "preferHighQuality": { "type": "boolean", "description": "Pick HD video and original images.", "example": "true" }, "watermarked": { "type": "boolean", "description": "Prefer Facebook's watermarked copies." }, "includeVariations": { "type": "boolean", "description": "Include media from every creative version of the ad." }, "probe": { "type": "boolean", "description": "Confirm each asset is still downloadable and report its size and content type." } }, "additionalProperties": false, "required": [ "ad" ] }, "examples": { "default": { "value": { "ad": "1234567890123456", "kinds": [ "video", "image" ], "preferHighQuality": true, "probe": true } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "description": "video, image, or thumbnail." }, "url": { "type": "string", "description": "Original Facebook or Instagram CDN URL." }, "downloadUrl": { "type": "string", "description": "FetchLayer download URL — pass it to GET /media to stream the bytes." }, "quality": { "type": "string", "description": "Which rendition was picked." }, "contentType": { "type": "string", "description": "MIME type, when probed." }, "contentLength": { "type": "number", "description": "Size in bytes, when probed." } } }, "description": "The ad’s media assets." }, "assetCount": { "type": "number", "description": "Number of assets in this response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "assetCount": 2, "assets": [ { "kind": "video", "quality": "hd", "contentType": "video/mp4", "contentLength": 4182773, "url": "https://video.xx.fbcdn.net/..." } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/media": { "get": { "operationId": "media", "tags": [ "Media" ], "summary": "Download an ad media file", "description": "Stream an ad's actual video or image bytes, using a url taken from an asset returned by /ad-media. Only Facebook and Instagram CDN hosts are accepted. HTTP Range requests are supported, so video seeking works. This is a GET with query parameters, not a JSON POST, and it bills as one request.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Facebook or Instagram CDN media URL, as returned on an ad asset. Passed as a query parameter.", "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Content-Disposition filename to serve the file as (max 200 characters).", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "Standard HTTP Range request header, for example bytes=0-65535. Sent as a header, not a query parameter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse an Ad Library URL", "description": "Turn any Facebook Ad Library URL into the structured filters it encodes — whether it points at one ad, an advertiser, or a search, plus the country, status, media type, platform and date filters carried in its query string. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any Ad Library URL, to be parsed into structured filters." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=crm" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "What the URL points at: ad, advertiser, search, or unknown." }, "adArchiveId": { "type": "string", "description": "Present when kind is ad." }, "pageId": { "type": "string", "description": "Present when kind is advertiser." }, "query": { "type": "string", "description": "Present when kind is search." }, "country": { "type": "string", "description": "Country filter carried in the URL." }, "activeStatus": { "type": "string", "description": "Status filter carried in the URL." }, "publisherPlatforms": { "type": "array", "items": { "type": "string" }, "description": "Platform filters carried in the URL." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "search", "query": "crm", "country": "US", "activeStatus": "active", "publisherPlatforms": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }