# Facebook Ads API Reference Canonical: https://monsterapi.co/docs/api/facebook-ads Read the Facebook Ads reference. Review parameters, response fields, examples, and current credit prices. OpenAPI specification: [Facebook](https://monsterapi.co/docs/openapi/platforms/facebook.yaml). --- Current operation prices: [public catalog](https://monsterapi.co/account/api/v1/public/api-prices). Prices use credits per request. --- # Facebook: Ad audience and transparency `GET /facebook/api/ads/details` Documentation: https://monsterapi.co/docs/api/facebook#facebook-ad-audience-and-transparency Operation ID: `facebook_ads_details` Returns advertiser, audience and transparency details for an ad. Pass both ad_id and its advertiser page_id. ## Authentication Send your billing API key in the `Authorization: Bearer ` header. Your account login is separate. ## Inputs - `ad_id` (query, required): Ad archive ID from `ads[].id` or `ad.id` in [/ads/library](https://monsterapi.co/docs/api/facebook-ads#facebook-ad-summaries). - `page_id` (query, required): Advertiser page ID for this ad from `ads[].author.id` or `ad.author.id` in [/ads/library](https://monsterapi.co/docs/api/facebook-ads#facebook-ad-summaries). ## Responses - 200: Requested information in data and its named fields; unavailable optional values are null. - 400: A request parameter is invalid. Refused at the gateway: the request target, path and query string together, is longer than 8,192 bytes; or the headers, the target counted among them, exceed 16,384 bytes or 64 fields - 401: #/components/responses/GatewayUnauthorized - 402: #/components/responses/GatewayPaymentRequired - 403: #/components/responses/GatewayForbidden - 404: The requested object is absent, or Facebook does not show it to logged-out visitors. An empty page of an object that exists does not return `404`. - 405: `method_not_allowed`: the endpoint answers GET alone, and any other method, HEAD included, is refused Refused at the gateway: the path exists, but no operation on it takes the method of the request, HEAD included; `Allow` names the methods that do - 409: #/components/responses/GatewayConflict - 429: `rate_limited`: Facebook limited the requests or asked a logged-out visitor to sign in. Wait for the seconds in `Retry-After`, then repeat the request. Facebook publishes no numbers for these limits. Refused at the gateway: the account calls faster than its rate limit allows - 500: The requested information could not be returned. - 501: The requested information is unavailable without signing in or is not supported. - 503: The requested information is temporarily unavailable. Repeat the request later. `code` gives the cause: - `upstream_error`: no answer came from Facebook, or Facebook answered with a server error. Wait for the seconds in `Retry-After`, then repeat the request. - `upstream_stale`: the service is renewing its access to this information. - `no_proxies`: the service cannot get this kind of information at the moment. - `overloaded`: the service is handling too many requests at the same time. Repeat the request after a short pause, or send fewer requests at the same time. Refused at the gateway: the check could not complete, the account is suspended, or the platform did not answer; each may pass later, and `Retry-After` comes only when the platform did not answer ## Credits Check the live price in the documentation before sending. Platform 2xx and 4xx responses can use credits, including empty data. Gateway refusals and 5xx responses do not use credits. Each pagination request is a separate call. https://monsterapi.co/docs/pricing ## Request template Replace path placeholders and add the required query parameters from the Inputs section before sending. ```shell curl --get 'https://api.monsterapi.co/facebook/api/ads/details' \ -H 'Authorization: Bearer ' ``` --- # Facebook: Ad summaries `GET /facebook/api/ads/library` Documentation: https://monsterapi.co/docs/api/facebook#facebook-ad-summaries Operation ID: `facebook_ads_library_root` Returns ad summaries by keyword, advertiser or ad ID. Give exactly one of q, page_id and ad_id. The country and the filters by delivery status, media type, platforms, languages, advertisers and impression dates narrow a search by q or page_id. With ad_id, a non-default value returns bad_request. ## Authentication Send your billing API key in the `Authorization: Bearer ` header. Your account login is separate. ## Inputs - `q` (query, optional): Keyword to search for. Give exactly one of `q`, `page_id` and `ad_id`. Up to 256 characters of visible text and spaces. Tabs, line breaks and invisible characters return `bad_request`. - `page_id` (query, optional): Advertiser page ID. Give exactly one of `q`, `page_id` and `ad_id`. - `ad_id` (query, optional): Ad archive ID. Give exactly one of `q`, `page_id` and `ad_id`. A lookup by `ad_id` takes no `country` and no filter other than the defaults `country=ALL`, `active_status=all` and `media_type=all`. Another value returns `bad_request`. - `country` (query, optional): Country value in uppercase two-letter form, such as `US`, or `ALL` for every country (default). Syntax is checked; Facebook determines whether a validly formed value is accepted. With `ad_id`, a value other than `ALL` returns `bad_request`. - `active_status` (query, optional): Delivery status of the listed ads: `all` (default), `active` or `inactive`. - `media_type` (query, optional): Media of the listed ads: `all` (default), `image`, `meme`, `image_and_meme`, `video`, or `none` for ads without an image or a video. - `publisher_platforms` (query, optional): Platforms of the listed ads, comma-separated, each at most once: `facebook`, `instagram`, `audience_network`, `messenger`, `whatsapp` and `threads`. Without this parameter, the list includes ads on every platform. - `content_languages` (query, optional): Content languages of the listed ads, comma-separated, each at most once, up to 50. Each value is a lowercase language code of two or three letters, such as `en` or `es`. The service checks only the syntax. A code that Facebook does not know, such as `zz`, returns an empty list. Without this parameter, the list includes ads in every language. - `page_ids` (query, optional): Page IDs of the advertisers of the listed ads, comma-separated, each at most once, up to 50: `ads[].author.id` in [/ads/library](https://monsterapi.co/docs/api/facebook-ads#facebook-ad-summaries). Without this parameter, the list includes ads of every advertiser. - `date_min` (query, optional): First day of the impression date range, `YYYY-MM-DD`. The range includes this day, and the list includes ads with impressions on this day or later. If you also give `date_max`, this day must be earlier. The day must exist in the calendar. Facebook can ignore a range outside the last seven years, such as a future range, and return the list without the date filter. - `date_max` (query, optional): Day after the last day of the impression date range, `YYYY-MM-DD`. The range does not include this day, and the list includes ads with impressions before this day. For a range that ends on 16 October 2026, give `2026-10-17`. The day must exist in the calendar. ## Responses - 200: Requested information in data and its named fields; unavailable optional values are null. - 400: A request parameter is invalid. Refused at the gateway: the request target, path and query string together, is longer than 8,192 bytes; or the headers, the target counted among them, exceed 16,384 bytes or 64 fields - 401: #/components/responses/GatewayUnauthorized - 402: #/components/responses/GatewayPaymentRequired - 403: #/components/responses/GatewayForbidden - 404: The requested object is absent, or Facebook does not show it to logged-out visitors. An empty page of an object that exists does not return `404`. - 405: `method_not_allowed`: the endpoint answers GET alone, and any other method, HEAD included, is refused Refused at the gateway: the path exists, but no operation on it takes the method of the request, HEAD included; `Allow` names the methods that do - 409: #/components/responses/GatewayConflict - 429: `rate_limited`: Facebook limited the requests or asked a logged-out visitor to sign in. Wait for the seconds in `Retry-After`, then repeat the request. Facebook publishes no numbers for these limits. Refused at the gateway: the account calls faster than its rate limit allows - 500: The requested information could not be returned. - 501: The requested information is unavailable without signing in or is not supported. - 503: The requested information is temporarily unavailable. Repeat the request later. `code` gives the cause: - `upstream_error`: no answer came from Facebook, or Facebook answered with a server error. Wait for the seconds in `Retry-After`, then repeat the request. - `upstream_stale`: the service is renewing its access to this information. - `no_proxies`: the service cannot get this kind of information at the moment. - `overloaded`: the service is handling too many requests at the same time. Repeat the request after a short pause, or send fewer requests at the same time. Refused at the gateway: the check could not complete, the account is suspended, or the platform did not answer; each may pass later, and `Retry-After` comes only when the platform did not answer ## Credits Check the live price in the documentation before sending. Platform 2xx and 4xx responses can use credits, including empty data. Gateway refusals and 5xx responses do not use credits. Each pagination request is a separate call. https://monsterapi.co/docs/pricing ## Request template Replace path placeholders and add the required query parameters from the Inputs section before sending. ```shell curl --get 'https://api.monsterapi.co/facebook/api/ads/library' \ -H 'Authorization: Bearer ' ``` --- # Facebook: Ad summaries with pagination `GET /facebook/api/ads/library/page` Documentation: https://monsterapi.co/docs/api/facebook#facebook-ad-summaries-with-pagination Operation ID: `facebook_ads_library_page` Returns further ad summaries after the cursor, which does not carry the filters. Pass cursor and repeat exactly one of q, page_id and ad_id with the same country and filters. ## Authentication Send your billing API key in the `Authorization: Bearer ` header. Your account login is separate. ## Inputs - `q` (query, optional): Same keyword used for the first page. Give exactly one of `q`, `page_id` and `ad_id`. Up to 256 characters of visible text and spaces. Tabs, line breaks and invisible characters return `bad_request`. - `page_id` (query, optional): Same advertiser page ID used for the first page. Give exactly one of `q`, `page_id` and `ad_id`. - `ad_id` (query, optional): Same ad archive ID used for the first page. Give exactly one of `q`, `page_id` and `ad_id`. - `country` (query, optional): Country value in uppercase two-letter form, such as `US`, or `ALL` for every country (default). Syntax is checked; Facebook determines whether a validly formed value is accepted. - `active_status` (query, optional): Delivery status of the listed ads: `all` (default), `active` or `inactive`. - `media_type` (query, optional): Media of the listed ads: `all` (default), `image`, `meme`, `image_and_meme`, `video`, or `none` for ads without an image or a video. - `publisher_platforms` (query, optional): Platforms of the listed ads, comma-separated, each at most once: `facebook`, `instagram`, `audience_network`, `messenger`, `whatsapp` and `threads`. Without this parameter, the list includes ads on every platform. - `content_languages` (query, optional): Content languages of the listed ads, comma-separated, each at most once, up to 50. Each value is a lowercase language code of two or three letters, such as `en` or `es`. The service checks only the syntax. A code that Facebook does not know, such as `zz`, returns an empty list. Without this parameter, the list includes ads in every language. - `page_ids` (query, optional): Page IDs of the advertisers of the listed ads, comma-separated, each at most once, up to 50: `ads[].author.id` in [/ads/library](https://monsterapi.co/docs/api/facebook-ads#facebook-ad-summaries). Without this parameter, the list includes ads of every advertiser. - `date_min` (query, optional): First day of the impression date range, `YYYY-MM-DD`. The range includes this day, and the list includes ads with impressions on this day or later. If you also give `date_max`, this day must be earlier. The day must exist in the calendar. Facebook can ignore a range outside the last seven years, such as a future range, and return the list without the date filter. - `date_max` (query, optional): Day after the last day of the impression date range, `YYYY-MM-DD`. The range does not include this day, and the list includes ads with impressions before this day. For a range that ends on 16 October 2026, give `2026-10-17`. The day must exist in the calendar. - `cursor` (query, required): `next_cursor` from [/ads/library](https://monsterapi.co/docs/api/facebook-ads#facebook-ad-summaries) or this endpoint. Pass it unchanged with the same subject, country and filters. ## Responses - 200: Requested information in data and its named fields; unavailable optional values are null. - 400: A request parameter is invalid. Refused at the gateway: the request target, path and query string together, is longer than 8,192 bytes; or the headers, the target counted among them, exceed 16,384 bytes or 64 fields - 401: #/components/responses/GatewayUnauthorized - 402: #/components/responses/GatewayPaymentRequired - 403: #/components/responses/GatewayForbidden - 404: The requested object is absent, or Facebook does not show it to logged-out visitors. An empty page of an object that exists does not return `404`. - 405: `method_not_allowed`: the endpoint answers GET alone, and any other method, HEAD included, is refused Refused at the gateway: the path exists, but no operation on it takes the method of the request, HEAD included; `Allow` names the methods that do - 409: #/components/responses/GatewayConflict - 429: `rate_limited`: Facebook limited the requests or asked a logged-out visitor to sign in. Wait for the seconds in `Retry-After`, then repeat the request. Facebook publishes no numbers for these limits. Refused at the gateway: the account calls faster than its rate limit allows - 500: The requested information could not be returned. - 501: The requested information is unavailable without signing in or is not supported. - 503: The requested information is temporarily unavailable. Repeat the request later. `code` gives the cause: - `upstream_error`: no answer came from Facebook, or Facebook answered with a server error. Wait for the seconds in `Retry-After`, then repeat the request. - `upstream_stale`: the service is renewing its access to this information. - `no_proxies`: the service cannot get this kind of information at the moment. - `overloaded`: the service is handling too many requests at the same time. Repeat the request after a short pause, or send fewer requests at the same time. Refused at the gateway: the check could not complete, the account is suspended, or the platform did not answer; each may pass later, and `Retry-After` comes only when the platform did not answer ## Credits Check the live price in the documentation before sending. Platform 2xx and 4xx responses can use credits, including empty data. Gateway refusals and 5xx responses do not use credits. Each pagination request is a separate call. https://monsterapi.co/docs/pricing ## Request template Replace path placeholders and add the required query parameters from the Inputs section before sending. ```shell curl --get 'https://api.monsterapi.co/facebook/api/ads/library/page' \ -H 'Authorization: Bearer ' ```