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

# Meta Ads Library API

> Every ad a brand runs in Meta's Ad Library: creative, headline, CTA, link, dates, format, platforms, advertiser, and EU reach where disclosed.

`POST /v1/data/facebook/ads/run`

**Pricing:** $0.005 per ad ($5.00 per 1,000).

Give a Facebook page URL or handle; set how many ads to return and whether to include inactive ads.

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**urls** `string` *required*

The advertiser's Facebook page URL or handle (e.g. facebook.com/nike), or its Instagram profile URL (e.g. instagram.com/nike).

Format e.g. `https://www.facebook.com/nike`.

**maxResults** `integer`

Number of ads to return in total. Use 0 for all.

**activeStatus** `string` (default: active)

Which ads to return.

Allowed values: `active` (Active only), `inactive` (Inactive only).

**isDetailsPerAd** `boolean` (default: true)

Pull each ad's advertiser profile and EU transparency block. Keep on for the full record.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/facebook/ads/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "urls": "https://www.facebook.com/nike",
    "maxResults": 50,
    "activeStatus": "active",
    "isDetailsPerAd": true
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/facebook/ads/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "urls": "https://www.facebook.com/nike",
    "maxResults": 50,
    "activeStatus": "active",
    "isDetailsPerAd": True
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/facebook/ads/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "urls": "https://www.facebook.com/nike",
  "maxResults": 50,
  "activeStatus": "active",
  "isDetailsPerAd": true
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one ad, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `adUrl` | Ad URL | url |
| `libraryId` | Library ID | text |
| `pageUrl` | Page URL | url |
| `headline` | Headline | text |
| `bodyText` | Body Text | text |
| `linkDescription` | Link Description | text |
| `ctaText` | CTA Text | text |
| `destinationUrl` | Destination URL | url |
| `format` | Format | text |
| `startDate` | Start Date | datetime |
| `endDate` | End Date | datetime |
| `daysActive` | Days Active | number |
| `isActive` | Is Active | text |
| `mediaUrl` | Media URL | url |
| `mediaType` | Media Type | text |
| `platforms` | Platforms | array |
| `advertiser` | Advertiser | object |
| `cards` | Cards | object\_array |
| `euReach` | EU Reach | object |
| `reachBreakdown` | Reach Breakdown | object\_array |
| `variantCount` | Variant Count | number |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "facebook/ads",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "headline": "{{product.name}}",
      "variantCount": null,
      "format": "DPA",
      "reachBreakdown": [],
      "startDate": "2025-04-25T07:00:00.000Z",
      "mediaType": "Carousel",
      "ctaText": "Install now",
      "endDate": "2026-08-16T07:00:00.000Z",
      "euReach": null,
      "cards": [
        {
          "title": "Calzado para hombre Nike Blazer Mid '77 SE - Blanco",
          "body": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los beneficios que la Nike App tiene para ti 😎. ¡Descárgala ahora!",
          "cta": "Install Now",
          "linkUrl": "https://www.nike.com/mx/t/calzado-blazer-mid-77-se-j99WT3?cp=54413048966_soc_",
          "imageUrl": "https://scontent-sea5-1.xx.fbcdn.net/v/t39.35426-6/400107091_3246840442276703_8782322399633680368_n.jpg?_nc_cat=110&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=MQlz7wKieq...",
          "videoUrl": null
        },
        {
          "title": "Calzado para mujer Nike Air Force 1 '07 - Blanco",
          "body": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los beneficios que la Nike App tiene para ti 😎. ¡Descárgala ahora!",
          "cta": "Install Now",
          "linkUrl": "https://www.nike.com/mx/t/calzado-air-force-1-07-WGq1wQ?cp=54413048966_soc_",
          "imageUrl": "https://scontent-sea5-1.xx.fbcdn.net/v/t39.35426-6/400057885_876651337399777_1711677532442992421_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=YG8lNp3X2d4...",
          "videoUrl": null
        }
      ],
      "isActive": true,
      "libraryId": "1559738104701476",
      "bodyText": "Encuentra tu mejor estilo.\nLlegó el momento de que disfrutes los beneficios que la Nike App tiene para ti 😎. ¡Descárgala ahora!",
      "destinationUrl": "http://play.google.com/store/apps/details?id=com.nike.omega",
      "adUrl": "https://www.facebook.com/ads/library/?id=1559738104701476",
      "platforms": [
        "FACEBOOK",
        "INSTAGRAM"
      ],
      "advertiser": {
        "category": "Sportswear Store",
        "igUsername": "nike",
        "igFollowers": 291487540,
        "pageLikes": 39566881,
        "verification": "BLUE_VERIFIED",
        "photoUrl": "https://scontent-mia5-1.xx.fbcdn.net/v/t39.30808-1/284964043_10159903868513445_7696353984967674128_n.jpg?stp=dst-jpg_s148x148_tt6&_nc_cat=102&ccb=1-7&_nc_sid..."
      },
      "linkDescription": null,
      "daysActive": 478,
      "pageUrl": "https://www.facebook.com/nike/",
      "mediaUrl": "https://scontent-sea5-1.xx.fbcdn.net/v/t39.35426-6/400107091_3246840442276703_8782322399633680368_n.jpg?_nc_cat=110&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=MQlz7wKieq..."
    }
  ]
}
```

## Related APIs

For TikTok ads use [`tiktok/ads`](https://docs.mindcase.co/apis/tiktok/ads); for Google ads use [`google-ads/ads`](https://docs.mindcase.co/apis/google-ads/ads); for LinkedIn ads use [`linkedin/ads-library`](https://docs.mindcase.co/apis/linkedin/ads-library).


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