> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ScrapeCreators: Facebook Adlibrary Search Ads

> Facebook: Searches the Meta Ad Library by keyword and returns matching ads. Includes SDK V2 examples, input constraints, response fields, and Deepline cost.

Facebook: Searches the Meta Ad Library by keyword and returns matching ads.

> [!NOTE]
>
> Tool ID: `scrapecreators_facebook_adlibrary_search_ads`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'scrapecreators_facebook_adlibrary_search_ads',
  {
    "query": "software companies hiring engineers"
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute scrapecreators_facebook_adlibrary_search_ads --input '{
  "query": "software companies hiring engineers"
}' --json
```

## Example response

The static output schema lacks the details for a reliable example. Use `deepline describe scrapecreators_facebook_adlibrary_search_ads --json` for the complete live contract.

## Input reference

Searches the Meta Ad Library by keyword and returns matching ads. Supports filtering by language with a 2-letter code such as EN or ES. Each result includes ad\_archive\_id, page\_name, is\_active, publisher\_platform, and a snapshot with body text, images, videos, and cta\_text. Both GET and POST are supported. Use GET for normal requests. If the cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.query` | `string` | Yes | — | Keyword to search for |
| `payload.sort_by` | `"total_impressions" \| "relevancy_monthly_grouped"` | No | — | Sort by impressions (high to low), or Most Recent (relevancy\_monthly\_grouped). Defaults to impressions. Allowed: `total_impressions`, `relevancy_monthly_grouped`. |
| `payload.search_type` | `"keyword_unordered" \| "keyword_exact_phrase"` | No | — | If you want to search by exact phrase or not Allowed: `keyword_unordered`, `keyword_exact_phrase`. |
| `payload.ad_type` | `"all" \| "political_and_issue_ads"` | No | — | Search for all ads or only political and issue ads Allowed: `all`, `political_and_issue_ads`. |
| `payload.country` | `string` | No | — | This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL. |
| `payload.language` | `string` | No | — | Language to filter ads on. Needs to be a 2 letter language code, such as EN, ES, or FR. |
| `payload.status` | `"ALL" \| "ACTIVE" \| "INACTIVE"` | No | — | Status of the ad. Defaults to ACTIVE. Allowed: `ALL`, `ACTIVE`, `INACTIVE`. |
| `payload.media_type` | `"ALL" \| "IMAGE" \| "VIDEO" \| "MEME" \| "IMAGE_AND_MEME" \| "NONE"` | No | — | Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme. Allowed: `ALL`, `IMAGE`, `VIDEO`, `MEME`, `IMAGE_AND_MEME`, `NONE`. |
| `payload.start_date` | `string` | No | — | Impressions start date. Needs to be in YYYY-MM-DD format. |
| `payload.end_date` | `string` | No | — | Impressions end date. Needs to be in YYYY-MM-DD format. |
| `payload.trim` | `boolean` | No | — | Set to true for a trimmed down version of the response |
| `payload.cursor` | `string` | No | — | Cursor to paginate through results |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Searches the Meta Ad Library by keyword and returns matching ads. Supports filtering by language with a 2-letter code such as EN or ES. Each result includes ad_archive_id, page_name, is_active, publisher_platform, and a snapshot with body text, images, videos, and cta_text. Both GET and POST are supported. Use GET for normal requests. If the cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body.",
    "properties": {
      "query": {
        "type": "string",
        "description": "Keyword to search for"
      },
      "sort_by": {
        "type": "string",
        "description": "Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.",
        "enum": [
          "total_impressions",
          "relevancy_monthly_grouped"
        ]
      },
      "search_type": {
        "type": "string",
        "description": "If you want to search by exact phrase or not",
        "enum": [
          "keyword_unordered",
          "keyword_exact_phrase"
        ]
      },
      "ad_type": {
        "type": "string",
        "description": "Search for all ads or only political and issue ads",
        "enum": [
          "all",
          "political_and_issue_ads"
        ]
      },
      "country": {
        "type": "string",
        "description": "This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL."
      },
      "language": {
        "type": "string",
        "description": "Language to filter ads on. Needs to be a 2 letter language code, such as EN, ES, or FR."
      },
      "status": {
        "type": "string",
        "description": "Status of the ad. Defaults to ACTIVE.",
        "enum": [
          "ALL",
          "ACTIVE",
          "INACTIVE"
        ]
      },
      "media_type": {
        "type": "string",
        "description": "Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme.",
        "enum": [
          "ALL",
          "IMAGE",
          "VIDEO",
          "MEME",
          "IMAGE_AND_MEME",
          "NONE"
        ]
      },
      "start_date": {
        "type": "string",
        "description": "Impressions start date. Needs to be in YYYY-MM-DD format."
      },
      "end_date": {
        "type": "string",
        "description": "Impressions end date. Needs to be in YYYY-MM-DD format."
      },
      "trim": {
        "type": "boolean",
        "description": "Set to true for a trimmed down version of the response"
      },
      "cursor": {
        "type": "string",
        "description": "Cursor to paginate through results"
      }
    },
    "required": [
      "query"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

Standard tool result payload.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `unknown` | Yes | — | Provider response payload. |
| `result.meta` | `object` | No | — | Additional response metadata (status, paging). |

<details>
  <summary>Show raw output schema</summary>

  ### Output JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Standard tool result payload.",
    "properties": {
      "data": {
        "description": "Provider response payload."
      },
      "meta": {
        "type": "object",
        "description": "Additional response metadata (status, paging).",
        "additionalProperties": true
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0.02` per pricing unit.

## Related documentation

* [ScrapeCreators provider guide](https://deepline.com/docs/providers/scrapecreators/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.