/v1/facebook/adLibrary/company/ads

GET

Company Ads

Get a company's running ads. Use GET normally; for long pagination cursors, use POST with the same parameters in the JSON body.

Credit cost	Default: 1 credit How charges are determined Cost is decided per call, not per endpoint: the same operation can cost different amounts depending on what it returns. A call that fails costs 0 credits. A result served from cache costs 0 credits. `default` is the cost when no rule matches. Rules are evaluated in order and the first whose conditions all hold wins. A `when` condition is one of: `param` (the request parameter is true), `outcome` (the classifier's outcome), `empty` / `nonEmpty` (a response field is empty and absent, or a non-empty array or string), `flag` (a response field is exactly true). A cost of `{ perStartedMinute: n, of: [fields] }` is n x max(1, ceil(seconds / 60)), so even a short result bills at least one minute.
Cache support	Not specified in the published contract.
Pagination	No explicit pagination metadata in the published contract. Consult the parameters and response fields below.

Parameters

Name	Location / required	Schema
`pageId` Company Ad Library page ID from Search for Companies. Provide pageId or companyName.	query / optional	`string`
`companyName` Company name. Provide companyName or pageId.	query / optional	`string`
`country` One two-letter country code, or ALL (default).	query / optional	`string`
`status` Status of the ad. Defaults to ACTIVE.	query / optional	`string` Allowed values `["ALL","ACTIVE","INACTIVE"]`
`media_type` Ad media type. Defaults to ALL. Meme means an image with text.	query / optional	`string` Allowed values `["ALL","IMAGE","VIDEO","MEME","IMAGE_AND_MEME","NONE"]`
`language` Two-letter ad language code, such as EN, ES, or FR.	query / optional	`string`
`sort_by` Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.	query / optional	`string` Allowed values `["total_impressions","relevancy_monthly_grouped"]`
`start_date` Start date to search for. Format: YYYY-MM-DD	query / optional	`string`
`end_date` End date to search for. Format: YYYY-MM-DD	query / optional	`string`
`trim` Set true for a trimmed response.	query / optional	`boolean`
`cursor` Cursor to paginate through results	query / optional	`string`

Request examples

Replace placeholder values and supply your own API key. For operations with a request body, populate the body using the schema above.

cURL

curl --request GET 'https://api.fetchproof.com/v1/facebook/adLibrary/company/ads' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/facebook/adLibrary/company/ads", {
  method: 'GET',
  headers: { 'x-api-key': process.env.FETCHPROOF_API_KEY }
});
console.log(await response.text());

Python

import os
import requests

response = requests.get("https://api.fetchproof.com/v1/facebook/adLibrary/company/ads",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]})
print(response.text)

Responses

200Success. Envelope: success / credits_remaining / credits_charged.

application/json

object

successrequired

boolean

credits_remainingrequired

integer

credits_chargedrequired

integer

resultsrequired

array

Array items

object

ad_archive_idrequired

string

ad_idoptional

null

archive_typesoptional

array

categoriesoptional

array

Array items

string

collation_countoptional

integer

collation_idoptional

string

contains_digital_created_mediaoptional

boolean

contains_sensitive_contentoptional

boolean

currencyoptional

string

end_daterequired

integer

entity_typeoptional

string

fev_infooptional

null

finserv_ad_dataoptional

object

is_deemed_finservrequired

boolean

is_limited_deliveryrequired

boolean

gated_typeoptional

string

has_user_reportedoptional

boolean

hidden_safety_dataoptional

boolean

hide_data_statusoptional

string

impressions_with_indexoptional

object

impressions_textrequired

null

impressions_indexrequired

integer

is_aaa_eligiblerequired

boolean

is_activerequired

boolean

is_profile_pageoptional

boolean

menu_itemsoptional

array

page_idrequired

string

page_is_deletedoptional

boolean

page_namerequired

string

political_countriesrequired

array

publisher_platformrequired

array

Array items

string

reach_estimaterequired

null

regional_regulation_dataoptional

object

finservrequired

object

is_deemed_finservrequired

boolean

is_limited_deliveryrequired

boolean

tw_anti_scamrequired

object

is_limited_deliveryrequired

boolean

report_countoptional

null

snapshotrequired

