FACEBOOK AD LIBRARY API

Company Ads

Retrieve company ads from Facebook Ad Library with a single API request.

GET/api/data/v1/facebook/adLibrary/company/ads
1credit base cost

Request parameters

Up to 1 credit

The intended company's Facebook Page ID. Use pageId for accurate Page selection instead of relying on the companyName lookup. You can get it from Search for Companies; verify that the result is the company you want. Provide pageId or compan

Company name for a convenience lookup. We look up the Page for you, but the match may not be the company you intended and can lead to inaccurate results. Use pageId to target the correct company. Provide companyName or pageId.

This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.

Status of the ad. Defaults to ACTIVE.

Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme.

Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc

Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.

Start date to search for. Format: YYYY-MM-DD

End date to search for. Format: YYYY-MM-DD

Set to true for a trimmed down version of the response

Cursor to paginate through results

Try in the console

Live requests use your prepaid balance. Cached responses cost zero where supported.

curl --request GET \
  --url 'https://fetchgoblin.com/api/data/v1/facebook/adLibrary/company/ads' \
  --header 'x-api-key: YOUR_FETCHGOBLIN_API_KEY'

Response

Example
{
  "success": true,
  "results": [
    {
      "ad_archive_id": "1212560900568826",
      "end_date": 1750230000,
      "is_aaa_eligible": false,
      "is_active": true,
      "page_id": "15087023444",
      "page_name": "Nike",
      "political_countries": [],
      "reach_estimate": null,
      "snapshot": {
        "body": {
          "text": "Que el frío no te detenga. Explora la colección de invierno con estilo y actitud Nike. 🧥"
        },
        "branded_content": null,
        "brazil_tax_id": null,
        "byline": null,
        "caption": "fb.com",
        "cards": [],
        "cta_text": "Learn more",
        "cta_type": "LEARN_MORE",
        "country_iso_code": null,
        "current_page_name": "Nike",
        "disclaimer_label": null,
        "display_format": "VIDEO",
        "event": null,
        "images": [],
        "is_reshared": false,
        "link_description": null,
        "link_url": "https://fb.com/canvas_doc/569658969305127",
        "page_categories": [
          "Ropa deportiva"
        ],
        "page_entity_type": "PERSON_PROFILE",
        "page_id": "15087023444",
        "page_is_deleted": false,
        "page_is_profile_page": false,
        "page_like_count": 37497718,
        "page_name": "Nike",
        "page_profile_picture_url": "https://scontent-ord5-1.xx.fbcdn.net/v/t39.35426-6/508742493_1906025190144374_200543536673957484_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=108&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=GUPolKbhQA4Q7kNvwH8Woql&_nc_oc=AdnsaYY9-9p8kkFm594f86VsMEc2Wias8yMQ69ZC2VOv642bjUgMRJNtfihFM4vr62o&_nc_zt=14&_nc_ht=scontent-ord5-1.xx&_nc_gid=mmzWe0H6RNHM_tNirxejrQ&oh=00_AfO73iYbuEFgc4yfmi6pUnjLAd0I1W5ac9hmHZqjq2KP3g&oe=685A4C47",
        "page_profile_uri": "https://facebook.com/nike",
        "root_reshared_post": null,
        "title": "Look de invierno activado",
        "videos": [
          {
            "video_hd_url": "https://video-ord5-2.xx.fbcdn.net/v/t42.1790-2/508345466_4710910465802253_4502560017294477681_n.?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=_z9ndrNSqU4Q7kNvwErNTOY&_nc_oc=AdlSb3GVLWTjl3iI6uvIsrEya2ZR-1ex8t8yXOr3e9u13u3xboXylCxrkWzfLsvDQcU&_nc_zt=28&_nc_ht=video-ord5-2.xx&_nc_gid=mmzWe0H6RNHM_tNirxejrQ&oh=00_AfNNOrS6GBT-R_RV15FpphRv-mUwyGoqJClQpP-LCOcqfQ&oe=685A6586",
            "video_preview_image_url": "https://scontent-ord5-3.xx.fbcdn.net/v/t39.35426-6/508472131_2706791729511119_7655112167724018421_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=-GGzon31Wl4Q7kNvwHpWdG2&_nc_oc=AdnRHcWzvX05mBu9KrhDjKgOuCYLKjNg_hm8eKY2dNaFg-4tpYznNPJvbLl7CAnB-2A&_nc_zt=14&_nc_ht=scontent-ord5-3.xx&_nc_gid=mmzWe0H6RNHM_tNirxejrQ&oh=00_AfMijP4k74e949uFas1PkfzzwiYWH_G49J4W-EYJa31VEQ&oe=685A3DDC",
            "video_sd_url": "https://video-ord5-3.xx.fbcdn.net/v/t42.1790-2/503830433_1272051757688626_4613408767025280545_n.mp4?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=zKD6ziOmKVgQ7kNvwFGCx5N&_nc_oc=AdkdTw235NDuAczGAvCTLl5TnQ8rUcWjy1QBEj8CC4Id8hVQPMexxPtU3froQOYk1OE&_nc_zt=28&_nc_ht=video-ord5-3.xx&_nc_gid=mmzWe0H6RNHM_tNirxejrQ&oh=00_AfNqJDVyyTMYnf7xs5te87vB3A0v3IGy41tdxT1ZvrAAlQ&oe=685A4FC3",
            "watermarked_video_hd_url": "",
            "watermarked_video_sd_url": ""
          }
        ],
        "additional_info": null,
        "ec_certificates": [],
        "extra_images": [],
        "extra_links": [
          "https://www.nike.com.pe/productos/ropa/casacas-y-chalecos_conjunto_pantalones_poleras?utm_source=facebook&utm_medium=paid&utm_campaign=junio_invierno_transacciones&utm_content=intereses2_invierno_collection2"
        ],
        "extra_texts": [],
        "extra_videos": [
          {
            "video_hd_handle": "https://video-ord5-3.xx.fbcdn.net/v/t42.1790-2/508262243_4710910432468923_4352661581573318069_n.?_nc_cat=107&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=bQXAtOCS-PMQ7kNvwEbVbC_&_nc_oc=AdnZ87pJ-oeIb5L7fizjaxNmRp0qkvq2SP_ADcnPFzMPca1L8gvUkpmF_c5vrAYmetw&_nc_zt=28&_nc_ht=video-ord5-3.xx&_nc_gid=mmzWe0H6RNHM_tNirxejrQ&oh=00_AfM8Q_xyap9vnoEn5T7FqI9yfO1ySPPKyJVGXPmaim5tCw&oe=685A58CD",
            "video_sd_handle": "https://video-ord5-3.xx.fbcdn.net/v/t42.1790-2/503830433_1272051757688626_4613408767025280545_n.mp4?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=zKD6ziOmKVgQ7kNvwFGCx5N&_nc_oc=AdkdTw235NDuAczGAvCTLl5TnQ8rUcWjy1QBEj8CC4Id8hVQPMexxPtU3froQOYk1OE&_nc_zt=28&_nc_ht=video-ord5-3.xx&_nc_gid=mmzWe0H6RNHM_tNirxejrQ&oh=00_AfNqJDVyyTMYnf7xs5te87vB3A0v3IGy41tdxT1ZvrAAlQ&oe=685A4FC3",
            "watermarked_video_hd_url": null,
            "watermarked_video_sd_url": null
          }
        ]
      },
      "total_active_time": null,
      "spend": null,
      "start_date": 1750143600,
      "publisher_platform": [
        "FACEBOOK"
      ],
      "url": "https://www.facebook.com/ads/library?id=1212560900568826",
      "start_date_string": "2025-06-17T07:00:00.000Z",
      "end_date_string": "2025-06-18T07:00:00.000Z"
    }
  ],
  "cursor": "AQHR2LpCDWOZyAGp-ZKr8rUsapAXh8rWjYuNxVvuU7L0kte18hxkxnaXM3e5jEZNgdcU",
  "credits_charged": 1,
  "credits_remaining": 1000,
  "request_id": "00000000-0000-4000-8000-000000000000"
}
Illustrative response with example values adapted for FetchGoblin. Run a request to retrieve current platform data.

