InsightSocial API
Facebook

Facebook Ad Library Company Ads API reference

Your first 10 calls are free, no card needed. Pricing and FAQ

Get a free API key
Example request
curl "https://api.insightsocial.app/v1/facebook/adlibrary/company/ads?companyName=Lululemon" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"
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.

Metered: 50–350 credits. We reserve the ceiling when the call starts and charge what it actually used when it finishes.

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

include?"audience"

Set to audience (one token only) to fill, on every ad that ran in the EU, post.ext.ad.eu_total_reach, post.ext.ad.eu_reach_breakdown (reach per EU country by age band and gender), post.ext.ad.targets_eu, target_ages, target_gender and target_locations. Without it the call is unchanged.

Value in

  • "audience"
dry_run?"1"

Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.

Value in

  • "1"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://api.insightsocial.app/v1/facebook/adlibrary/company/ads"
{  "success": true,  "platform": "string",  "endpoint": "string",  "schema_version": "2",  "pagination": {    "next_cursor": "string",    "has_more": true,    "page_size": 0,    "stopped_at": "since"  },  "unavailable": [    "string"  ],  "credits_used": 0,  "credits_remaining": 0,  "request_id": "string",  "cached": true,  "idempotent_replay": true,  "charge_reason": "string",  "free_call": true,  "data": {    "items": [      {        "post": {          "id": "string",          "url": "http://example.com",          "kind": "string",          "content": {            "text": "string",            "media_urls": [              "http://example.com"            ],            "thumbnail_url": "http://example.com",            "duration_seconds": 0          },          "author": {            "id": "string",            "username": "string",            "display_name": "string",            "avatar_url": "http://example.com",            "verified": true          },          "engagement": {            "views": 0,            "likes": 0,            "comments": 0,            "shares": 0,            "saves": 0          },          "flags": {            "nsfw": true,            "spoiler": true,            "pinned": true,            "deleted": true,            "likes_hidden": true,            "comments_hidden": true,            "shares_hidden": true,            "views_hidden": true,            "saves_hidden": true          },          "published_at": "2019-08-24T14:15:22Z",          "language": "string",          "ext": {            "property1": null,            "property2": null          }        }      }    ],    "total": 0,    "truncated": true,    "ext": {      "property1": null,      "property2": null    }  }}

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.

Adlibrary › Search › Ads GET

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