object

bodyrequired

object

textrequired

string

branded_contentrequired

object

current_page_namerequired

string

page_categoriesrequired

array

Array items

string

page_idrequired

string

page_is_deletedrequired

boolean

page_namerequired

string

page_profile_pic_urlrequired

string

page_profile_urirequired

string

brazil_tax_idrequired

null

bylinerequired

null

captionrequired

string

cardsrequired

array

cta_textrequired

string

cta_typerequired

string

country_iso_coderequired

null

current_page_namerequired

string

disclaimer_labelrequired

null

display_formatrequired

string

eventrequired

null

imagesrequired

array

is_resharedrequired

boolean

link_descriptionrequired

null

link_urlrequired

string

page_categoriesrequired

array

Array items

string

page_entity_typerequired

string

page_idrequired

string

page_is_deletedrequired

boolean

page_is_profile_pagerequired

boolean

page_like_countrequired

integer

page_namerequired

string

page_profile_picture_urlrequired

string

page_profile_urirequired

string

root_reshared_postrequired

null

titlerequired

string

videosrequired

array

Array items

object

video_hd_urlrequired

string

video_preview_image_urlrequired

string

video_sd_urlrequired

string

watermarked_video_hd_urlrequired

string

watermarked_video_sd_urlrequired

string

additional_inforequired

null

ec_certificatesrequired

array

extra_imagesrequired

array

extra_linksrequired

array

Array items

string

extra_textsrequired

array

extra_videosrequired

array

Array items

object

video_hd_handlerequired

string

video_sd_handlerequired

string

watermarked_video_hd_urlrequired

null

watermarked_video_sd_urlrequired

null

spendrequired

null

start_daterequired

integer

state_media_run_labeloptional

null

targeted_or_reached_countriesoptional

array

total_active_timerequired

null

urloptional

string

start_date_stringoptional

string

{
  "format": "date-time"
}

end_date_stringoptional

string

{
  "format": "date-time"
}

cursorrequired

string

401Invalid or missing x-api-key

402No credits remaining

403Upstream denied (age gate, audience controls)

404Resource or endpoint not found

429Rate limited

POST

Company Ads

Get a company's running ads. Use GET normally; for long pagination cursors, use POST with the same parameters in the JSON body.

Credit cost	Default: 1 credit How charges are determined Cost is decided per call, not per endpoint: the same operation can cost different amounts depending on what it returns. A call that fails costs 0 credits. A result served from cache costs 0 credits. `default` is the cost when no rule matches. Rules are evaluated in order and the first whose conditions all hold wins. A `when` condition is one of: `param` (the request parameter is true), `outcome` (the classifier's outcome), `empty` / `nonEmpty` (a response field is empty and absent, or a non-empty array or string), `flag` (a response field is exactly true). A cost of `{ perStartedMinute: n, of: [fields] }` is n x max(1, ceil(seconds / 60)), so even a short result bills at least one minute.
Cache support	Not specified in the published contract.
Pagination	No explicit pagination metadata in the published contract. Consult the parameters and response fields below.

Parameters

Name	Location / required	Schema
`pageId` Company Ad Library page ID from Search for Companies. Provide pageId or companyName.	query / optional	`string`
`companyName` Company name. Provide companyName or pageId.	query / optional	`string`
`country` One two-letter country code, or ALL (default).	query / optional	`string`
`status` Status of the ad. Defaults to ACTIVE.	query / optional	`string` Allowed values `["ALL","ACTIVE","INACTIVE"]`
`media_type` Ad media type. Defaults to ALL. Meme means an image with text.	query / optional	`string` Allowed values `["ALL","IMAGE","VIDEO","MEME","IMAGE_AND_MEME","NONE"]`
`language` Two-letter ad language code, such as EN, ES, or FR.	query / optional	`string`
`sort_by` Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.	query / optional	`string` Allowed values `["total_impressions","relevancy_monthly_grouped"]`
`start_date` Start date to search for. Format: YYYY-MM-DD	query / optional	`string`
`end_date` End date to search for. Format: YYYY-MM-DD	query / optional	`string`
`trim` Set true for a trimmed response.	query / optional	`boolean`
`cursor` Cursor to paginate through results	query / optional	`string`

Request examples

Replace placeholder values and supply your own API key. For operations with a request body, populate the body using the schema above.

cURL

curl --request POST 'https://api.fetchproof.com/v1/facebook/adLibrary/company/ads' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/facebook/adLibrary/company/ads", {
  method: 'POST',
  headers: { 'x-api-key': process.env.FETCHPROOF_API_KEY }
});
console.log(await response.text());

