Meta Ad Librarymeta.advertisers.ads.list

Meta advertiser ads API

The ads one advertiser (a Facebook page) runs in the Meta Ad Library, by the page ID or the brand's name: copy, creative, landing page, platforms and dates. The way to see what a competitor is running now.

GEThttps://api.okdata.online/v1/meta/advertisers/ads/list

Price

One call costs $0.004 and returns one page of about 30 ads. Collecting 1,000 ads takes about 34 calls, $0.136 in total. Each page is a separate call; failed calls are not charged.

Parameters

NameTypeDescription
idstringThe advertiser's Facebook page ID. Give id or name. e.g. 30147264485
namestringThe advertiser's name as on its Facebook page. Give id or name. e.g. Stanley 1913
countrystringOnly ads shown in this country (ISO code); all countries when left out. e.g. US
statusstringactiveinactiveallAds running now (the default), stopped ones, or both. default active
mediastringallimagevideoOnly image or only video ads; all by default. default all
sortstringimpressionsnewestMost impressions first (the default) or newest first. default impressions
cursorstringOpaque cursor from page.next_cursor of the previous call. Each page is a separate call.
viewstringcompactstandardfullHow much of each object comes back. full adds platform-specific fields under ext. default standard
fieldsstringComma-separated fields to keep, to save tokens.

cursor, view and fields work the same on every endpoint: how requests work.

Returned fields

Each item is a Ad.

FieldTypeDescription
idstringAd ID in the library.
urlstringLink to the ad in the library.
advertiserAdvertiserRefWho runs the ad.
titlestring | nullHeadline, where the ad has one.
textstringAd copy as plain text; empty when the ad has none.
formatstring | nullCreative format; dynamic means the platform assembles it per viewer (catalog ads).
imagesstring[] | nullImage URLs of the creative.
videosstring[] | nullVideo URLs of the creative.
landing_urlstring | nullWhere the ad leads.
ctastring | nullCall-to-action button text.
platformsstring[] | nullWhere it is delivered, e.g. facebook, instagram.
activeboolean | nullWhether the ad is still running.
first_shown_atstring | nullFirst time or day shown, ISO 8601 in UTC.
last_shown_atstring | nullLast time or day shown, ISO 8601 in UTC.
reachstring | nullPeople reached, as the library publishes it: a bracket such as 1K-10K, or a count (the EU reach of a Meta ad); null where none is published.
extobjectPlatform-specific extras. Only returned with view=full.

Request

cURL
curl -G "https://api.okdata.online/v1/meta/advertisers/ads/list" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'id=30147264485'
Python
import os
import requests

resp = requests.get(
    "https://api.okdata.online/v1/meta/advertisers/ads/list",
    headers={"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"},
    params={"id": "30147264485"},
    timeout=60,
)
body = resp.json()
if body["code"] != "ok":
    raise RuntimeError(f"{body['code']}: {body['message']} (charged: {body['charged']})")

for row in body["data"]["items"]:
    print(row["advertiser"]["name"], row["first_shown_at"], row["text"][:60])
print("cost: $" + body["meta"]["billing"]["amount"])
TypeScript
const url = new URL('https://api.okdata.online/v1/meta/advertisers/ads/list');
url.searchParams.set('id', "30147264485");

const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.OKDATA_API_KEY}`,
  },
});
const body = await res.json();
if (body.code !== 'ok') throw new Error(`${body.code}: ${body.message}`);

for (const row of body.data.items) {
  console.log(row.advertiser.name, row.first_shown_at, row.text.slice(0, 60));
}
console.log('cost: $' + body.meta.billing.amount);
MCPtools/call
{
  "name": "call",
  "arguments": {
    "endpoint": "meta.advertisers.ads.list",
    "params": {
      "id": "30147264485"
    }
  }
}

Or ask an agent that has the MCP server connectedUse Meta advertiser ads and sum up what these ads promise, which offers they push and since when.

Response

200 · application/jsonmeta.billing.amount = 0.004
{
  "code": "ok",
  "request_id": "0f6c2a8e-4b1d-4e0a-9a51-3c7d2b9e1f20",
  "data": {
    "items": [
      {
        "id": "1856995242318099",
        "url": "https://www.facebook.com/ads/library/?id=1856995242318099",
        "advertiser": {
          "id": "30147264485",
          "name": "Stanley 1913",
          "url": "https://www.facebook.com/Stanley1913/"
        },
        "title": "The Holiday Collection",
        "text": "Great gifts. Under $50. No compromise.",
        "format": "carousel",
        "images": [
          "https://cdn.example.com/ad/1.jpg"
        ],
        "videos": null,
        "landing_url": "https://www.stanley1913.com/collections/gifts-under-50",
        "cta": "Shop now",
        "platforms": [
          "facebook",
          "instagram"
        ],
        "active": true,
        "first_shown_at": "2026-11-10T08:00:00Z",
        "last_shown_at": "2026-11-11T08:00:00Z",
        "reach": null
      }
    ]
  },
  "page": {
    "next_cursor": "eyJvIjoyMH0",
    "has_more": true
  },
  "warnings": [],
  "meta": {
    "capability": "meta.advertisers.ads.list",
    "billing": {
      "amount": "0.004",
      "currency": "USD",
      "balance_after": "9.996"
    },
    "unavailable": {},
    "cached": false,
    "replayed": false,
    "fetched_at": "2026-11-11T08:00:00Z"
  }
}

Try it

This sends a real call to https://api.okdata.online and is billed as usual: at most $0.004. Failed calls are free. Your key goes only to that address and is never stored on this site.

Questions

How much does the Meta advertiser ads API cost?

One call costs $0.004 and returns one page of about 30 ads. Collecting 1,000 ads takes about 34 calls, $0.136 in total. Each page is a separate call; failed calls are not charged.

How do I get the next page?

Pass page.next_cursor from the response back as the cursor parameter. When page.has_more is false there is nothing left. Every page is its own call at $0.004.

Do I need a Meta Ad Library account, cookies or a QR login?

No. You send only your okdata API key. The data is public data from Meta Ad Library; nothing is fetched with your own Meta Ad Library account.

Am I charged when a call fails?

No. Every error response says charged: false, except a timeout, which says charged: null until the outcome is known. Resend with the same Idempotency-Key and you are never charged twice.

What if Meta Ad Library does not show a field?

The field is null, and meta.unavailable names it with the reason: platform (the platform never shows it) or capability (we cannot fetch it yet).

Answers that use this endpoint

All Meta Ad Library endpoints → · Answers