Meta ad library API (/api/v1/adlibrary)

This supplements the API reference. Use GET /api/v1/adlibrary (or the legacy alias GET /api/adlibrary) with your API key to search Meta (Facebook / Instagram) ads programmatically.

Path note: /api/v1/adlibrary is canonical; /api/adlibrary is a supported metered alias. Examples below use /api/v1/... for programmatic calls. Tracked brands over an API key (GET /api/v1/brands) and session brand-detail tabs are documented in Brands & Brand tracker.

MCP tool (Meta ads)#

• search_facebook_ads — same underlying flow as GET /api/v1/adlibrary (keyword, country, page, sort).
• find_winning_products — adlibrary-backed winning-products view (forces winning-score + product-page filters for product discovery).
• creative_inspiration_pack — adlibrary-backed shortlist with hooks, landing pages, and media mix.
• brief_competitor — quick competitor brief from adlibrary + store/tracker signals.
• scan_ad — ad-id/url scanner with hook + scaling verdict from available signals.

For MCP sort_by on search_facebook_ads and find_winning_products, use: relevance, datefound, lastseen, adspend, longestrunning, reach, adsetamount, consistency, monthlyvisits, pageactiveads. Aliases created, date, recent, last_ad_started, and first_ad_started are normalized automatically by MCP.

Setup: MCP. Parameters: MCP · tools reference. For list_tracked_brands, see Brands.

Shared auth and metering (/api/v1/adlibrary, /api/v1/brands)#

Both /api/v1/adlibrary and /api/v1/brands share the same metering and auth rules. Brand detail routes under /api/brands/* are session-only — see Brands.

• API key: X-API-Key, Authorization: Bearer, or ?api_key= (see API reference).
• Session: If the visitor is already logged in, the same routes can run without a key; the active user must still meet the API access check below.
• Plan: Account must include API access. Otherwise 403.
• Credits / rate limit: Monthly API credits and 60 requests per minute per user. On exhaustion, 429 with a JSON error and optional credits object.

When you use an API key without an existing browser session, the server still resolves the key to your account for that request so behavior matches the dashboard.

GET /api/v1/adlibrary — Meta / Facebook winning ads list#

Alias: GET /api/adlibrary — same metering and parameters.

UI equivalent: The in-app Meta ads views call /api/fb-ads (or /api/fb-ads-winning) with the same query shape. For integration, copy a working request from your browser’s network tab and swap the path to /api/v1/adlibrary (or /api/adlibrary), keeping the same query keys and values.

Entry guard (required query keys)#

The endpoint only returns its main JSON payload when all of the following keys are present in the query string (empty string is allowed):

searchkeyword, keyword, min, countries, from, to, sorting, mediafilter, page, max, scroll, scaling, niches, fromlastseen, tolastseen, activestatus

If any are missing, the response is not the usual list payload (avoid this in clients).

Additionally, the inner gate requires trial set in the query or a logged-in / API-key–resolved session. With a valid X-API-Key, you meet the session requirement automatically. Otherwise the response is:

{"error":"logged_out"}

All query parameters#

Everything below is read from the query string (same shape as /api/fb-ads in the app).

isset gate (must be present; empty string is OK)#

Same list as Entry guard above:
searchkeyword, keyword, min, max, countries, from, to, sorting, mediafilter, page, scroll, scaling, niches, fromlastseen, tolastseen, activestatus.

Strongly recommended on every request#

The handler reads website, languages, pagetypefilter, sortdirection, apps, and themes without going through that isset list. Mirror the dashboard and send at least website=All, languages=All, pagetypefilter= (empty = all page types), sortdirection=desc, apps=All, themes=All so behavior matches the UI and optional keys are always defined.

Auth / session / trial#

Pagination, cursor, de-duplication#

Keyword search#

Active ads, scaling, media, page type, adscore, impressions#

Sorting#

Spend, reach (with window), traffic, days running, price, copy, video length, active ads on page#

Dates (strings, typically Y-m-d)#

Open-ended date ranges are normalized server-side (e.g. only from set → to may be set to match from).

Catalog: countries, stores, niches, languages, apps, themes, excludes#

Deep links, shuffle, caps#

Validation / errors#

Invalid min or max (outside 0…90000000) can yield {"error":"value_not_in_range_1"} or _2, or a non-JSON false body in edge cases.

Discovering valid niches and themes (no API key on these routes)#

Integrations should learn allowed values from discovery JSON, not from guessing:

Preset niche shortcuts (UI “chips”): The app also exposes human-facing two-letter codes (e.g. CG, BY, SP) in the niche filter. Those are valid segments in niches= the same way the browser sends them.

Path / numeric niche segments: Values are resolved using the server’s niche catalog (paths like /Apparel/... and numeric ids map to canonical names in search). If a segment is unknown, it may be passed through as-is — prefer /api/niche-counts over inventing strings.

Note: /api/niche-counts and /api/themes are discovery helpers and do not consume Meta ad library API credits the same way /api/adlibrary does. Your deployment may still require login or other policy in front of these routes.

Feature gates (upgrade JSON)#

For accounts without the required product tier, certain filters or sort modes return 200 with a small JSON body (upgrade prompt is in-band, not always HTTP 403):

Other notable responses#

• {"message":"need_account"} — Anonymous trial requests beyond allowed usage (trial flow guardrails).
• Success payload: JSON object including data (ads), optional message (human-readable filter hints), total when computed on first page, and free-tier credit fields when applicable.