Response shape

This schema describes the documented data shape. Some platform fields may be absent or null. The response also includes your FetchGoblin request ID and current credit balance.

View JSON Schema +
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ad_archive_id": {
            "type": "string"
          },
          "end_date": {
            "type": "integer"
          },
          "is_aaa_eligible": {
            "type": "boolean"
          },
          "is_active": {
            "type": "boolean"
          },
          "page_id": {
            "type": "string"
          },
          "page_name": {
            "type": "string"
          },
          "political_countries": {
            "type": "array"
          },
          "reach_estimate": {
            "type": [
              "string",
              "object",
              "array",
              "number",
              "boolean",
              "null"
            ]
          },
          "snapshot": {
            "type": "object",
            "properties": {
              "body": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string"
                  }
                }
              },
              "branded_content": {
                "type": [
                  "string",
                  "object",
                  "array",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "brazil_tax_id": {
                "type": [
                  "string",
                  "object",
                  "array",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "byline": {
                "type": [
                  "string",
                  "object",
                  "array",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "caption": {
                "type": "string"
              },
              "cards": {
                "type": "array"
              },
              "cta_text": {
                "type": "string"
              },
              "cta_type": {
                "type": "string"
              },
              "country_iso_code": {
                "type": [
                  "string",
                  "object",
                  "array",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "current_page_name": {
                "type": "string"
              },
              "disclaimer_label": {
                "type": [
                  "string",
                  "object",
                  "array",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "display_format": {
                "type": "string"
              },
              "event": {
                "type": [
                  "string",
                  "object",
                  "array",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "images": {
                "type": "array"
              },
              "is_reshared": {
                "type": "boolean"
              },
              "link_description": {
                "type": [
                  "string",
                  "object",
                  "array",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "link_url": {
                "type": "string"
              },
              "page_categories": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "page_entity_type": {
                "type": "string"
              },
              "page_id": {
                "type": "string"
              },
              "page_is_deleted": {
                "type": "boolean"
              },
              "page_is_profile_page": {
                "type": "boolean"
              },
              "page_like_count": {
                "type": "integer"
              },
              "page_name": {
                "type": "string"
              },
              "page_profile_picture_url": {
                "type": "string"
              },
              "page_profile_uri": {
                "type": "string"
              },
              "root_reshared_post": {
                "type": [
                  "string",
                  "object",
                  "array",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "videos": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "video_hd_url": {
                      "type": "string"
                    },
                    "video_preview_image_url": {
                      "type": "string"
                    },
                    "video_sd_url": {
                      "type": "string"
                    },
                    "watermarked_video_hd_url": {
                      "type": "string"
                    },
                    "watermarked_video_sd_url": {
                      "type": "string"
                    }
                  }
                }
              },
              "additional_info": {
                "type": [
                  "string",
                  "object",
                  "array",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "ec_certificates": {
                "type": "array"
              },
              "extra_images": {
                "type": "array"
              },
              "extra_links": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "extra_texts": {
                "type": "array"
              },
              "extra_videos": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "video_hd_handle": {
                      "type": "string"
                    },
                    "video_sd_handle": {
                      "type": "string"
                    },
                    "watermarked_video_hd_url": {
                      "type": [
                        "string",
                        "object",
                        "array",
                        "number",
                        "boolean",
                        "null"
                      ]
                    },
                    "watermarked_video_sd_url": {
                      "type": [
                        "string",
                        "object",
                        "array",
                        "number",
                        "boolean",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "total_active_time": {
            "type": [
              "string",
              "object",
              "array",
              "number",
              "boolean",
              "null"
            ]
          },
          "spend": {
            "type": [
              "string",
              "object",
              "array",
              "number",
              "boolean",
              "null"
            ]
          },
          "start_date": {
            "type": "integer"
          },
          "publisher_platform": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string"
          },
          "start_date_string": {
            "type": "string"
          },
          "end_date_string": {
            "type": "string"
          }
        }
      }
    },
    "cursor": {
      "type": "string"
    },
    "credits_charged": {
      "type": "integer",
      "minimum": 0,
      "description": "FetchGoblin credits charged for this request."
    },
    "credits_remaining": {
      "type": "integer",
      "description": "Your FetchGoblin credit balance after this request."
    },
    "request_id": {
      "type": "string",
      "format": "uuid",
      "description": "FetchGoblin request identifier."
    }
  }
}