Ad Library Company Ads

GET/v1/facebook/adLibrary/company/adsNot available

Lists the ads a company runs in the Facebook Ad Library, 30 per page. Not available yet.

Not available

This route is documented so that existing integrations get a clear answer, but it returns no data: every call is a free error and costs no credits. The notes below say what it answers.

01Query parameters

Name	Type	Description
pageIdoptional	string	The advertiser's numeric Facebook page id (from the Ad Library company search). One of `pageId` or `companyName` is required.
companyNameoptional	string	The company's name. One of `pageId` or `companyName` is required.
countryoptional	string	One two-letter country code, or `ALL`.Default: `ALL`
statusoptional	string	Ad status filter.Default: `ACTIVE`Accepted values:`ALLACTIVEINACTIVE`
media_typeoptional	string	Media type filter; `MEME` means an image with text.Default: `ALL`Accepted values:`ALLIMAGEVIDEOMEMEIMAGE_AND_MEMENONE`
languageoptional	string	Two-letter language code, e.g. `EN`.
sort_byoptional	string	`total_impressions` (most impressions first) or `relevancy_monthly_grouped` (most recent first).Default: `total_impressions`Accepted values:`total_impressionsrelevancy_monthly_grouped`
start_dateoptional	string	Start date, `YYYY-MM-DD`.
end_dateoptional	string	End date, `YYYY-MM-DD`.
cursoroptional	string	The `cursor` from the previous page.
trimoptional	boolean	Set to `true` for a shorter response.Default: `false`

02Responses

Real answers from the API. Lists are shortened to 2 items.

GET /v1/facebook/adLibrary/company/ads

{
  "success": false,
  "credits_remaining": 4980,
  "credits_charged": 0,
  "error": "missing_parameter",
  "errorStatus": 400,
  "message": "You must provide a 'pageId' or 'companyName' parameter"
}

Common to every endpoint

Any route can answer these: a missing or wrong key, no credits left, the platform not answering, or a failure on our side. None of them costs credits.

GET /v1/cosmos/profile?handle=design

{
  "success": false,
  "message": "Invalid API key"
}

03Notes

The Facebook Ad Library is not available through this API yet: a call with its required parameters answers a 503 `upstream_unavailable` and is free. Missing required parameters still return a free 400.

04Errors & credits

Every error has success: false, a real HTTP status and costs no credits.

400missing_parameter
A required parameter is missing or invalid.
403private_account
The account is private or age-restricted.
404not_found
No such account.
503upstream_error
The platform did not answer; retry shortly.