Skip to main content
POST
Submit Facebook Ad Library Search task

Ad Library Search

Search public ads by keyword, status, country, media type, and date range.

Request Example

SocQ follows available result pages until results_limit is reached, no next page is available, or the task reaches its pagination safety boundary. Duplicate ad IDs are saved once.

Completed Task Response

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
query
string
required

Keyword or phrase used to search public ads.

Minimum string length: 1
results_limit
integer
default:100

Maximum unique ads to save across result pages.

Required range: 20 <= x <= 2000
sort_by
enum<string>
default:total_impressions

Sort by estimated impressions or recent relevance.

Available options:
total_impressions,
relevancy_monthly_grouped
search_type
enum<string>
default:keyword_unordered

Match query words in any order or as an exact phrase.

Available options:
keyword_unordered,
keyword_exact_phrase
ad_type
enum<string>
default:all

Include all ads or only political and issue ads.

Available options:
all,
political_and_issue_ads
country
string
default:ALL

ALL or one two-letter country code.

Pattern: ^(ALL|[A-Za-z]{2})$
status
enum<string>
default:ACTIVE

Ad delivery status.

Available options:
ALL,
ACTIVE,
INACTIVE
media_type
enum<string>
default:ALL

Creative media filter.

Available options:
ALL,
IMAGE,
VIDEO,
MEME,
IMAGE_AND_MEME,
NONE
start_date
string<date>

Impression period start date in YYYY-MM-DD format.

end_date
string<date>

Impression period end date in YYYY-MM-DD format. It cannot precede start_date.

callback_url
string<uri>

Optional URL that receives the task completion callback.

Response

Task submitted

code
integer
Example:

200

data
object