# Ad Library ads by company > Every ad one advertiser is running (or ran) on Facebook and Instagram, from Meta's Ad Library. - **Request:** `GET https://api.lurkapi.com/v1/facebook/adLibrary/company/ads` - **Auth:** `x-api-key` header ([get a free key](https://lurkapi.com/login?next=/dashboard)) - **Cost:** 1 credit per call. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)). - **MCP tool:** `facebook_company_ads` on `https://api.lurkapi.com/mcp` - **Freshness:** responses are cached for up to 30 minutes - **Try it live:** https://lurkapi.com/docs/facebook/company-ads#try (no signup) - **Platform:** [Facebook](https://lurkapi.com/docs/facebook.md) (facebook.com/ads/library) - **Web page:** https://lurkapi.com/docs/facebook/company-ads ## When to use this Use it to study one competitor's creative, offers and landing pages. Pass `pageId` (exact) or `companyName` (we use the top match and return it as `page_id` and `page_name`). `status` defaults to all; pass `active` for ads running now. `pageId` comes from search companies (facebook_search_companies) or the `view_all_page_id` in an Ad Library URL. Returns 404 `not_found` if no page matches `companyName`. The list is under `results` (keyword search uses `searchResults`). **Pagination.** The first page returns up to 30 ads plus `searchResultsCount`. Pass `cursor` back (with the same filters) for the next page: cursor pages return up to 10 ads, which is Facebook's own page size, and `searchResultsCount` is null. `cursor` is null on the last page. ## Parameters All parameters go in the query string. | Name | Type | Required | Default | Allowed values | Description | Example | | --- | --- | --- | --- | --- | --- | --- | | `pageId` | string | no | | | The advertiser's Facebook page id, e.g. `15087023444` (Nike). Required unless you pass `companyName`. | `15087023444` | | `companyName` | string | no | | | Advertiser name, e.g. `Nike`. We use the top match from search companies. Ignored when `pageId` is set. | | | `country` | string | no | `ALL` | | Where the ad ran: a 2-letter ISO country code (US, GB, DE…) or ALL. One country per request. | | | `status` | string | no | `all` | `all`, `active`, `inactive` | Only ads that are running now (active), only stopped ads (inactive), or both (all). | `active` | | `media_type` | string | no | `all` | `all`, `image`, `video`, `meme`, `image_and_meme`, `none` | Creative format. `meme` is Facebook's name for image + text; `none` means text-only. | | | `ad_type` | string | no | `ALL` | `ALL`, `POLITICAL_AND_ISSUE_ADS`, `EMPLOYMENT_ADS`, `HOUSING_ADS`, `CREDIT_ADS` | Ad category. Political ads also carry spend and impressions ranges. | | | `language` | string | no | | | Language of the ad text as an ISO 639-1 code, e.g. `en` or `es`. | | | `sort_by` | string | no | `total_impressions` | `total_impressions`, `relevancy_monthly_grouped` | `total_impressions`: most-seen ads first. `relevancy_monthly_grouped`: most recent first. | | | `start_date` | string | no | | | Only ads shown on or after this date (YYYY-MM-DD). The ad itself may have launched earlier. | | | `end_date` | string | no | | | Only ads shown on or before this date (YYYY-MM-DD). | | | `cursor` | string | no | | | The `cursor` from the previous response, to get the next page. Keep every other param the same. | | | `trim` | boolean | no | `false` | `true`, `false` | `true` drops image and video URLs (inside `snapshot.cards` too) for a much smaller response. All text is kept. | | ## Example request Replace `YOUR_API_KEY` with your key, or set `LURKAPI_KEY` for the code. [Get a free key](https://lurkapi.com/login?next=/dashboard). curl: ```bash curl "https://api.lurkapi.com/v1/facebook/adLibrary/company/ads?pageId=15087023444&status=active" \ -H "x-api-key: YOUR_API_KEY" ``` JavaScript: ```js const params = new URLSearchParams({ pageId: "15087023444", status: "active", }); const res = await fetch(`https://api.lurkapi.com/v1/facebook/adLibrary/company/ads?${params}`, { headers: { "x-api-key": process.env.LURKAPI_KEY }, }); const data = await res.json(); if (!data.success) throw new Error(`${data.code}: ${data.error}`); console.log(data.results); ``` Python: ```python import os import requests res = requests.get( "https://api.lurkapi.com/v1/facebook/adLibrary/company/ads", params={ "pageId": "15087023444", "status": "active", }, headers={"x-api-key": os.environ["LURKAPI_KEY"]}, timeout=60, ) data = res.json() if not data["success"]: raise RuntimeError(f"{data['code']}: {data['error']}") print(data["results"]) ``` ## Example response A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in `…`. 200 OK (application/json): ```json { "success": true, "credits_remaining": 998, "credits_charged": 1, "page_id": "15087023444", "page_name": "Nike", "results": [ { "ad_archive_id": "1702938977100376", "ad_id": null, "categories": [ "UNKNOWN" ], "collation_count": null, "collation_id": null, "contains_digital_created_media": false, "contains_sensitive_content": false, "currency": "", "end_date": 1790751600, "end_date_string": null, "fev_info": null, "gated_type": "ELIGIBLE", "has_user_reported": false, "hide_data_status": "NONE", "impressions_with_index": { "impressions_text": null, "impressions_index": -1 }, "is_aaa_eligible": false, "is_active": true, "menu_items": [], "page_id": "15087023444", "page_is_deleted": false, "page_name": "Nike", "publisher_platform": [ "FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER" ], "reach_estimate": null, "regional_regulation_data": { "finserv": { "is_deemed_finserv": false, "is_limited_delivery": false }, "tw_anti_scam": { "is_limited_delivery": false } }, "report_count": null, "snapshot": { "additional_info": null, "branded_content": null, "brazil_tax_id": null, "byline": null, "caption": "itunes.apple.com", "cards": [ { "body": "Bring sports more fully into your day with the Nike App.", "caption": "itunes.apple.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "₱9,895", "link_url": "https://www.nike.com/ph/t/invincible-3-road-running-shoes-LL61DX/DR2660-001", "original_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/431631323_92872743202…", "resized_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/431631323_92872743202…", "title": "Nike Invincible 3 Women's Road Running Shoes", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Bring sports more fully into your day with the Nike App.", "caption": "itunes.apple.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "₱3,995", "link_url": "https://www.nike.com/ph/t/run-swift-3-road-running-shoes-2fHbzp/DR2698-002", "original_image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/431679131_94921416663…", "resized_image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/431679131_94921416663…", "title": "Nike Run Swift 3 Women's Road Running Shoes", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Bring sports more fully into your day with the Nike App.", "caption": "itunes.apple.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "₱5,039", "link_url": "https://www.nike.com/ph/t/cosmic-unity-3-basketball-shoes-hcwmW0/DV2757-100", "original_image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/431644642_73750860147…", "resized_image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/431644642_73750860147…", "title": "Cosmic Unity 3 Basketball Shoes", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Bring sports more fully into your day with the Nike App.", "caption": "itunes.apple.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "₱3,599", "link_url": "https://www.nike.com/ph/t/acg-polartec-wolf-tree-mid-rise-trousers-mVbQBn/CV0615-060", "original_image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/431748186_28931604736…", "resized_image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/431748186_28931604736…", "title": "Nike ACG Polartec ® 'Wolf Tree' Women's Mid-Rise Trousers", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Bring sports more fully into your day with the Nike App.", "caption": "itunes.apple.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "₱1,695", "link_url": "https://www.nike.com/ph/t/dri-fit-icon-basketball-jersey-4Z5f8P/DV9968-010", "original_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/431718739_34998891035…", "resized_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/431718739_34998891035…", "title": "Nike Dri-FIT Icon Men's Basketball Jersey", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Bring sports more fully into your day with the Nike App.", "caption": "itunes.apple.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "₱3,595", "link_url": "https://www.nike.com/ph/t/fc-barcelona-2023-24-stadium-fourth-dri-fit-fo…", "original_image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/431734766_93023398175…", "resized_image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/431734766_93023398175…", "title": "Nike F.C. Barcelona 2023/24 Stadium Fourth Women's Nike Dri-FIT Football Shirt", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null } ], "country_iso_code": null, "cta_text": "Install now", "cta_type": "INSTALL_MOBILE_APP", "disclaimer_label": null, "display_format": "DPA", "ec_certificates": [], "event": null, "extra_images": [], "extra_links": [], "extra_texts": [], "extra_videos": [], "images": [], "is_reshared": false, "link_description": null, "link_url": "http://itunes.apple.com/app/id1095459556", "page_categories": [ "Sportswear", "Product/service" ], "page_id": "15087023444", "page_is_deleted": false, "page_like_count": 39514042, "page_name": "Nike", "page_profile_picture_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/431756959_71287105437…", "page_profile_uri": "https://facebook.com/nike", "root_reshared_post": null, "title": "{{product.name}}", "videos": [], "body": { "text": "Bring sports more fully into your day with the Nike App." } }, "spend": null, "start_date": 1744009200, "start_date_string": null, "state_media_run_label": null, "targeted_or_reached_countries": [], "total_active_time": null, "url": null }, { "ad_archive_id": "1559738104701476", "ad_id": null, "categories": [ "UNKNOWN" ], "collation_count": null, "collation_id": null, "contains_digital_created_media": false, "contains_sensitive_content": false, "currency": "", "end_date": 1790751600, "end_date_string": null, "fev_info": null, "gated_type": "ELIGIBLE", "has_user_reported": false, "hide_data_status": "NONE", "impressions_with_index": { "impressions_text": null, "impressions_index": -1 }, "is_aaa_eligible": false, "is_active": true, "menu_items": [], "page_id": "15087023444", "page_is_deleted": false, "page_name": "Nike", "publisher_platform": [ "FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER" ], "reach_estimate": null, "regional_regulation_data": { "finserv": { "is_deemed_finserv": false, "is_limited_delivery": false }, "tw_anti_scam": { "is_limited_delivery": false } }, "report_count": null, "snapshot": { "additional_info": null, "branded_content": null, "brazil_tax_id": null, "byline": null, "caption": "play.google.com", "cards": [ { "body": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los benefic…", "caption": "play.google.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "$2,294", "link_url": "https://www.nike.com/mx/t/calzado-air-force-1-07-WGq1wQ?cp=54413048966_soc_", "original_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/400057885_87665133739…", "resized_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/400057885_87665133739…", "title": "Calzado para mujer Nike Air Force 1 '07 - Blanco", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los benefic…", "caption": "play.google.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "$1,409", "link_url": "https://www.nike.com/mx/t/pants-de-tejido-woven-upf-sportswear-tech-pack…", "original_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/399999246_15658089508…", "resized_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/399999246_15658089508…", "title": "Pants de tejido Woven para hombre UPF Nike Sportswear Tech Pack - Negro", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los benefic…", "caption": "play.google.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "$854", "link_url": "https://www.nike.com/mx/t/shorts-dri-fit-de-18-900-versátiles-sin-forro-…", "original_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/399960590_10038894207…", "resized_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/399960590_10038894207…", "title": "Shorts Dri-FIT de 18 cm versátiles sin forro para hombre Nike Form - Negro", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los benefic…", "caption": "play.google.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "$2,699", "link_url": "https://www.nike.com/mx/t/calzado-blazer-mid-77-se-j99WT3?cp=54413048966_soc_", "original_image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/400107091_32468404422…", "resized_image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/400107091_32468404422…", "title": "Calzado para hombre Nike Blazer Mid '77 SE - Blanco", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los benefic…", "caption": "play.google.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "$584", "link_url": "https://www.nike.com/mx/t/camiseta-de-tirantes-estampada-cropped-dri-fit…", "original_image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/399930460_24955988143…", "resized_image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/399930460_24955988143…", "title": "Camiseta de tirantes estampada cropped para mujer Nike Dri-FIT One - Negro", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null }, { "body": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los benefic…", "caption": "play.google.com", "cta_text": "Install Now", "cta_type": "INSTALL_MOBILE_APP", "image_crops": [], "link_description": "$2,069", "link_url": "https://www.nike.com/mx/t/dri-fit-adv-aps-chamarra-de-condición-física-7…", "original_image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/399982152_69380555947…", "resized_image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.35426-6/399982152_69380555947…", "title": "Nike Dri-FIT ADV A.P.S. Chamarra de condición física para hombre - Negro", "video_hd_url": null, "video_preview_image_url": null, "video_sd_url": null, "watermarked_resized_image_url": "", "watermarked_video_hd_url": null, "watermarked_video_sd_url": null } ], "country_iso_code": null, "cta_text": "Install now", "cta_type": "INSTALL_MOBILE_APP", "disclaimer_label": null, "display_format": "DPA", "ec_certificates": [], "event": null, "extra_images": [], "extra_links": [], "extra_texts": [], "extra_videos": [], "images": [], "is_reshared": false, "link_description": null, "link_url": "http://play.google.com/store/apps/details?id=com.nike.omega", "page_categories": [ "Sportswear", "Product/service" ], "page_id": "15087023444", "page_is_deleted": false, "page_like_count": 39514042, "page_name": "Nike", "page_profile_picture_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/400027547_35873985350…", "page_profile_uri": "https://facebook.com/nike", "root_reshared_post": null, "title": "{{product.name}}", "videos": [], "body": { "text": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los benefic…" } }, "spend": null, "start_date": 1745564400, "start_date_string": null, "state_media_run_label": null, "targeted_or_reached_countries": [], "total_active_time": null, "url": null } ], "searchResultsCount": 3198, "cursor": "AQHTSMQB_ilt9UKh88HFxw9XeDw_S-boWBzDyu2zJ501ztCVwRkxXJhPBxpxMJXVjKXd" } ``` ## Response fields Every field of a successful response. `[]` marks a list: `a[].b` is the `b` of each item in `a`. **nullable** fields can be `null`; **optional** fields can be missing. | Field | Type | Description | | --- | --- | --- | | `success` | `true` | Always true here; errors have `success: false`. | | `credits_remaining` | `number` | Your balance after this call. On anonymous playground calls: free tries left today. | | `credits_charged` | `number` | Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1). | | `page_id` | `string` | The page these ads are from: `pageId` as given, or the page we matched for `companyName`. | | `page_name` | `string`, nullable | That page's name (the matched page for `companyName`, else from the ads); null when there are no ads. | | `results` | `object[]` | The advertiser's ads. | | `results[].ad_archive_id` | `string`, nullable | The Ad Library id. Pass it as `id` to the ad details endpoint. | | `results[].ad_id` | `string`, nullable | Meta's internal ad id. null in every response we've seen; use the Ad Library id. | | `results[].page_id` | `string`, nullable | The advertiser's Facebook page id. Pass it as `pageId` to the company ads endpoint. | | `results[].page_name` | `string`, nullable | The advertiser's page name. | | `results[].is_active` | `boolean` | Whether the ad is running now. | | `results[].start_date` | `number`, nullable | When the ad started running, Unix seconds (UTC). | | `results[].end_date` | `number`, nullable | When the ad stopped, or its latest delivery date if still running, Unix seconds (UTC). | | `results[].start_date_string` | `string`, nullable | The same date as ISO 8601 text when Facebook includes it; often null, so prefer the Unix seconds field. | | `results[].end_date_string` | `string`, nullable | The same date as ISO 8601 text when Facebook includes it; often null, so prefer the Unix seconds field. | | `results[].total_active_time` | `number`, nullable | Seconds the ad has run, when Facebook reports it; usually null. | | `results[].publisher_platform` | `string[]` | Where it ran, uppercase: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, THREADS. | | `results[].collation_count` | `number`, nullable | How many near-identical versions are grouped under this ad. A high count means the advertiser is scaling it; null for a single version. | | `results[].collation_id` | `string`, nullable | Id shared by the grouped versions of this ad; null for a single version. | | `results[].snapshot` | `object` | The creative: copy, media, landing page and advertiser details. | | `results[].snapshot.page_id` | `string`, nullable | The advertiser's page id (same as the ad's). | | `results[].snapshot.page_name` | `string`, nullable | The advertiser's page name as shown on the ad. | | `results[].snapshot.page_profile_uri` | `string`, nullable | The advertiser's Facebook page URL. | | `results[].snapshot.page_profile_picture_url` | `string`, nullable | The advertiser's profile picture, 60×60 px. | | `results[].snapshot.page_like_count` | `number`, nullable | Followers of the advertiser's page. | | `results[].snapshot.page_categories` | `string[]` | Page categories, e.g. ["Outdoor & Sporting Goods Company"]. | | `results[].snapshot.page_is_deleted` | `boolean` | Whether the advertiser's page has been deleted. | | `results[].snapshot.title` | `string`, nullable | Headline under the creative; null when there is none. | | `results[].snapshot.caption` | `string`, nullable | Display link under the creative, usually the domain (e.g. HOKA.com). | | `results[].snapshot.link_url` | `string`, nullable | Landing page the ad sends people to, UTM tags included. | | `results[].snapshot.link_description` | `string`, nullable | Text under the headline; null when there is none. | | `results[].snapshot.cta_text` | `string`, nullable | Button label, e.g. "Shop now". | | `results[].snapshot.cta_type` | `string`, nullable | Button type, e.g. SHOP_NOW, LEARN_MORE, NO_BUTTON. | | `results[].snapshot.display_format` | `string`, nullable | Creative format, e.g. IMAGE, VIDEO, DCO (dynamic creative), DPA (dynamic product ad) or MULTI_IMAGES. For DCO and DPA ads the creative is in `cards`. | | `results[].snapshot.images` | `object[]` | Image creatives. Empty for video and card-based ads, and with trim=true. | | `results[].snapshot.images[].original_image_url` | `string`, nullable | Full-size image URL. Facebook CDN links expire after a few days; download what you need. | | `results[].snapshot.images[].resized_image_url` | `string`, nullable | 600 px image URL, good for thumbnails. | | `results[].snapshot.images[].watermarked_resized_image_url` | `string` | Watermarked copy; empty or null in every response we've seen. | | `results[].snapshot.images[].image_crops` | `any[]` | Facebook internal field; an empty array in every response we've seen. Crop hints for the image. | | `results[].snapshot.videos` | `object[]` | Video creatives. Empty for image and card-based ads, and with trim=true. | | `results[].snapshot.videos[].video_hd_url` | `string`, nullable | HD video file URL; null if Facebook has no HD version. | | `results[].snapshot.videos[].video_sd_url` | `string`, nullable | SD video file URL. | | `results[].snapshot.videos[].video_preview_image_url` | `string`, nullable | Poster frame (still image) URL. | | `results[].snapshot.videos[].watermarked_video_hd_url` | `string`, nullable | Watermarked copy; empty or null in every response we've seen. | | `results[].snapshot.videos[].watermarked_video_sd_url` | `string`, nullable | Watermarked copy; empty or null in every response we've seen. | | `results[].snapshot.cards` | `object[]` | Carousel, dynamic-creative and product versions, each with its own copy and media. With trim=true the text stays and media URLs are null. | | `results[].snapshot.cards[].title` | `string`, nullable | This version's headline. | | `results[].snapshot.cards[].body` | `string`, nullable | This version's primary text. | | `results[].snapshot.cards[].caption` | `string`, nullable | This version's display link, usually the domain. | | `results[].snapshot.cards[].cta_text` | `string`, nullable | Button label, e.g. "Shop now". | | `results[].snapshot.cards[].cta_type` | `string`, nullable | Button type, e.g. SHOP_NOW, LEARN_MORE. | | `results[].snapshot.cards[].link_url` | `string`, nullable | This version's landing page URL. | | `results[].snapshot.cards[].link_description` | `string`, nullable | Text under the headline; null when there is none. | | `results[].snapshot.cards[].original_image_url` | `string`, nullable | Full-size image URL; null for video versions. | | `results[].snapshot.cards[].resized_image_url` | `string`, nullable | 600 px image URL; null for video versions. | | `results[].snapshot.cards[].watermarked_resized_image_url` | `string` | Watermarked copy; empty or null in every response we've seen. | | `results[].snapshot.cards[].image_crops` | `any[]` | Facebook internal field; an empty array in every response we've seen. Crop hints for the image. | | `results[].snapshot.cards[].video_hd_url` | `string`, nullable | HD video file URL; null for image versions. | | `results[].snapshot.cards[].video_sd_url` | `string`, nullable | SD video file URL; null for image versions. | | `results[].snapshot.cards[].video_preview_image_url` | `string`, nullable | Poster frame URL; null for image versions. | | `results[].snapshot.cards[].watermarked_video_hd_url` | `string`, nullable | Watermarked copy; empty or null in every response we've seen. | | `results[].snapshot.cards[].watermarked_video_sd_url` | `string`, nullable | Watermarked copy; empty or null in every response we've seen. | | `results[].snapshot.byline` | `string`, nullable | Line under the page name, when shown; null or empty in most ads. | | `results[].snapshot.disclaimer_label` | `string`, nullable | "Paid for by" line on political and issue ads; null otherwise. | | `results[].snapshot.country_iso_code` | `string`, nullable | Facebook internal field; null in every response we've seen. A country code on some ads. | | `results[].snapshot.is_reshared` | `boolean` | Whether the ad reshares an existing post (see `root_reshared_post`). | | `results[].snapshot.root_reshared_post` | `any` | The original post when `is_reshared` is true; null otherwise. | | `results[].snapshot.branded_content` | `any` | Paid partnership details when the ad is branded content; null otherwise. | | `results[].snapshot.additional_info` | `any` | Facebook internal field; null in every response we've seen. | | `results[].snapshot.brazil_tax_id` | `any` | Advertiser tax id shown on ads under Brazil's rules; null otherwise. | | `results[].snapshot.ec_certificates` | `any[]` | Facebook internal field; an empty array in every response we've seen. | | `results[].snapshot.event` | `any` | Event details on event ads; null otherwise. | | `results[].snapshot.extra_images` | `any[]` | More images from dynamic creative; usually empty. | | `results[].snapshot.extra_links` | `any[]` | More landing page URLs from dynamic creative; usually empty. | | `results[].snapshot.extra_texts` | `any[]` | More text variations from dynamic creative; usually empty. | | `results[].snapshot.extra_videos` | `any[]` | More videos from dynamic creative; usually empty. | | `results[].snapshot.body` | `object`, nullable | Primary text as `{ text }`; null when the copy is only in `cards`. | | `results[].snapshot.body.text` | `string`, nullable | The ad's primary text. | | `results[].categories` | `string[]` | Special ad categories Facebook assigned. ["UNKNOWN"] for ordinary ads. | | `results[].targeted_or_reached_countries` | `string[]` | Countries the ad targeted or reached, when Facebook discloses them; empty in most results. | | `results[].currency` | `string` | Currency code of `spend` (e.g. USD) when spend is reported; an empty string otherwise. | | `results[].spend` | `any` | Spend range, reported for political and issue ads only; null otherwise. | | `results[].impressions_with_index` | `object` | Impressions range, reported for political and issue ads only. | | `results[].impressions_with_index.impressions_text` | `string`, nullable | The range as Facebook shows it; null when not reported. | | `results[].impressions_with_index.impressions_index` | `number` | Facebook's bucket number for the range; -1 when not reported. | | `results[].reach_estimate` | `any` | Estimated reach, which Facebook reports for some EU-delivered ads; null otherwise. | | `results[].url` | `string`, nullable | Ad Library link for this ad. Often null; build it as https://www.facebook.com/ads/library/?id=. | | `results[].contains_digital_created_media` | `boolean` | Whether Facebook labels the creative as AI-generated or digitally altered. | | `results[].contains_sensitive_content` | `boolean` | Facebook internal field; false in every response we've seen. Facebook's sensitive-content flag. | | `results[].gated_type` | `string` | Facebook internal field; ELIGIBLE (lowercase in ad details) in every response we've seen. | | `results[].has_user_reported` | `boolean` | Whether the viewing user reported the ad. Always false: we read the Ad Library logged out. | | `results[].hide_data_status` | `string` | Facebook internal field; NONE in every response we've seen. | | `results[].is_aaa_eligible` | `boolean` | Facebook flag, true on a few ads; meaning undocumented. Ad details' `aaa_info` holds the related data when present. | | `results[].menu_items` | `any[]` | Facebook internal field; an empty array in every response we've seen. | | `results[].page_is_deleted` | `boolean` | Whether the advertiser's page has been deleted. | | `results[].regional_regulation_data` | `object` | Delivery limits under regional ad rules. | | `results[].regional_regulation_data.finserv` | `object` | Financial-services ad rules. | | `results[].regional_regulation_data.finserv.is_deemed_finserv` | `boolean` | Facebook treats the ad as a financial-services ad. | | `results[].regional_regulation_data.finserv.is_limited_delivery` | `boolean` | Delivery is limited under financial-services rules. | | `results[].regional_regulation_data.tw_anti_scam` | `object` | Taiwan's anti-scam ad rules. | | `results[].regional_regulation_data.tw_anti_scam.is_limited_delivery` | `boolean` | Delivery is limited under Taiwan's anti-scam rules. | | `results[].report_count` | `number`, nullable | Times the ad was reported, when disclosed; null in every response we've seen. | | `results[].fev_info` | `any` | Facebook internal field; null in every response we've seen. | | `results[].state_media_run_label` | `any` | Label for ads run by state-controlled media; null otherwise. | | `searchResultsCount` | `number`, nullable | Total matching ads, as Facebook estimates it. Only on the first page; null on cursor pages. | | `cursor` | `string`, nullable | Pass as `cursor` for the next page. null on the last page. | ## Pagination Pass the response's `cursor` back as `cursor`, with the other parameters unchanged, for the next page. It's `null` on the last page. Each page costs 1 credit. The first five pages, in JavaScript: ```js let cursor = null; for (let page = 1; page <= 5; page++) { const params = new URLSearchParams({ pageId: "15087023444", status: "active" }); if (cursor) params.set("cursor", cursor); const res = await fetch(`https://api.lurkapi.com/v1/facebook/adLibrary/company/ads?${params}`, { headers: { "x-api-key": process.env.LURKAPI_KEY }, }); const data = await res.json(); if (!data.success) throw new Error(`${data.code}: ${data.error}`); console.log(data.results); cursor = data.cursor; if (!cursor) break; // last page } ``` ## Caching and freshness Responses are cached for up to 30 minutes, so a repeat call within that window can return the same data. It still costs 1 credit. ## Errors Errors return `{ success: false, error, code, docs }` with the HTTP status below. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)). [All error codes](https://lurkapi.com/docs.md#errors). | Status | Code | Meaning | | --- | --- | --- | | 401 | `missing_api_key` | No API key. Send it in the `x-api-key` header. | | 401 | `invalid_api_key` | The key is unknown or was revoked. | | 402 | `insufficient_credits` | Not enough credits for this call. Buy a pack or wait for tomorrow's top-up. | | 404 | `not_found` | The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked. | | 405 | `method_not_allowed` | Endpoints take GET with query params. | | 429 | `rate_limited` | Too many calls at once. Wait for the `retry-after` seconds, then retry. | | 500 | `internal_error` | Something broke on our side. Retry; 5xx errors are free. | | 502 | `upstream_error` | The platform didn't give a usable answer. Retry; 5xx errors are free. | | 503 | `upstream_busy` | All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free. | | 504 | `upstream_timeout` | The platform took over 30 seconds to answer. Retry; timeouts are free. | ## Use it in Claude Once LurkAPI is [connected to Claude](https://lurkapi.com/docs.md#claude), this endpoint is the `facebook_company_ads` tool. Ask in plain English, for example: Ask Claude: ```text Use LurkAPI's facebook_company_ads with pageId "15087023444", status "active" and summarize what you find. ``` Claude calls `facebook_company_ads` with arguments like these, and each call costs 1 credit: Tool arguments: ```json { "pageId": "15087023444", "status": "active" } ``` Tool results skip nulls and empty lists to save tokens, and `trim` defaults to `true`. --- Previous: [Search Ad Library ads](https://lurkapi.com/docs/facebook/search-ads.md) · Next: [Ad Library ad details](https://lurkapi.com/docs/facebook/ad.md)