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

# get_meta_ads

> The ads a brand is running on Facebook and Instagram, from the Meta Ad Library: creative, text, dates, platforms. ₹0.28 per page; a brand with no ads is ₹0.

## What it does

The ads one advertiser is running, from Meta's public Ad Library, by `companyName` (its page name) or `pageId`: `data.results[]` with `ad_archive_id`, `start_date`, `end_date`, `is_active`, `publisher_platform[]` and the `snapshot` (`body`, `title`, `caption`, `cta_text`, `link_url`, `images`, `videos`), with `data.cursor` for the next page. Filter with `country`, `status` and `media_type`. Use it to see a competitor's live creatives and how long they have run; for the brand's organic posts use [`get_social_posts`](https://parel.si/docs/tools/get_social_posts.md).

India: `country: "IN"`.

## Inputs

Generated from the contract captured from staging on 2026-11-05. This tool declares one-of sets: `companyName` or `pageId` must be present, or it is `invalid_input` for ₹0.

| Field | Type | Required | Description |
|---|---|---|---|
| `trim` | boolean | no | Set to true for a trimmed down version of the response. e.g. "false" |
| `cursor` | string | no | Cursor to paginate through results. e.g. "AQHRBUAxNmFlxBVMFL6uTb1ICFsV65O4SqmPbcVZJhiveBpPS1hFHAmL6yCJcF760cXP" |
| `pageId` | string | one of | The companies ad library page id. You can get this with my Search For Companies Endpoint. Can either use this or companyName. e.g. "367152833370567" |
| `status` | string | no | Status of the ad. Defaults to ACTIVE.. e.g. "ACTIVE" |
| `country` | string | no | This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.. e.g. "ALL" |
| `sort_by` | string | no | Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.. e.g. "total_impressions" |
| `end_date` | string | no | End date to search for. Format: YYYY-MM-DD. e.g. "2025-12-31" |
| `language` | string | no | Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc. e.g. "EN" |
| `media_type` | string | no | Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme.. e.g. "ALL" |
| `start_date` | string | no | Start date to search for. Format: YYYY-MM-DD. e.g. "2025-01-01" |
| `companyName` | string | one of | The name of the company. Can either use this or pageId. e.g. "Lululemon" |

One of these sets must be complete (anything else is `invalid_input`, ₹0): `companyName`; `pageId`.

## What drives the cost

Nothing: flat per page of about 30 ads. The response is large (around 200 KB): over MCP it is cut to whole ads with a `_truncated` note, REST returns everything. An empty result is `class: "ok_free"`, ₹0.

## 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: "get_meta_ads"` |
| Over REST | `POST https://api.parel.si/v1/run` with `"tool": "get_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":"get_meta_ads","input":{"country":"IN","companyName":"Mamaearth"}}'
```

## What comes back

`data.results[]`, `data.searchResultsCount`, `data.cursor`. A real answer recorded during the live check of 2026-10-28, trimmed to two ads:

