Facebook

Ad search

Ads in Meta's Ad Library by keyword, about 10 a page: by the country, status, media and dates given.

GET/v1/facebook/ad-library/ads/search1 credit

Headers

Get your API key

x-api-key*stringrequiredheader

Your API key, made in the dashboard.

Parameters

query*stringrequiredquery

Words to search for.

min 1 chars · max 200 chars · example: running

countrystringoptionalquery

Only ads shown in this country: a two-letter code (US), or ALL.

default: ALL

statusenumoptionalquery

Only ads running now, or those that stopped.

one of: all, active, inactive · default: all

media_typeenumoptionalquery

Only ads with images, videos, memes (image and text), either, or none.

one of: all, image, video, meme, image_and_meme, none · default: all

start_datestringoptionalquery

Only ads shown in this date range (YYYY-MM-DD): give start_date and end_date together.

end_datestringoptionalquery

Only ads shown in this date range (YYYY-MM-DD): give start_date and end_date together.

cursorstringoptionalquery

For the next page: page.next_cursor from the page before. Send the other parameters again with it.

max 12000 chars

Response fields

dataarray

The result: one object, or a list for the endpoints that return several.

data[].idstring

The ad's id in the Ad Library: digits, written as text.

data[].urlstring

The ad's page in the Ad Library.

data[].page_idstringnullable

The advertiser's Page id: the company ads endpoint takes it.

data[].page_namestringnullable

The advertiser's name.

data[].page_urlstringnullable

The advertiser's profile.

data[].page_picturestringnullable

The advertiser's picture.

data[].activebooleannullable

Whether the ad still runs.

data[].started_atstringnullable

When it started running.

format: date-time

data[].ended_atstringnullable

When it stopped running, or its planned end.

format: date-time

data[].platformsstring[]nullable

Where it runs: FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS.

data[].formatstringnullable

IMAGE, VIDEO, CAROUSEL, DCO (several versions) and so on.

data[].textstringnullable

Its text.

data[].titlestringnullable

Its headline.

data[].link_urlstringnullable

Where it links to.

data[].ctastringnullable

Its button's text (Shop now, Sign up).

data[].imagestringnullable

Its image's link, the first of several, or its video's thumbnail.

data[].video_urlstringnullable

Its video's file, in HD where there is one.

data[].versionsintegernullable

How many ads the Ad Library groups under this one (the same ad, run several times).

pageobjectnullable

Paging, for the endpoints that page; null for the others.

page.next_cursorstringnullable

Send it as the cursor parameter, with the same other parameters, for the next page. Null on the last page.

page.has_morebooleanoptional

Whether another page follows.

default: false

metaobject

About this call.

meta.platformstring

The platform: reddit, threads, tiktok or youtube.

meta.endpointstring

The endpoint's name, such as channel_videos.

meta.paramsobject

The call's parameters, defaults included. Parameters without a value, and the cursor, are left out.

meta.request_idstring

This call's id. Quote it when you report a problem.

meta.api_versionstring

The API version that answered.

meta.fetched_atstring

When the data was fetched from the platform (UTC).

format: date-time

meta.cachedbooleanoptional

Whether it came from our cache; fetched_at says how old it is.

default: false

Code example

curl -X GET 'https://api.socialparse.dev/v1/facebook/ad-library/ads/search?query=running' \  -H 'x-api-key: YOUR_API_KEY'

Responses

Successful Response

{  "data": [    {      "id": "string",      "url": "string",      "page_id": "string",      "page_name": "string",      "page_url": "string",      "page_picture": "string",      "active": true,      "started_at": "2019-08-24T14:15:22Z",      "ended_at": "2019-08-24T14:15:22Z",      "platforms": [        "string"      ],      "format": "string",      "text": "string",      "title": "string",      "link_url": "string",      "cta": "string",      "image": "string",      "video_url": "string",      "versions": 0    }  ],  "page": {    "next_cursor": "string",    "has_more": false  },  "meta": {    "platform": "string",    "endpoint": "string",    "params": {      "property1": "string",      "property2": "string"    },    "request_id": "string",    "api_version": "string",    "fetched_at": "2019-08-24T14:15:22Z",    "cached": false  }}

An ad in Meta's Ad Library: its advertiser, text, headline, link, image or video, platforms and dates.

Company ads

An advertiser's ads in Meta's Ad Library, about 10 a page.