Python

import os
import requests

response = requests.post("https://api.fetchproof.com/v1/facebook/adLibrary/company/ads",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]})
print(response.text)

Responses

200Success. Envelope: success / credits_remaining / credits_charged.

application/json

object

successrequired

boolean

credits_remainingrequired

integer

credits_chargedrequired

integer

resultsrequired

array

Array items

object

ad_archive_idrequired

string

ad_idoptional

null

archive_typesoptional

array

categoriesoptional

array

Array items

string

collation_countoptional

integer

collation_idoptional

string

contains_digital_created_mediaoptional

boolean

contains_sensitive_contentoptional

boolean

currencyoptional

string

end_daterequired

integer

entity_typeoptional

string

fev_infooptional

null

finserv_ad_dataoptional

object

is_deemed_finservrequired

boolean

is_limited_deliveryrequired

boolean

gated_typeoptional

string

has_user_reportedoptional

boolean

hidden_safety_dataoptional

boolean

hide_data_statusoptional

string

impressions_with_indexoptional

object

impressions_textrequired

null

impressions_indexrequired

integer

is_aaa_eligiblerequired

boolean

is_activerequired

boolean

is_profile_pageoptional

boolean

menu_itemsoptional

array

page_idrequired

string

page_is_deletedoptional

boolean

page_namerequired

string

political_countriesrequired

array

publisher_platformrequired

array

Array items

string

reach_estimaterequired

null

regional_regulation_dataoptional

object

finservrequired

object

is_deemed_finservrequired

boolean

is_limited_deliveryrequired

boolean

tw_anti_scamrequired

object

is_limited_deliveryrequired

boolean

report_countoptional

null

snapshotrequired

object

bodyrequired

object

textrequired

string

branded_contentrequired

object

current_page_namerequired

string

page_categoriesrequired

array

Array items

string

page_idrequired

string

page_is_deletedrequired

boolean

page_namerequired

string

page_profile_pic_urlrequired

string

page_profile_urirequired

string

brazil_tax_idrequired

null

bylinerequired

null

captionrequired

string

cardsrequired

array

cta_textrequired

string

cta_typerequired

string

country_iso_coderequired

null

current_page_namerequired

string

disclaimer_labelrequired

null

display_formatrequired

string

eventrequired

null

imagesrequired

array

is_resharedrequired

boolean

link_descriptionrequired

null

link_urlrequired

string

page_categoriesrequired

array

Array items

string

page_entity_typerequired

string

page_idrequired

string

page_is_deletedrequired

boolean

page_is_profile_pagerequired

boolean

page_like_countrequired

integer

page_namerequired

string

page_profile_picture_urlrequired

string

page_profile_urirequired

string

root_reshared_postrequired

null

titlerequired

string

videosrequired

array

Array items

object

video_hd_urlrequired

string

video_preview_image_urlrequired

string

video_sd_urlrequired

string

watermarked_video_hd_urlrequired

string

watermarked_video_sd_urlrequired

string

additional_inforequired

null

ec_certificatesrequired

array

extra_imagesrequired

array

extra_linksrequired

array

Array items

string

extra_textsrequired

array

extra_videosrequired

array

Array items

object

video_hd_handlerequired

string

video_sd_handlerequired

string

watermarked_video_hd_urlrequired

null

watermarked_video_sd_urlrequired

null

spendrequired

null

start_daterequired

integer

state_media_run_labeloptional

null

targeted_or_reached_countriesoptional

array

total_active_timerequired

null

urloptional

string

start_date_stringoptional

string

{
  "format": "date-time"
}

end_date_stringoptional

string

{
  "format": "date-time"
}

cursorrequired

string

401Invalid or missing x-api-key

402No credits remaining

403Upstream denied (age gate, audience controls)

404Resource or endpoint not found

429Rate limited