Facebook Ads API

GET | POST /v1/facebook/ads

Send parameters as a query string with GET, or as a JSON body with POST. Both are equivalent.

Request

curl "https://gateway.apinoa.com/v1/facebook/ads?pageId=103032366405927&country=US" \
  -H "x-api-key: $APINOA_API_KEY"

What to Pass

Pass	Reads	Notes
`query`	Ads matching the keywords	`exact` matches the whole phrase
`pageId`	Every ad one advertiser runs	The numeric Page id; `profile` returns it as `id`

Pass query or pageId. The filters (country, status, adType, mediaType, platforms, languages, startDate, endDate, sort) work with either.

Parameters

Parameter	Type	Notes
`adType`	enum	all (default), or one special category: political (social issues, elections or politics), housing, employment, credit. `all` `political` `housing` `employment` `credit`
`country`	string	Where the ads ran: an ISO 3166-1 alpha-2 code, or ALL (default).
`cursor`	string	Opaque cursor from the previous page's `cursor`. Pass it alone for the next page.
`endDate`	string	Only ads that started running on or before this day (YYYY-MM-DD).
`exact`	boolean	query: match the exact phrase instead of any of its words.
`languages`	string list	Only ads in these languages (ISO 639-1).
`mediaType`	enum	all (default), image, video, meme, image_and_meme, none. `all` `image` `video` `meme` `image_and_meme` `none`
`pageId`	string	Every ad one advertiser runs: its numeric Page id (`profile` returns it as `id`).
`platforms`	string list	Only ads that ran on these platforms.
`query`	string	Keywords to search the Ad Library for.
`sort`	enum	relevance (default), or impressions (highest first; Facebook states impressions for political ads). `relevance` `impressions`
`startDate`	string	Only ads that started running on or after this day (YYYY-MM-DD).
`status`	enum	active (default), inactive or all. `active` `inactive` `all`

The same parameters, and every response type, are in the OpenAPI document.

Response

Returns Page of Ad in data. A real response, shortened: arrays keep their first entries and long text is cut.

{
  "success": true,
  "data": {
    "platform": "facebook",
    "items": [
      {
        "platform": "facebook",
        "id": "3976964025794051",
        "url": "https://www.facebook.com/ads/library/?id=3976964025794051",
        "active": true,
        "startedAt": "2026-09-25T07:00:00.000Z",
        "endedAt": "2026-11-07T08:00:00.000Z",
        "platforms": [
          "facebook"
        ],
        "page": {
          "id": "103032366405927",
          "name": "HOKA",
          "url": "https://www.facebook.com/hoka/",
          "avatarUrl": "https://scontent-sjc6-1.xx.fbcdn.net/v/t39.35426-6/825336657_180203818…",
          "likes": 1228615,
          "categories": [
            "Outdoor & Sporting Goods Company"
          ]
        },
        "format": "DPA",
        "title": "HOKA",
        "body": "You were so close to your new favorite pair of shoes.",
        "caption": "HOKA.COM",
        "linkUrl": "https://www.hoka.com/en/us/membership/?utm_source=facebookinstagram&ut…",
        "ctaText": "Shop now",
        "ctaType": "SHOP_NOW",
        "images": [],
        "videos": [],
        "cards": [
          {
            "title": "HOKA",
            "body": "You were so close to your new favorite pair of shoes.",
            "caption": "hoka.com",
            "linkUrl": "https://www.hoka.com/en/us/womens-recovery-comfort-shoes/bondi-sr/192410928866.html",
            "linkDescription": "Join the HOKA® membership program for free shipping, 60 day free retur…",
            "ctaText": "Shop Now",
            "ctaType": "SHOP_NOW",
            "image": {
              "url": "https://scontent-sjc3-1.xx.fbcdn.net/v/t39.35426-6/825336518_112375061…",
              "resizedUrl": "https://scontent-sjc3-1.xx.fbcdn.net/v/t39.35426-6/825336518_112375061…"
            }
          }
        ],
        "ext": {
          "has_user_reported": false,
          "gated_type": "ELIGIBLE",
          "is_aaa_eligible": false,
          "regional_regulation_data": {
            "finserv": {
              "is_deemed_finserv": false,
              "is_limited_delivery": false
            },
            "tw_anti_scam": {
              "is_limited_delivery": false
            }
          },
          "hide_data_status": "NONE",
          "snapshot": {
            "is_reshared": false
          }
        }
      }
    ],
    "total": 76,
    "ext": {
      "pageId": "103032366405927",
      "searchType": "page",
      "countries": [
        "US"
      ],
      "status": "active",
      "adType": "all",
      "mediaType": "all"
    },
    "cursor": "wolqmF7MPrf2JKaKI1y_9VZxaa2iDzDeS7f-FTs2d0zUKqI_bJfat3T4LfV8QiVXZwwwg3…"
  }
}

Errors

Status	Code	Meaning
400	`INVALID_CURSOR`	The `cursor` is not one this operation returned. Start again without it.
400	`INVALID_PARAMS`	A parameter is missing, unknown or out of range. The message names it.
401	`UNAUTHORIZED`	The `x-api-key` header is missing, or the key is revoked or unknown.
402	`INSUFFICIENT_BALANCE`	The balance does not cover this call. Top up in the dashboard.
429	`MARKETPLACE_SATURATED`	Too many concurrent calls. Retry after the `Retry-After` seconds.
502	`UPSTREAM_ERROR`	The platform answered with something unusable. Retry with backoff.

Every code is listed in Errors. Failed calls are not billed.

Pricing

Price $0.001 per call. List price; the rate steps down above 1,000 calls a day.

Notes

A Facebook-only record; its fields are shown in the response.
total is how many ads match, exactly as the Ad Library states it. Above 50,000 it states only that many or more, and the answer carries totalAtLeast instead.
Ads about social issues, elections or politics (adType=political) also carry spend, impressions, reach, currency and who paid for them (disclaimer).
For the next page, pass cursor alone.

Ads