> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/tools/search_meta_ads

# search_meta_ads

> Ads on Facebook and Instagram that match a keyword, from the Meta Ad Library: advertiser, text, dates and links. ₹0.28 per page; a result that finds nothing is ₹0.

## What it does

Ads on Facebook and Instagram that match a keyword, from Meta's public Ad Library, across every advertiser: data.searchResults[] with each ad's advertiser page (page_name, page_id), start and end dates, is_active, the platforms it runs on and the snapshot (body text, title, cta_text, link_url, images and videos), plus data.cursor for the next page and the total count. Filter with country (two-letter code, default ALL), status (ACTIVE or ALL), media_type and a date window.

Use it to find who advertises on a theme or product and what their hooks are; for every ad of one known brand use [`get_meta_ads`](https://parel.si/docs/tools/get_meta_ads.md), for Google ads [`get_google_ads`](https://parel.si/docs/tools/get_google_ads.md), for LinkedIn [`search_linkedin_ads`](https://parel.si/docs/tools/search_linkedin_ads.md). Generic words match loosely, so expect some off-topic rows. Flat price per page; a keyword with no ads is free.

India: country "IN".

## Inputs

Generated from the contract captured from staging on 2026-11-17.

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | The keyword or phrase the ads should contain. |
| `cursor` | string | no | The cursor from the previous answer, for the next page. |
| `status` | string | no | ACTIVE (default) or ALL. |
| `ad_type` | string | no | all (default) or political_and_issue_ads. |
| `country` | string | no | Two-letter country code ("IN"), or ALL (default). |
| `sort_by` | `total_impressions` or `relevancy_monthly_grouped` | no | total_impressions (default) or relevancy_monthly_grouped. It orders the ads; it does not mean spend or reach figures come back. |
| `end_date` | string | no | Only ads shown on or before this date, YYYY-MM-DD. |
| `media_type` | string | no | ALL (default), IMAGE, VIDEO or MEME (text with an image). |
| `start_date` | string | no | Only ads shown on or after this date, YYYY-MM-DD. |
| `search_type` | string | no | keyword_unordered (default, any order) or keyword_exact_phrase. |

## What drives the cost

Flat per page of about thirty ads; pass cursor for the next page. Answers are trimmed to the text, links and first image, about 70 KB. A result that finds nothing is `class: "ok_free"`, ₹0. The timeout is 30 seconds.

## Price today

| | |
|---|---|
| Price today | **₹0.28** per page (`cost_paise: 28`) at ₹93.93 per US dollar on 17 November 2026 |
| Hold before the call | ₹0.42 (`hold_paise: 42`); when the call settles the real price is charged and the unused part is released |
| ₹0 when | it fails, or the provider answers but there is nothing in it (an empty list, no email, no page): `class: "ok_free"`, ₹0 |
| Timeout | 30 s, then `upstream_timeout` (₹0, retryable) |
| Over MCP | `run_tool` with `tool: "search_meta_ads"` |
| Over REST | `POST https://api.parel.si/v1/run` with `"tool": "search_meta_ads"` |
| Confirmation | not needed (the estimate is under the ₹200 threshold) |

## Request

```bash
curl https://api.parel.si/v1/run \
  -H "Authorization: Bearer $PAREL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"search_meta_ads","input":{"query":"protein powder","country":"IN"}}'
```

## What comes back

`data`, as the live check of 2026-11-17 recorded it, trimmed:

```json
{
  "searchResultsCount": 4163,
  "cursor": "AQHTQgMg1qEmjVI9xUMFDZ8318Fu8YXtYNgORHfyaHQ9ktRHugrAxAMH4PlirchdiYle",
  "searchResults": [
    {
      "ad_archive_id": "2131552947327013",
      "url": "https://www.facebook.com/ads/library?id=2131552947327013",
      "page_id": "271312889545862",
      "page_name": "BigMuscles Nutrition",
      "is_active": true,
      "start_date_string": "2025-06-08T07:00:00.000Z",
      "end_date_string": "2026-11-16T08:00:00.000Z",
      "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "AUDIENCE_NETWORK"
      ],
      "collation_count": 1,
      "spend": null,
      "reach_estimate": null,
      "snapshot": {
        "body": {
          "text": "[filled from the advertiser catalogue: product brand]"
        },
        "title": "[filled from the advertiser catalogue: product name]",
        "caption": "https://www.bigmusclesnutrition.com/collections/wh...",
        "link_description": "[filled from the advertiser catalogue: product description]",
        "link_url": "https://www.bigmusclesnutrition.com/collections/whey-protein-1/products/premium-gold-whey-protein-1?variant=40900235133027",
        "cta_text": "Order now",
        "display_format": "DCO",
        "page_categories": [
          "Vitamins/supplements"
        ],
        "page_like_count": 98330,
        "images": [],
        "videos": [],
        "cards": [
          {
            "title": "Gold Whey is Easy to Digest. Hard to Beat.",
            "body": "WARNING: Are you tired of feeling sore after a workout?\n\nIntroducing Premium Gold Whey by BigMuscles!\n25g of high-quality whey protein per scoop\nEnhanced with ProHydrolase enzyme tech for faster recovery\n\nNo sugar, no fillers. Just pure pow…"
          },
          {
            "title": "Gold Whey is Easy to Digest. Hard to Beat.",
            "body": "WARNING: Are you tired of feeling sore after a workout?\n\nIntroducing Premium Gold Whey by BigMuscles!\n25g of high-quality whey protein per scoop\nEnhanced with ProHydrolase enzyme tech for faster recovery\n\nNo sugar, no fillers. Just pure pow…"
          },
          {
            "title": "Gold Whey is Easy to Digest. Hard to Beat.",
            "body": "WARNING: Are you tired of feeling sore after a workout?\n\nIntroducing Premium Gold Whey by BigMuscles!\n25g of high-quality whey protein per scoop\nEnhanced with ProHydrolase enzyme tech for faster recovery\n\nNo sugar, no fillers. Just pure pow…"
          }
        ]
      }
    },
    {
      "ad_archive_id": "1001015195732590",
      "url": "https://www.facebook.com/ads/library?id=1001015195732590",
      "page_id": "271312889545862",
      "page_name": "BigMuscles Nutrition",
      "is_active": true,
      "start_date_string": "2026-05-29T07:00:00.000Z",
      "end_date_string": "2026-11-16T08:00:00.000Z",
      "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "AUDIENCE_NETWORK"
      ],
      "collation_count": 1,
      "spend": null,
      "reach_estimate": null,
      "snapshot": {
        "body": {
          "text": "Gold Whey Isolate - 90% Isolate Protein. Packed with 7 Natural Ingredients."
        },
        "title": "BigMuscles Nutrition",
        "caption": "bigmusclesnutrition.com",
        "link_description": "Experience ultra-pure whey protein isolate with 27g protein per scoop. Clean Label Certified, made from cow milk, and imported from Europe. Price ₹1899",
        "link_url": "https://www.bigmusclesnutrition.com/collections/whey-protein-1/products/gold-whey-isolate",
        "cta_text": "See details",
        "display_format": "CAROUSEL",
        "page_categories": [
          "Vitamins/supplements"
        ],
        "page_like_count": 98330,
        "images": [],
        "videos": [],
        "cards": [
          {
            "title": "Pure Whey Protein Isolate 90% | BigMuscles Nutrition",
            "body": "Experience ultra-pure whey protein isolate with 27g protein per scoop. Clean Label Certified, made from cow milk, and imported from Europe. Price ₹1899"
          },
          {
            "title": "Made from 7 Natural Ingredients Only - Gold Whey Isolate",
            "body": "Crafted from 7 pure ingredients including whey isolate, natural cocoa, Himalayan salt, and pineapple enzyme. No hidden additives — 100% transparency, 100% purity."
          },
          {
            "title": "Simply Natural Goodness | Free from Artificial Additives",
            "body": "No artificial flavors, preservatives, gums, or thickeners. Gluten-free, soy-free, and amino-spike-free for clean, natural, and gut-friendly protein nourishment."
          }
        ]
      }
    },
    {
      "ad_archive_id": "2525139057905385",
      "url": "https://www.facebook.com/ads/library?id=2525139057905385",
      "page_id": "271312889545862",
      "page_name": "BigMuscles Nutrition",
      "is_active": true,
      "start_date_string": "2026-05-27T07:00:00.000Z",
      "end_date_string": "2026-11-16T08:00:00.000Z",
      "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "AUDIENCE_NETWORK"
      ],
      "collation_count": 1,
      "spend": null,
      "reach_estimate": null,
      "snapshot": {
        "body": {
          "text": "[filled from the advertiser catalogue: product brand]"
        },
        "title": "[filled from the advertiser catalogue: product name]",
        "caption": "https://www.bigmusclesnutrition.com/collections/wh...",
        "link_description": "[filled from the advertiser catalogue: product description]",
        "link_url": "https://www.bigmusclesnutrition.com/collections/whey-protein-1/products/premium-gold-whey-protein-1?variant=40900235133027",
        "cta_text": "Order now",
        "display_format": "DCO",
        "page_categories": [
          "Vitamins/supplements"
        ],
        "page_like_count": 98330,
        "images": [],
        "videos": [],
        "cards": [
          {
            "title": "Gold Whey is Easy to Digest. Hard to Beat.",
            "body": "Train harder. Recover faster. Perform better.\nPremium Gold Whey by BigMuscles delivers 25g of high-quality whey protein per scoop, enhanced with ProHydrolase® enzyme technology for faster digestion, better absorption, and maximum muscle rec…"
          },
          {
            "title": "Gold Whey is Easy to Digest. Hard to Beat.",
            "body": "Train harder. Recover faster. Perform better.\nPremium Gold Whey by BigMuscles delivers 25g of high-quality whey protein per scoop, enhanced with ProHydrolase® enzyme technology for faster digestion, better absorption, and maximum muscle rec…"
          },
          {
            "title": "Gold Whey is Easy to Digest. Hard to Beat.",
            "body": "Train harder. Recover faster. Perform better.\nPremium Gold Whey by BigMuscles delivers 25g of high-quality whey protein per scoop, enhanced with ProHydrolase® enzyme technology for faster digestion, better absorption, and maximum muscle rec…"
          }
        ]
      }
    }
  ]
}
```

## Notes

- Flat per page of about thirty ads; pass cursor for the next page. Answers are trimmed to the text, links and first image, about 70 KB.
- Keyword matching is loose: generic words bring off-topic advertisers, so filter by page_name.
- Spend and reach appear only where Meta publishes them (EU and political ads); elsewhere they are empty.

## Siblings

- [`get_meta_ads`](https://parel.si/docs/tools/get_meta_ads.md)
- [`get_google_ads`](https://parel.si/docs/tools/get_google_ads.md)
- [`search_linkedin_ads`](https://parel.si/docs/tools/search_linkedin_ads.md)
