Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Meta

You first need to create an account, you can sign up here to receive 50 credits to test it out.

The Facebook & Instagram endpoint allows you find all Facebook and Instagram ads for a given company.

It takes a Facebook page or a company domain as input.

Company domain has to be passed in the 'company.com' format, meaning all prefixes like 'https://' or 'www.' need to be removed.

API endpoint

POST api.adyntel.com/facebook

See which Facebook or Instagram ads a company is running by providing their website or Facebook page as input.

Headers

Name
Value
Required

Content-Type

application/json

Body

Name
Type
Description
Required

api_key

string

Adyntel API key

email

number

Adyntel account email

facebook_url

string

Facebook page url (needs to start with https://) Either this or company_domain is required.

company_domain

string

Company website Either this or facebook_url is required.

webhook_url

string

Webhook URL where the data will be returned

continuation_token

string

Token used to grab the next set of ads

media_type

string

Parameter used to filter results for a specific type of media. Possible values: image, meme, image_and_meme, video

country_code

string or array

Parameter used to filter results for a specific country. Pass a single code ("FR") for one country, or an array of up to 20 codes (["FR", "ES", "DE"]) to run one independent job per country. The array form requires webhook_url and costs one credit per country — see Filtering by several countries below. See possible list of values below.

language

string or array

Filter results to ads written in one or more languages. Accepts an English language name ("Polish"), an ISO 639-1 code ("pl"), or an array mixing both (["pl", "French"]), in which case an ad matching any one of them is returned. An unrecognised language is rejected with a 422 before anything is scraped or charged. See possible list of values below.

active_status

string

This filters the search in the ad library by active, inactive or all ads. If this is not added the endpoint returns, by default, just active ads. Possible values: inactive (to get just the inactive ads) and all (to get both the active and inactive ads)

all_ads

boolean

This will automatically use the continuation_token and scrape all the pages, returning all available ads. Works only with a webhook_url as it needs a place to send each page, one by one. Warning: use this cautiously because there is no way of stopping it. If you use this on a domain that runs 10000 ads, it will try to scrape all the ads and it will use the credits (one page = one credit)

check_ugc

boolean

When true, each video ad is ran through a classifier and a parameter called is_ugc_video (boolean) is added to the final response.

Works only together with media_type set to video

List of possible values for the country_code parameter:

AL | DZ | AS | AD | AO | AQ | AG | AR | AM | AU | AT | AZ | BH | BD | BB | BY | BE | BZ | BJ | BT | BO | BA | BW | BR | BN | BG | BF | BI | KH | CM | CA | CV | BQ | CF | TD | CL | CN | CX | CC | CO | KM | CK | CR | CI | HR | CW | CY | CZ | CD | DK | DJ | DM | DO | EC | EG | SV | GQ | ER | EE | SZ | ET | FM | FJ | FI | FR | PF | TF | GA | GE | DE | GH | GR | GD | GU | GT | GG | GN | GW | GY | HT | HM | HN | HU | IS | IN | ID | IQ | IE | IL | IT | JM | JP | JE | JO | KZ | KE | KI | KW | KG | LA | LV | LB | LS | LR | LY | LI | LT | LU | MG | MW | MY | MV | MT | ML | MH | MR | MU | MX | MD | MC | MN | ME | MA | MZ | MM | NA | NR | NP | NL | NC | NZ | NI | NE | NG | NU | NF | MK | MP | NO | OM | PK | PW | PA | PG | PY | PE | PH | PN | PL | PT | QA | CG | RO | RW | SH | KN | LC | PM | VC | WS | SM | ST | SA | SN | SC | SL | SG | SX | SK | SI | SB | SO | ZA | GS | KR | ES | LK | SR | CH | SE | TJ | TZ | TH | BS | GM | TL | TG | TK | TO | TT | TN | TR | TM | TV | UG | UA | AE | GB | US | UY | UZ | VU | VA | VE | VN | YE | ZM | ZW | BM | BV | IO | VG | IC | KY | TW | YT | FO | FK | GF | PS | GI | GL | GP | HK | IM | MO | MQ | MS | AW | PR | RE | AI | EH | MF | SJ | TC | UM | VI | WF

List of possible values for the language parameter:

Send either the name or the code in brackets.

Afrikaans (af) | Akan (ak) | Albanian (sq) | Amharic (am) | Arabic (ar) | Armenian (hy) | Assamese (as) | Aymara (ay) | Azerbaijani (az) | Bambara (bm) | Basque (eu) | Belarusian (be) | Bengali (bn) | Bosnian (bs) | Breton (br) | Bulgarian (bg) | Burmese (my) | Catalan (ca) | Cebuano (cb) | Chichewa (ny) | Chinese (zh) | Croatian (hr) | Czech (cs) | Danish (da) | Divehi (dv) | Dutch (nl) | English (en) | Esperanto (eo) | Estonian (et) | Faroese (fo) | Finnish (fi) | French (fr) | Frisian (fy) | Fulah (ff) | Galician (gl) | Georgian (ka) | German (de) | Greek (el) | Guarani (gn) | Gujarati (gu) | Haitian Creole (ht) | Hausa (ha) | Hebrew (he) | Hindi (hi) | Hungarian (hu) | Icelandic (is) | Igbo (ig) | Indonesian (id) | Inuktitut (iu) | Irish (ga) | Italian (it) | Japanese (ja) | Javanese (jv) | Kannada (kn) | Kazakh (kk) | Khmer (km) | Kinyarwanda (rw) | Kongo (kg) | Korean (ko) | Kurdish (ku) | Kyrgyz (ky) | Lao (lo) | Latin (la) | Latvian (lv) | Limburgish (li) | Lingala (ln) | Lithuanian (lt) | Macedonian (mk) | Malagasy (mg) | Malay (ms) | Malayalam (ml) | Maltese (mt) | Maori (mi) | Marathi (mr) | Mongolian (mn) | Nepali (ne) | Northern Sami (se) | Norwegian (no) | Norwegian Bokmal (nb) | Norwegian Nynorsk (nn) | Odia (or) | Oromo (om) | Pashto (ps) | Persian (fa) | Polish (pl) | Portuguese (pt) | Punjabi (pa) | Quechua (qu) | Romanian (ro) | Romansh (rm) | Russian (ru) | Sanskrit (sa) | Sardinian (sc) | Scottish Gaelic (gd) | Serbian (sr) | Shona (sn) | Sindhi (sd) | Sinhala (si) | Slovak (sk) | Slovenian (sl) | Somali (so) | Southern Sotho (st) | Spanish (es) | Swahili (sw) | Swati (ss) | Swedish (sv) | Tagalog (tl) | Tajik (tg) | Tamil (ta) | Tatar (tt) | Telugu (te) | Thai (th) | Tibetan (bo) | Tigrinya (ti) | Tsonga (ts) | Tswana (tn) | Turkish (tr) | Ukrainian (uk) | Urdu (ur) | Uyghur (ug) | Uzbek (uz) | Venda (ve) | Vietnamese (vi) | Welsh (cy) | Wolof (wo) | Xhosa (xh) | Yiddish (yi) | Yoruba (yo) | Zulu (zu)

Filtering by several countries

country_code also accepts an array of codes. Each country runs as its own independent job: it is scraped on its own, charged on its own, retried on its own and sends its own webhook. Asking for ["FR", "ES", "DE"] is the same as making three separate single-country calls, in one request.

The array form requires webhook_url. Without one the call is rejected with a 400, because there is no single synchronous response that could carry several countries.

Rules:

  • At most 20 countries per request. More than that returns a 400 and nothing is queued or charged.

  • Codes are case-insensitive and whitespace is trimmed, so ["fr", " FR "] is one country and one credit.

  • ALL means "no country filter" and is only valid on its own. Mixing it with real codes (["ALL", "FR"]) returns a 400.

  • An empty array ([]) behaves exactly like leaving the parameter out.

  • Every other filter you send (media_type, active_status, language, check_ugc, all_ads) applies to each country.

  • A request that names a country is never served from cache, so you always get a fresh scrape.

Credits

One credit per country. Three countries cost three credits. The credits for the whole request are reserved before any job is queued, so a request you cannot afford is rejected with a 402 and nothing is queued and nothing is charged.

Example request

The response carries one job id per country, in the order you asked for them:

You then receive one webhook POST per country, each one an ordinary single-country response carrying its own country_code. A single string keeps its existing behaviour and returns a single jobId:

Partial failures

If a country cannot be queued, the others still run. The response is a 200 that lists the jobs that did start plus the countries that will never send a webhook, so your receiver is not left waiting for them. The countries that failed are not charged.

If no country at all could be queued you get a 500 and the entire request is refunded.

Example request

  • Request made using company_domain:

  • Request made using facebook_url:

  • Request made using webhooks (works with both company_domain and facebook_url):

When you're using webhooks the data will be sent to the webhook URL and you will receive a different response to your call:

  • Request made using continuation_token. You receive this token in the first call you make, but only if there are more ads than we were able to retrieve (usually we get the first 30 ads). If you use this in your next call we will give you the next set of ads (next 30) and, if there are more ads, you will receive another continuation_token that you can use to grab the next set of ads etc. This continues until the last page of ads where the response you get will have a "null" continuation_token.

Possible responses

204

There are multiple situations in which the response code will be 204 with no message. This happens when:

  • the domain provided returns a HTML response different than 200. That usually happens if the website could be loaded, it is not available, domain is expired etc.

  • we scrape the domain provided but there is no Facebook URL on it so there is no way to move to the next step

  • we scraped the Facebook URL but the page is not publicly available so it cannot be scraped

You are not charged when you receive this response code.

Full response, with ads

Example response

Attributes

  • active_status (string) Indicates whether the ad campaign is currently active.

  • continuation_token (nullable string) Token used for pagination to retrieve the next set of results, if applicable.

  • country_code (string) The ISO code of the country where the ads are displayed.

  • is_result_complete (boolean) Indicates if the result set is complete or if more data is available.

  • media_types (string) Types of media included in the ads, such as images or videos.

  • number_of_ads (integer) Total number of ads returned in the response.

  • page_id (string) Unique identifier for the Facebook page associated with the ads.

  • platform (array of strings) Platforms where the ads are running, e.g., Facebook, Instagram.

  • results (array of objects) Contains detailed information about each ad.

  • adArchiveID (string) Unique identifier for the ad in the archive.

  • adid (string) Identifier for the ad itself.

  • archiveTypes (array) Types of archives associated with the ad, if any.

  • categories (array of integers) Categories assigned to the ad for classification purposes.

  • collationCount (integer) Number of times this ad has been collated or grouped with others.

  • collationID (integer) Identifier for the collation group this ad belongs to.

  • containsDigitallyCreatedMedia (boolean) Indicates if the ad contains digitally created media content.

  • containsSensitiveContent (boolean) Indicates if the ad contains sensitive content that may require special handling.

  • currency (string) Currency used in any financial data related to the ad, if applicable.

  • endDate (integer) Unix timestamp representing when the ad campaign ends.

  • entityType (string) Type of entity associated with the ad, such as a person or business profile.

  • fevInfo (nullable object) Additional information related to Facebook's ad review process.

  • finServAdData (object) Contains information about financial service advertisements.

  • gatedType (string) Eligibility status of the ad for certain features or audiences.

  • hasUserReported (boolean) Indicates if any users have reported this ad for review or issues.

  • hiddenSafetyData (boolean) Indicates if there is any safety data that is hidden from view.

  • hideDataStatus (string) Status indicating whether any data related to this ad is hidden from public view.

  • impressionsWithIndex (object) Contains information about ad impressions.

  • isAAAEligible (boolean) Indicates eligibility for AAA (Audience and Ad Analysis) features.

  • isActive (boolean) Indicates whether the ad is currently active and running.

  • isAdAccountActioned (boolean) Indicates if any actions have been taken on this ad by account administrators.

  • isProfilePage (boolean) Indicates if this ad is associated with a profile page rather than a business page.

  • menuItems (array) Array of menu items associated with this ad's context or placement.

  • pageID (string) Identifier for the Facebook page that owns this ad.

  • pageInfo (nullable object) Additional information about the page associated with the ad.

  • pageIsDeleted (boolean) Indicates whether the page associated with this ad has been deleted.

  • pageName (string) Name of the Facebook page associated with this ad.

  • politicalCountries (array) List of countries where this ad is classified as political content.

  • publisherPlatform (array of strings) Platforms where this ad is published and visible to users.

  • reachEstimate (nullable object) Estimated reach of this ad in terms of audience size or demographics, if available.

  • reportCount (nullable integer) Number of reports or complaints filed against this ad by users or moderators.

  • snapshot (object) Contains detailed information about the ad creative, including body, images, and call-to-action details.

  • spend (nullable object) Financial spend data related to this ad campaign, if available.

  • startDate (integer) Unix timestamp representing when the ad campaign starts or started running.

  • stateMediaRunLabel (nullable string) Label indicating media run state or status for regulatory purposes, if applicable.

  • totalActiveTime (nullable integer) Total active time duration for which this ad has been running since its start date.

PreviousExtracting LinkedIn page id
NextMeta ad search

Last updated