```json
{
  "success": true,
  "results": [
    {
      "ad_archive_id": "1575470834177468",
      "collation_count": null,
      "collation_id": null,
      "is_active": true,
      "page_id": "619181354927737",
      "page_is_deleted": false,
      "snapshot": {
        "branded_content": null,
        "page_id": "619181354927737",
        "page_is_deleted": false,
        "page_profile_uri": "https://www.facebook.com/Mamaearthindia/",
        "root_reshared_post": null,
        "byline": null,
        "disclaimer_label": null,
        "page_name": "Mamaearth",
        "page_profile_picture_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/657025374_1258899409681193_7421290957540838777_n.jpg",
        "event": null,
        "caption": "mamaearth.in",
        "cta_text": "Shop now",
        "cards": [
          {
            "body": "Heard you wanted a Price Drop? Here you go!🥳Get Insane price drops on your favourite products😍.\nGrab the goodness of nature now. Shop Now.",
            "cta_type": "SHOP_NOW",
            "caption": "mamaearth.in",
            "link_description": "Mamaearth",
            "link_url": "https://mamaearth.in/product/rosemary-anti-hair-fall-combo-500-ml",
            "title": "Rosemary Anti-Hair Fall Combo - 500 ml",
            "cta_text": "Shop Now",
            "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-iad3-2.xx.fbcdn.net/v/t39.35426-6/655952949_1828199094519162_2856887411413812742_n.jpg",
            "resized_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/655952949_1828199094519162_2856887411413812742_n.jpg",
            "watermarked_resized_image_url": ""
          },
          {
            "body": "Heard you wanted a Price Drop? Here you go!🥳Get Insane price drops on your favourite products😍.\nGrab the goodness of nature now. Shop Now.",
            "cta_type": "SHOP_NOW",
            "caption": "mamaearth.in",
            "link_description": "Mamaearth",
            "link_url": "https://mamaearth.in/product/multani-mitti-face-wash-with-multani-mitti-bulgarian-rose-for-oil-control-acne-100-ml",
            "title": "Multani Mitti Face Wash for Acne-100ml",
            "cta_text": "Shop Now",
            "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-iad6-1.xx.fbcdn.net/v/t39.35426-6/657952624_1142423604615887_4899537850598341115_n.jpg",
            "resized_image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/657952624_1142423604615887_4899537850598341115_n.jpg",
            "watermarked_resized_image_url": ""
          },
          "… 4 more item(s) truncated"
        ],
        "body": {
          "text": "Heard you wanted a Price Drop? Here you go!🥳Get Insane price drops on your favourite products😍.\nGrab the goodness of nature now. Shop Now."
        },
        "cta_type": "SHOP_NOW",
        "display_format": "DPA",
        "link_description": "Mamaearth",
        "link_url": "http://mamaearth.in/",
        "images": [],
        "page_categories": [
          "Baby goods/kids goods"
        ],
        "page_like_count": 484547,
        "title": "Rosemary Anti-Hair Fall Combo - 500 ml",
        "videos": [],
        "is_reshared": false,
        "extra_links": [],
        "extra_texts": [],
        "extra_images": [],
        "extra_videos": [],
        "country_iso_code": null,
        "brazil_tax_id": null,
        "additional_info": null,
        "ec_certificates": []
      },
      "has_user_reported": false,
      "report_count": null,
      "menu_items": [],
      "state_media_run_label": null,
      "page_name": "Mamaearth",
      "impressions_with_index": {
        "impressions_text": null,
        "impressions_index": -1
      },
      "gated_type": "ELIGIBLE",
      "categories": [
        "UNKNOWN"
      ],
      "is_aaa_eligible": false,
      "contains_digital_created_media": false,
      "reach_estimate": null,
      "currency": "",
      "spend": null,
      "end_date": 1793170800,
      "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "… 2 more item(s) truncated"
      ],
      "start_date": 1777359600,
      "contains_sensitive_content": false,
      "total_active_time": null,
      "regional_regulation_data": {
        "finserv": {
          "is_deemed_finserv": false,
          "is_limited_delivery": false
        },
        "tw_anti_scam": {
          "is_limited_delivery": false
        }
      },
      "hide_data_status": "NONE",
      "fev_info": null,
      "ad_id": null,
      "targeted_or_reached_countries": [],
      "url": "https://www.facebook.com/ads/library?id=1575470834177468",
      "start_date_string": "2026-04-28T07:00:00.000Z",
      "end_date_string": "2026-10-28T07:00:00.000Z"
    },
    {
      "ad_archive_id": "1297573992514723",
      "collation_count": null,
      "collation_id": null,
      "is_active": true,
      "page_id": "619181354927737",
      "page_is_deleted": false,
      "snapshot": {
        "branded_content": null,
        "page_id": "619181354927737",
        "page_is_deleted": false,
        "page_profile_uri": "https://www.facebook.com/Mamaearthindia/",
        "root_reshared_post": null,
        "byline": null,
        "disclaimer_label": null,
        "page_name": "Mamaearth",
        "page_profile_picture_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/658148219_1898203517563872_4989264418472397500_n.jpg",
        "event": null,
        "caption": "mamaearth.in",
        "cta_text": "Shop now",
        "cards": [
          {
            "body": "Say no to toxins and yes to nature! Shop your favorite natural products and get Upto 25% Off. Use Code: SAVE25",
            "cta_type": "SHOP_NOW",
            "caption": "mamaearth.in",
            "link_description": "Upto 25% Off | Code: SAVE25",
            "link_url": "https://mamaearth.in/product/glow-serum-bb-cream-with-vitamin-c-turmeric-25-g",
            "title": "BB Cream Glow Serum SPF 30 PA++ with Vitamin C -25g",
            "cta_text": "Shop Now",
            "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-iad6-1.xx.fbcdn.net/v/t39.35426-6/658474464_970677765465092_4627052752500854270_n.jpg",
            "resized_image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.35426-6/658474464_970677765465092_4627052752500854270_n.jpg",
            "watermarked_resized_image_url": ""
          },
          {
            "body": "Say no to toxins and yes to nature! Shop your favorite natural products and get Upto 25% Off. Use Code: SAVE25",
            "cta_type": "SHOP_NOW",
            "caption": "mamaearth.in",
            "link_description": "Upto 25% Off | Code: SAVE25",
            "link_url": "https://mamaearth.in/product/rosemary-anti-hair-fall-combo-500-ml",
            "title": "Rosemary Anti-Hair Fall Combo - 500 ml",
            "cta_text": "Shop Now",
            "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-iad3-2.xx.fbcdn.net/v/t39.35426-6/659112890_974006254963653_7815437150465029761_n.jpg",
            "resized_image_url": "https://scontent-iad3-2.xx.fbcdn.net/v/t39.35426-6/659112890_974006254963653_7815437150465029761_n.jpg",
            "watermarked_resized_image_url": ""
          },
          "… 4 more item(s) truncated"
        ],
        "body": {
          "text": "Say no to toxins and yes to nature! Shop your favorite natural products and get Upto 25% Off. Use Code: SAVE25"
        },
        "cta_type": "SHOP_NOW",
        "display_format": "DPA",
        "link_description": "Upto 25% Off | Code: SAVE25",
        "link_url": "http://mamaearth.in/",
        "images": [],
        "page_categories": [
          "Baby goods/kids goods"
        ],
        "page_like_count": 484547,
        "title": "BB Cream Glow Serum SPF 30 PA++ with Vitamin C -25g",
        "videos": [],
        "is_reshared": false,
        "extra_links": [],
        "extra_texts": [],
        "extra_images": [],
        "extra_videos": [],
        "country_iso_code": null,
        "brazil_tax_id": null,
        "additional_info": null,
        "ec_certificates": []
      },
      "has_user_reported": false,
      "report_count": null,
      "menu_items": [],
      "state_media_run_label": null,
      "page_name": "Mamaearth",
      "impressions_with_index": {
        "impressions_text": null,
        "impressions_index": -1
      },
      "gated_type": "ELIGIBLE",
      "categories": [
        "UNKNOWN"
      ],
      "is_aaa_eligible": false,
      "contains_digital_created_media": false,
      "reach_estimate": null,
      "currency": "",
      "spend": null,
      "end_date": 1793170800,
      "publisher_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "… 2 more item(s) truncated"
      ],
      "start_date": 1777359600,
      "contains_sensitive_content": false,
      "total_active_time": null,
      "regional_regulation_data": {
        "finserv": {
          "is_deemed_finserv": false,
          "is_limited_delivery": false
        },
        "tw_anti_scam": {
          "is_limited_delivery": false
        }
      },
      "hide_data_status": "NONE",
      "fev_info": null,
      "ad_id": null,
      "targeted_or_reached_countries": [],
      "url": "https://www.facebook.com/ads/library?id=1297573992514723",
      "start_date_string": "2026-04-28T07:00:00.000Z",
      "end_date_string": "2026-10-28T07:00:00.000Z"
    },
    "… 28 more item(s) truncated"
  ],
  "searchResultsCount": 585,
  "cursor": "AQHTU69qDSfPrGp52UX3YJp_9aLK_uZZ_AGQLGxtCFRLo8x-tq5cLFkLhM6il4azFElv"
}
```

## Notes

- About 30 ads per page, around 200 KB: cut to whole ads over MCP, complete over REST. Pass cursor for the next page.
- companyName must match the page name as Meta shows it; a brand with no ads returns an empty list, which is free.
- Spend and reach are only present where Meta publishes them (EU and political ads).

## Siblings

- [`get_social_posts`](https://parel.si/docs/tools/get_social_posts.md) for the same brand's organic Instagram posts.
- [`search_amazon`](https://parel.si/docs/tools/search_amazon.md) for how its products are priced.
