Ad Library API: Search ads across ad libraries

Searches the public Meta, Google, TikTok, and LinkedIn ad libraries in one call and returns ads in a shared shape. Requires query; platforms and countries narrow the search, and limit caps total ads. sources[] reports each library's result.

4 credits / requestBilled only on success

Authorization

ApiKeyAuth

x-api-key<token>

In: header

Query Parameters

query*string

Brand, advertiser, or keyword. Every library supports advertiser-name search; Google resolves the name to an advertiser first, because its creative search cannot take free text.

Length1 <= length <= 200

platforms?string

Comma-separated ad libraries to query. Defaults to all four. Narrow this to avoid paying for sources you don't need.

Default"meta,google,tiktok,linkedin"

countries?string

Comma-separated ISO 3166-1 alpha-2 codes. Meta, Google, and TikTok accept one country per query and use the first entry; LinkedIn accepts the full list. UK is corrected to GB and EL to GR, because those are the codes people write and neither is the ISO code the libraries answer to.

Default"US"

date_min?string

Earliest ad-activity date (YYYY-MM-DD). When omitted, TikTok falls back to the last 90 days because it requires a window.

Match^\d{4}-\d{2}-\d{2}$

date_max?string

Latest ad-activity date (YYYY-MM-DD). Defaults to today.

Match^\d{4}-\d{2}-\d{2}$

active_status?string

Delivery status. Only Meta filters on this; the other libraries ignore it and report whatever status they expose.

Default"all"

Value in

"all"
"active"
"inactive"

media_type?string

Creative format filter. Applied by Meta and Google when searching; applied to the merged results afterward for TikTok and LinkedIn.

Default"all"

Value in

"all"
"image"
"video"

limit?integer

Maximum ads across every library combined. Results are interleaved round-robin so one library cannot crowd out the rest.

Range1 <= value <= 200

Default40

enrich_details?string

Include available advertiser, date, and copy details for LinkedIn ads. Disable for a faster, lower-cost response with fewer fields.

Defaulttrue

include_source?string

Include each ad's original platform record in source when you need fields outside the shared response shape.

Defaultfalse

curl -X GET "https://example.com/v1/ad-library/search?query=nike" \  -H "x-api-key: YOUR_API_KEY"

{  "data": {    "count": 0,    "ads": [      {        "platform": "meta",        "ad_id": "string",        "ad_url": "string",        "advertiser_name": "string",        "advertiser_id": "string",        "first_seen": "string",        "last_seen": "string",        "is_active": true,        "creative": {          "format": "image",          "title": "string",          "body": "string",          "landing_url": "string",          "media_urls": [            "string"          ],          "thumbnail_url": "string"        },        "metrics": {          "impressions": {            "min": 0,            "max": 0,            "text": "string"          },          "spend": {            "min": 0,            "max": 0,            "text": "string"          },          "audience": {            "min": 0,            "max": 0,            "text": "string"          },          "currency": "string"        },        "countries": [          "string"        ],        "surfaces": [          "string"        ],        "source": null      }    ],    "sources": [      {        "platform": "meta",        "status": "ok",        "count": 0,        "reason": "string",        "pages": 0,        "enriched": 0,        "resolved_advertiser": {          "id": "string",          "name": "string"        }      }    ]  }}