InsightSocial API
Facebook

Adlibrary › Company › Ads

GET
/v1/facebook/adlibrary/company/ads

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.

Authorization

apiKey
x-api-key<token>

Your key from the dashboard. It starts with isk_.

In: header

Query Parameters

pageId?string

Facebook page ID of the advertiser. Provide at least one of: pageId, companyName.

companyName?string

The name of the company. Can either use this or pageId. Provide at least one of: pageId, companyName.

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 refers to ads with image and text. Not sure why they call it meme.

Value in

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

Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc

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"
start_date?string

Start date to search for. Format: YYYY-MM-DD

end_date?string

End date to search for. Format: YYYY-MM-DD

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/company/ads"
{  "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 › Ad GET

Returns one ad from the Facebook Ad Library: creative, CTA and link, run dates, display format, and the advertiser's page URL, likes and categories. Use it when you have an ad id or URL. Spend and reach are political-ads-only, and Facebook publishes no per-ad impression count. **100 credits** per call. Re-running the exact same call within 6h is free.

Adlibrary › Search › Ads GET

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](/docs/pagination).