> For the complete documentation index, see [llms.txt](https://docs.scrapingdog.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scrapingdog.com/facebook-ads-scraper-api.md).

# Facebook Ads Scraper API

Each successful request will cost you **`5`** API credits.

You have to send a GET request to **`http://api.scrapingdog.com/facebook/ads`** with the below-given parameters.

### Parameters <a href="#parameters" id="parameters"></a>

#### **Scrapingdog Parameters**

| Parameter                                                          | Description                                                                                     |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| <p>api\_key<br></p><p><mark style="color:red;">required</mark></p> | <p>Your personal API key. Available on your dashboard <br><br>Type: <strong>String</strong></p> |

#### Search Query

| Parameter | Description                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page\_id  | <p>Facebook Page ID used to fetch ads from a specific Facebook page. When this is provided, the API searches ads by page instead of keyword.<br><br>Type: <strong>String</strong></p>                                                                                                                                                                                                                                              |
| query     | <p>Search keyword or phrase used to find matching ads in the Facebook Ads Library. Required when <code>page\_id</code> or <code>url</code> is not provided.<br><br>Type: <strong>String</strong></p>                                                                                                                                                                                                                               |
| url       | <p>Full Facebook Ads Library URL. If provided, the API extracts supported search parameters from the URL automatically, such as <code>q</code> as <code>query</code> and <code>view\_all\_page\_id</code> as <code>page\_id</code>. This is useful when users already have a Facebook Ads Library search URL and want to scrape the same results without manually passing each parameter.<br><br>Type: <strong>String</strong></p> |

#### Geographic Location and Localization

| Parameter         | Description                                                                                                                                                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| location\_id      | <p>Location identifier used to filter ads by a specific city, region, or country. This must be used together with <code>location\_name</code> and <code>location\_type</code>.<br><br>Type: <strong>String</strong></p> |
| location\_name    | <p>Name of the location used in the location filter, such as a city, region, or country name. Required when using <code>location\_id</code>.<br><br>Type: <strong>String</strong></p>                                   |
| location\_type    | <p>Type of location filter. Accepted values are <code>CITY</code>, <code>REGION</code>, and <code>COUNTRY</code>. Required when using location filters.<br><br>Type: <strong>String</strong></p>                        |
| country           | <p>Country code used to filter ads by country. Default value is <code>ALL</code>. Example: <code>US</code>, <code>IN</code>, <code>GB</code>.<br><br>Type: <strong>String</strong></p>                                  |
| content\_language | <p>Filters ads by the language of the ad content. Pass the language code supported by Facebook Ads Library.<br><br>Type: <strong>String</strong></p>                                                                    |

#### Filters

| Parameter             | Description                                                                                                                                                                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ad\_type              | <p>Type of ads to return. Default value is <code>ALL</code>. Accepted values are <code>ALL</code>, <code>POLITICAL\_AND\_ISSUE\_ADS</code>, <code>HOUSING</code>, <code>EMPLOYMENT</code>, and <code>CREDIT</code>.<br><br>Type: <strong>String</strong></p>                      |
| active\_status        | <p>Filters ads by their current status. Default value is <code>ALL</code>. Accepted values are <code>ALL</code>, <code>ACTIVE</code>, and <code>INACTIVE</code>.<br><br>Type: <strong>String</strong></p>                                                                         |
| media\_type           | <p>Filters ads by creative media type. Default value is <code>ALL</code>. Accepted values are <code>ALL</code>, <code>VIDEO</code>, and <code>IMAGE</code>.<br><br>Type: <strong>String</strong></p>                                                                              |
| platforms             | <p>Comma-separated list of platforms where the ads are running. Accepted values are <code>facebook</code>, <code>instagram</code>, <code>messenger</code>, and <code>audience\_network</code>. Example: <code>facebook,instagram</code>.<br><br>Type: <strong>String</strong></p> |
| is\_targeted\_country | <p>Boolean value used to apply targeted country filtering. In your code, this is automatically treated as <code>true</code> when a specific country or location filter is used.<br><br>Type: <strong>String</strong></p>                                                          |

#### Date Range

| Parameter   | Description                                                                                                                                        |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| start\_date | <p>Filters ads that started running on or after this date. Use ISO date format: <code>YYYY-MM-DD</code>.<br><br>Type: <strong>String</strong></p>  |
| end\_date   | <p>Filters ads that started running on or before this date. Use ISO date format: <code>YYYY-MM-DD</code>.<br><br>Type: <strong>String</strong></p> |

#### Pagination

| Parameter         | Description                                                                                                                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| next\_page\_token | <p>Pagination token used to fetch the next page of ad results. Pass the token returned in the previous response to continue scraping from where the last request ended.<br><br>Type: String</p> |

{% hint style="info" %}
The next\_page\_token can get very large when you get deeper into pages. Due to this, NGINX can reject the request because the URI is getting too large. Users can also use the POST API with same endpoint  and pass all these parameters as a body.
{% endhint %}

### API Example

{% tabs %}
{% tab title="cURL" %}

```bash
cURL "https://api.scrapingdog.com/facebook/ads?api_key=APIKEU&page_id=102479591179005"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

api_key = "APIKEY"
url = "https://api.scrapingdog.com/facebook/ads"

params = {
    "api_key": api_key,
    "paeg_id": "102479591179005"
}

response = requests.get(url, params=params)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Request failed with status code: {response.status_code}")

```

{% endtab %}

{% tab title="Node JS" %}

```javascript
const axios = require('axios');

const api_key = 'APIKEY';
const url = 'https://api.scrapingdog.com/facebook/ads/';

const params = {
  api_key: api_key,
  page_id: '102479591179005'
};

axios
  .get(url, { params: params })
  .then(function (response) {
    if (response.status === 200) {
      const data = response.data;
      console.log(data)
    } else {
      console.log('Request failed with status code: ' + response.status);
    }
  })
  .catch(function (error) {
    console.error('Error making the request: ' + error.message);
  });

```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

// Set the API key and request parameters
$api_key = 'APIKEY';
$page_id = '102479591179005';

// Set the API endpoint
$url = 'https://api.scrapingdog.com/facebook/ads/?api_key=' . $api_key . '&page_id=' . $page_id;

// Initialize cURL session
$ch = curl_init($url);

// Set cURL options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute the cURL request
$response = curl_exec($ch);

// Check if the request was successful
if ($response === false) {
    echo 'cURL error: ' . curl_error($ch);
} else {
    // Process the response data as needed
    echo $response;
}

// Close the cURL session
curl_close($ch);

```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'net/http'
require 'uri'

# Set the API key and request parameters
api_key = 'APIKEY'
page_id = '102479591179005'

# Construct the API endpoint URL
url = URI.parse("https://api.scrapingdog.com/facebook/ads/?api_key=#{api_key}&page_id=#{page_id}")

# Create an HTTP GET request
request = Net::HTTP::Get.new(url)

# Create an HTTP client
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true # Enable SSL (https)

# Send the request and get the response
response = http.request(request)

# Check if the request was successful
if response.is_a?(Net::HTTPSuccess)
  puts response.body # Process the response data as needed
else
  puts "HTTP request failed with code: #{response.code}, message: #{response.message}"
end

```

{% endtab %}

{% tab title="Java" %}

```java
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.IOException;

public class Main {
    public static void main(String[] args) {
        try {
            // Set the API key and request parameters
            String apiKey = "APIKEY";
            String page_id = "102479591179005";

            // Construct the API endpoint URL
            String apiUrl = "https://api.scrapingdog.com/facebook/ads/?api_key=" + apiKey
                    + "&page_id=" + page_id

            // Create a URL object from the API URL string
            URL url = new URL(apiUrl);

            // Open a connection to the URL
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();

            // Set the request method to GET
            connection.setRequestMethod("GET");

            // Get the response code
            int responseCode = connection.getResponseCode();

            if (responseCode == 200) {
                // Read the response from the connection
                BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
                String inputLine;
                StringBuilder response = new StringBuilder();

                while ((inputLine = reader.readLine()) != null) {
                    response.append(inputLine);
                }
                reader.close();

                // Process the response data as needed
                System.out.println(response.toString());
            } else {
                System.out.println("HTTP request failed with response code: " + responseCode);
            }

            // Close the connection
            connection.disconnect();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

```

{% endtab %}
{% endtabs %}

### API Response

```json
{
     "ads": [
        {
            "ad_archive_id": "1451833693256257",
            "page_id": "102479591179005",
            "snapshot": {
                "branded_content": null,
                "page_id": "102479591179005",
                "page_is_deleted": false,
                "page_profile_uri": "https://facebook.com/agilefever",
                "root_reshared_post": null,
                "byline": null,
                "disclaimer_label": null,
                "page_name": "AgileFever",
                "page_profile_picture_url": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/645763362_1241420054208437_1400942722396186234_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=109&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=kGPLPoPeM9MQ7kNvwGYGdvv&_nc_oc=AdoZ9FeiAkvkv6lLo_edyxhFGWI6r6twNpHCt_fFcaBfbC7oGlGZpFp_z2zR-znwA_g&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=XXKmnNUvX2jfPUbPfuHK1g&_nc_ss=73289&oh=00_Af4H3FRLWiOuCPFfcGb-BvJeCy9p7PO9IKNyrGcZ8T8J_g&oe=6A1CE096",
                "event": null,
                "caption": "agilefever.com",
                "cta_text": "Learn more",
                "cards": [
                    {
                        "body": "Join the top 1% of engineers who can actually put AI into production.",
                        "cta_type": "LEARN_MORE",
                        "caption": "agilefever.com",
                        "link_description": "Join the top 1% of engineers who can actually put AI into production.",
                        "link_url": "https://www.agilefever.com/bootcamps/mlops-bootcamp/",
                        "title": "From Software Engineer to MLOps Architect 🚀",
                        "cta_text": "Learn More",
                        "video_hd_url": null,
                        "video_preview_image_url": null,
                        "video_sd_url": null,
                        "watermarked_video_hd_url": null,
                        "watermarked_video_sd_url": null,
                        "image_crops": [],
                        "original_image_url": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/646313981_4360384810916665_9099797892930691372_n.jpg?_nc_cat=108&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=1mTtdvKWk2kQ7kNvwHo3ZXp&_nc_oc=Adq_VXXO38FMrlFFtZc5-HAN11qmiP86M_qjtPEO9LmLEdNywMK8RV7w2vUjrDJBYn4&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=XXKmnNUvX2jfPUbPfuHK1g&_nc_ss=73289&oh=00_Af72g74719xFKFqAxQXxrR1boFeTLD5GVGL-WHmoSHBoqQ&oe=6A1CB9F1",
                        "resized_image_url": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/646638311_897966893038610_8416632628881061211_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=VdzjvLBMzIcQ7kNvwHw-yrg&_nc_oc=AdqRXSi5PIQbgmz9yf35WK5BFJKC7YIbqYRn-LONR3en2bfx6EQycaTDLuG4r3NjN1w&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=XXKmnNUvX2jfPUbPfuHK1g&_nc_ss=73289&oh=00_Af7QQuDcYBqIdG-uuSsCPX99_1RkTQCXeKR8Gs7-CuI21g&oe=6A1CBD35",
                        "watermarked_resized_image_url": ""
                    },
                    {
                        "body": "Join the top 1% of engineers who can actually put AI into production.",
                        "cta_type": "LEARN_MORE",
                        "caption": "agilefever.com",
                        "link_description": "Join the top 1% of engineers who can actually put AI into production.",
                        "link_url": "https://www.agilefever.com/bootcamps/mlops-bootcamp/",
                        "title": "From Software Engineer to MLOps Architect 🚀",
                        "cta_text": "Learn More",
                        "video_hd_url": null,
                        "video_preview_image_url": null,
                        "video_sd_url": null,
                        "watermarked_video_hd_url": null,
                        "watermarked_video_sd_url": null,
                        "image_crops": [],
                        "original_image_url": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/646927756_1251100770326777_5598043279398185210_n.jpg?_nc_cat=107&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=xbxbXbDn2EgQ7kNvwE7jvLn&_nc_oc=AdoJLWsIOXC2kdw6qdn7oG_GHjtTPHtJSISHnNclJkhb5GXTIZQso6ih2eCc8JHm8PI&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=XXKmnNUvX2jfPUbPfuHK1g&_nc_ss=73289&oh=00_Af4ujX_WP-_yzOn72tPoZrbFaYRKJibWmLJzt5gjxyzJ6A&oe=6A1CCD7B",
                        "resized_image_url": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/645369087_2353670585044965_2218704528678595872_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=6htQyMkxvmcQ7kNvwFCXMyG&_nc_oc=AdqiYbRw8GHME-G5dZ1x0wCvctefX6Ue-CGQAOevJcnVZydzI2essqZIcQW4Eushy2I&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=XXKmnNUvX2jfPUbPfuHK1g&_nc_ss=73289&oh=00_Af56Z9wLOHUwxv1UA3ySTa1yL-c9MHkEVN7Eh1IGTeP8tA&oe=6A1CBB9C",
                        "watermarked_resized_image_url": ""
                    },
                    {
                        "body": "Join the top 1% of engineers who can actually put AI into production.",
                        "cta_type": "LEARN_MORE",
                        "caption": "agilefever.com",
                        "link_description": "Join the top 1% of engineers who can actually put AI into production.",
                        "link_url": "https://www.agilefever.com/bootcamps/mlops-bootcamp/",
                        "title": "From Software Engineer to MLOps Architect 🚀",
                        "cta_text": "Learn More",
                        "video_hd_url": null,
                        "video_preview_image_url": null,
                        "video_sd_url": null,
                        "watermarked_video_hd_url": null,
                        "watermarked_video_sd_url": null,
                        "image_crops": [],
                        "original_image_url": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/646614578_3380223628793906_3270121437360773425_n.jpg?_nc_cat=107&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=xZz9YHgNVzcQ7kNvwGZFJJZ&_nc_oc=AdpJOpGcDpI_vkrjGY2If8UzzxGBhy6Izly-urNzR1vG7N9Yxmi_OaqnPHH0RAnVWxY&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=XXKmnNUvX2jfPUbPfuHK1g&_nc_ss=73289&oh=00_Af6u7A4xOHRipGVhDpd8VA5hIJo94y6AF68hK7Dgj0kGlA&oe=6A1CCCF0",
                        "resized_image_url": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/645450604_1975098390058857_4510795847006939788_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=l1_jZzOBchEQ7kNvwHGFBbB&_nc_oc=Adpe0_EaRprG7_2faJL0qekiNgl-r1Rtm2DkkfxB0jt3AQ_JzrPuKlnt9a1AJpPUS7w&_nc_zt=14&_nc_ht=scontent-phl2-1.xx&_nc_gid=XXKmnNUvX2jfPUbPfuHK1g&_nc_ss=73289&oh=00_Af4fIpzNAAgr-v4_cZLv6lcq4XAilh70e2Am7HdwQ_wRuQ&oe=6A1CC7AF",
                        "watermarked_resized_image_url": ""
                    }
                ],
                "body": {
                    "text": "Stop building models that never leave the notebook. 🛑\n\nThe industry is shifting. While everyone is learning \"How to Prompt,\" the real architectural challenge is \"How to Scale.\" As a Software Engineer, you already have the foundation. Our MLOps Bootcamp gives you the missing pieces: CI/CD for ML, Model Monitoring, and automated retraining pipelines.\n\nGo from \"Developer\" to \"MLOps Architect\" and lead the AI transition in your company.\n\n✅ 100% Project-based learning\n✅ Master Docker, Kubernetes, & MLflow\n✅ Architecture patterns used by Netflix and Uber"
                },
                "cta_type": "LEARN_MORE",
                "display_format": "CAROUSEL",
                "link_description": null,
                "link_url": "https://www.agilefever.com/",
                "images": [],
                "page_categories": [
                    "Education website"
                ],
                "page_like_count": 416,
                "title": "AgileFever",
                "videos": [],
                "is_reshared": false,
                "extra_links": [
                    "https://www.agilefever.com/bootcamps/",
                    "https://www.agilefever.com/privacy/",
                    "https://www.agilefever.com/bootcamps/"
                ],
                "extra_texts": [
                    {
                        "text": "Unlock Your Career Potential with AgileFever Bootcamps!"
                    },
                    {
                        "text": "Accelerate your career with AgileFever’s comprehensive bootcamps in agile, AI, data science, and more. Learn from industry experts through hands-on training designed for immediate impact. Sign up now to get personalized details and exclusive enrollment offers!"
                    },
                    {
                        "text": "Please provide your contact details so we can share exclusive information."
                    },
                    {
                        "text": "How many years of professional experience do you have?"
                    },
                    {
                        "text": "Fresher / No professional experience"
                    },
                    {
                        "text": "1 to 2 years"
                    },
                    {
                        "text": "2 to 5 years"
                    },
                    {
                        "text": "More than 5 years"
                    },
                    {
                        "text": "Full name"
                    },
                    {
                        "text": "Email"
                    },
                    {
                        "text": "Phone number"
                    },
                    {
                        "text": "Job title"
                    },
                    {
                        "text": "Terms and Conditions for AgileFever"
                    },
                    {
                        "text": "Visit AgileFever's Privacy Policy."
                    },
                    {
                        "text": "Thank you for your interest!"
                    },
                    {
                        "text": "We’ve received your info and will be in touch shortly with next steps."
                    }
                ],
                "extra_images": [],
                "extra_videos": [],
                "country_iso_code": null,
                "brazil_tax_id": null,
                "additional_info": null,
                "ec_certificates": []
            },
            "is_active": false,
            "page_name": "AgileFever",
            "categories": [
                "UNKNOWN"
            ],
            "collation_count": 1,
            "end_date": 1773385200,
            "gated_type": "ELIGIBLE",
            "hide_data_status": "NONE",
            "impressions_with_index": {
                "impressions_text": null,
                "impressions_index": -1
            },
            "publisher_platform": [
                "FACEBOOK",
                "INSTAGRAM",
                "THREADS"
            ],
            "start_date": 1772524800,
            "total_active_time": null
        },
        ...
      ]
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.scrapingdog.com/facebook-ads-scraper-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.