InsightSocial API
Facebook

Adlibrary › Search › Ads

GET
/v1/facebook/adlibrary/search/ads

Returns Facebook Ad Library ads matching a keyword, each with its creative text, images, sponsor info, and running status.

Use it to find ads across all advertisers by keyword; if you already know the advertiser, adlibrary/company/ads is more direct.

100 credits per call.

Re-running the exact same call within 1h is free.

Paginates by cursor — see Pagination.

Authorization

apiKey
x-api-key<token>

Your key from the dashboard. It starts with isk_.

In: header

Query Parameters

query*string

Search keyword or phrase to find ads in the Facebook Ad Library

sort_by?string

Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.

Value in

  • "total_impressions"
  • "relevancy_monthly_grouped"
search_type?string

If you want to search by exact phrase or not

Value in

  • "keyword_unordered"
  • "keyword_exact_phrase"
ad_type?string

Search for all ads or only political and issue ads

Value in

  • "all"
  • "political_and_issue_ads"
country?string

This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.

status?string

Status of the ad. Defaults to ACTIVE.

Value in

  • "ALL"
  • "ACTIVE"
  • "INACTIVE"
media_type?string

Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme.

Value in

  • "ALL"
  • "IMAGE"
  • "VIDEO"
  • "MEME"
  • "IMAGE_AND_MEME"
  • "NONE"
start_date?string

Impressions start date. Needs to be in YYYY-MM-DD format.

end_date?string

Impressions end date. Needs to be in YYYY-MM-DD format.

cursor?string

Cursor to paginate through results

trim?boolean

Set to true for a trimmed down version of the response

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/facebook/adlibrary/search/ads?query=string"
{  "success": true,  "platform": "instagram",  "endpoint": "/v1/instagram/profile/posts",  "data": {    "items": [      "…"    ],    "dropped": 0  },  "pagination": {    "next_cursor": "is2.eyJwIjoyfQ",    "has_more": true,    "page_size": 12  },  "credits_used": 20,  "credits_remaining": 9980,  "request_id": "req_1a2b3c4d5e6f",  "cached": false,  "idempotent_replay": false,  "charge_reason": "miss",  "free_call": false}

Adlibrary › Company › Ads GET

Returns the ads one company or page is running in the Facebook Ad Library, each with its creative, status, spend, and targeting info. Use it when you know the advertiser by pageId or company name; to find ads by keyword across advertisers, use adlibrary/search/ads. **100 credits** per call. Re-running the exact same call within 6h is free. Paginates by `cursor` — see [Pagination](/docs/pagination).

Adlibrary › Search › Companies GET

Returns advertiser pages in the Facebook Ad Library matching a name, each with its page id, name, handle, verification badge and follower count. Use it to find an advertiser's pageId first, then pass that pageId to adlibrary/company/ads, which is also where you count their ads. **100 credits** per call. Re-running the exact same call within 1h is free.