> ## Documentation Index
> Fetch the complete documentation index at: https://getanyapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Facebook Company Ads

> Sell facebook.company_ads on AnyAPI: the request your endpoint receives, the response it must return, and what the live trial grades.

List the Meta Ad Library ads a company is running by page ID or company name (creative text, format, platforms, and run dates) with cursor pagination.

This page is the seller-facing summary of one catalog API, `facebook.company_ads`. The transport rules that apply to every API a seller serves - signed requests, the response envelope, timeouts, and body limits - are on [the operator endpoint contract](https://getanyapi.com/docs/sell/operator-endpoint-contract.md).

## The price you compete with

AnyAPI publishes this API from **\$1.10 per 1,000 requests**. That is the price a buyer sees today, so it is the price your endpoint has to come in under to win traffic.

## The request your endpoint receives

This API takes no input fields.

> **Full input JSON Schema**
>
> ```json theme={"dark"}
> {
>   "$schema": "https://json-schema.org/draft/2020-12/schema",
>   "$id": "https://getanyapi.com/schemas/facebook.company_ads.input.json",
>   "example": {
>     "pageId": "15087023444",
>     "sortBy": "recent"
>   },
>   "title": "Facebook company ads input",
>   "type": "object",
>   "additionalProperties": false,
>   "anyOf": [
>     {
>       "required": [
>         "pageId"
>       ]
>     },
>     {
>       "required": [
>         "companyName"
>       ]
>     }
>   ],
>   "properties": {
>     "pageId": {
>       "type": "string",
>       "minLength": 1,
>       "description": "Company's Ad Library page ID. Provide either pageId or companyName."
>     },
>     "companyName": {
>       "type": "string",
>       "minLength": 1,
>       "description": "Company name to search (e.g. \"nike\"). Exact-match and case-sensitive against the Meta Ad Library index; an advertiser with no indexed page returns found:false."
>     },
>     "country": {
>       "type": "string",
>       "description": "Two-letter country code to scope results. Defaults to all countries."
>     },
>     "status": {
>       "type": "string",
>       "enum": [
>         "ALL",
>         "ACTIVE",
>         "INACTIVE"
>       ],
>       "description": "Ad status filter. Defaults to ACTIVE."
>     },
>     "mediaType": {
>       "type": "string",
>       "enum": [
>         "ALL",
>         "IMAGE",
>         "VIDEO",
>         "MEME",
>         "IMAGE_AND_MEME",
>         "NONE"
>       ],
>       "description": "Creative media type filter."
>     },
>     "language": {
>       "type": "string",
>       "description": "Two-letter language code to filter ads (e.g. \"EN\", \"ES\", \"FR\")."
>     },
>     "sortBy": {
>       "type": "string",
>       "enum": [
>         "impressions",
>         "recent"
>       ],
>       "description": "Sort order: impressions (highest first, the default) or recent (most recent)."
>     },
>     "startDate": {
>       "type": "string",
>       "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$",
>       "description": "Filter to ads with impressions on or after this date, in YYYY-MM-DD format."
>     },
>     "endDate": {
>       "type": "string",
>       "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$",
>       "description": "Filter to ads with impressions on or before this date, in YYYY-MM-DD format."
>     },
>     "cursor": {
>       "type": "string",
>       "description": "Opaque pagination cursor from a previous response's nextCursor."
>     }
>   }
> }
> ```

## The response your endpoint must return

| Field | Type | Always present | What it means |
| - | - | - | - |
| `data` | null or object | yes | |
| `data.ads` | array | yes | |
| `data.ads[].active` | boolean | yes | |
| `data.ads[].adCount` | integer or null | yes | Number of ads in this campaign (collation count). Null when the source does not report it. |
| `data.ads[].caption` | string | no | Caption line of the ad creative, usually the advertiser's display domain. |
| `data.ads[].categories` | array | no | Ad Library categories the ad is filed under. |
| `data.ads[].creatives` | array | no | One entry per card of a carousel, dynamic-product, or dynamic-creative ad, in the order Meta returns them, each with its own text and destination. Single-creative ads return an empty array. The same card images and videos also appear in media. Meta CDN media URLs are signed and expire. |
| `data.ads[].creatives[].body` | string | no | Card body text. |
| `data.ads[].creatives[].caption` | string | no | Card display caption, usually the destination domain. |
| `data.ads[].creatives[].ctaText` | string | no | Card call-to-action label (e.g. "Shop Now"). |
| `data.ads[].creatives[].ctaType` | string | no | Card call-to-action type (e.g. "SHOP\_NOW"). |
| `data.ads[].creatives[].image` | string | no | Card image URL. For a video card this is the poster frame. |
| `data.ads[].creatives[].linkDescription` | string | no | Card secondary description line. |
| `data.ads[].creatives[].linkUrl` | string | no | Card destination URL. |
| `data.ads[].creatives[].title` | string | no | Card headline. |
| `data.ads[].creatives[].videoUrl` | string | no | Card video file URL (HD when supplied, otherwise SD). Present only on video cards. |
| `data.ads[].ctaText` | string | no | Call-to-action button label on the ad. |
| `data.ads[].ctaType` | string | no | Call-to-action button type on the ad, e.g. "SHOP\_NOW". |
| `data.ads[].currency` | string | yes | |
| `data.ads[].displayFormat` | string | yes | |
| `data.ads[].endDate` | integer | yes | Epoch seconds. |
| `data.ads[].id` | string | yes | Ad Library archive ID. |
| `data.ads[].isReshared` | boolean | no | Whether the ad creative is a reshare of another post. |
| `data.ads[].linkDescription` | string | no | Description text shown under the ad's link. |
| `data.ads[].linkUrl` | string | no | Destination URL the ad links to. |
| `data.ads[].media` | array | no | Creative attached to the ad: one element per image, video, or carousel card, in the order the ad presents them. Empty when the ad has none. |
| `data.ads[].media[].height` | integer | no | Pixel height of the media item, when the lane reports it. |
| `data.ads[].media[].type` | string | yes | One of photo, video, or gif. |
| `data.ads[].media[].url` | string | yes | Image URL. For a video or GIF this is the poster/thumbnail frame. |
| `data.ads[].media[].videoUrl` | string | no | Playable video file URL. Present only for video and gif items. |
| `data.ads[].media[].width` | integer | no | Pixel width of the media item, when the lane reports it. |
| `data.ads[].pageCategories` | array | no | Categories Facebook lists the advertising page under. |
| `data.ads[].pageDeleted` | boolean | no | Whether the advertising page has been deleted. |
| `data.ads[].pageId` | string | yes | |
| `data.ads[].pageLikes` | integer | no | Like count of the advertising page. |
| `data.ads[].pageName` | string | yes | |
| `data.ads[].pageProfilePicture` | string | no | Profile picture of the advertising page. This is the advertiser's identity image, not ad creative. |
| `data.ads[].pageUrl` | string | no | Canonical Facebook URL of the advertising page. |
| `data.ads[].platforms` | array | yes | |
| `data.ads[].startDate` | integer | yes | Epoch seconds. |
| `data.ads[].text` | string | yes | Ad body text. |
| `data.ads[].title` | string | no | Headline of the ad creative. |
| `data.nextCursor` | string or null | yes | Opaque cursor for the next page of ads, or null when this lane has no more. Pass it back as cursor to continue. |
| `data.totalResults` | integer | no | Total number of ads Facebook reports for the page. |
| `found` | boolean | yes | |

Extra fields are kept, missing declared fields fail.

> **Full output JSON Schema**
>
> ```json theme={"dark"}
> {
>   "$schema": "https://json-schema.org/draft/2020-12/schema",
>   "$id": "https://getanyapi.com/schemas/facebook.company_ads.output.json",
>   "title": "Facebook company ads output",
>   "type": "object",
>   "additionalProperties": false,
>   "required": [
>     "found",
>     "data"
>   ],
>   "properties": {
>     "found": {
>       "type": "boolean"
>     },
>     "data": {
>       "oneOf": [
>         {
>           "type": "null"
>         },
>         {
>           "type": "object",
>           "additionalProperties": false,
>           "required": [
>             "nextCursor",
>             "ads"
>           ],
>           "properties": {
>             "nextCursor": {
>               "type": [
>                 "string",
>                 "null"
>               ],
>               "description": "Opaque cursor for the next page of ads, or null when this lane has no more. Pass it back as cursor to continue."
>             },
>             "ads": {
>               "type": "array",
>               "items": {
>                 "type": "object",
>                 "required": [
>                   "id",
>                   "pageId",
>                   "pageName",
>                   "active",
>                   "startDate",
>                   "endDate",
>                   "currency",
>                   "text",
>                   "displayFormat",
>                   "platforms",
>                   "adCount"
>                 ],
>                 "properties": {
>                   "id": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string",
>                     "description": "Ad Library archive ID."
>                   },
>                   "pageId": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string"
>                   },
>                   "pageName": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string"
>                   },
>                   "active": {
>                     "type": "boolean"
>                   },
>                   "startDate": {
>                     "x-anyapi-must-populate": true,
>                     "type": "integer",
>                     "description": "Epoch seconds."
>                   },
>                   "endDate": {
>                     "type": "integer",
>                     "description": "Epoch seconds."
>                   },
>                   "currency": {
>                     "type": "string"
>                   },
>                   "text": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string",
>                     "description": "Ad body text."
>                   },
>                   "displayFormat": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string"
>                   },
>                   "platforms": {
>                     "x-anyapi-must-populate": true,
>                     "type": "array",
>                     "items": {
>                       "type": "string"
>                     }
>                   },
>                   "adCount": {
>                     "type": [
>                       "integer",
>                       "null"
>                     ],
>                     "description": "Number of ads in this campaign (collation count). Null when the source does not report it."
>                   },
>                   "pageProfilePicture": {
>                     "type": "string",
>                     "format": "uri",
>                     "description": "Profile picture of the advertising page. This is the advertiser's identity image, not ad creative."
>                   },
>                   "media": {
>                     "type": "array",
>                     "description": "Creative attached to the ad: one element per image, video, or carousel card, in the order the ad presents them. Empty when the ad has none.",
>                     "items": {
>                       "type": "object",
>                       "required": [
>                         "type",
>                         "url"
>                       ],
>                       "properties": {
>                         "type": {
>                           "type": "string",
>                           "description": "One of photo, video, or gif."
>                         },
>                         "url": {
>                           "type": "string",
>                           "format": "uri",
>                           "description": "Image URL. For a video or GIF this is the poster/thumbnail frame."
>                         },
>                         "videoUrl": {
>                           "type": "string",
>                           "format": "uri",
>                           "description": "Playable video file URL. Present only for video and gif items."
>                         },
>                         "width": {
>                           "type": "integer",
>                           "description": "Pixel width of the media item, when the lane reports it."
>                         },
>                         "height": {
>                           "type": "integer",
>                           "description": "Pixel height of the media item, when the lane reports it."
>                         }
>                       }
>                     }
>                   },
>                   "creatives": {
>                     "type": "array",
>                     "description": "One entry per card of a carousel, dynamic-product, or dynamic-creative ad, in the order Meta returns them, each with its own text and destination. Single-creative ads return an empty array. The same card images and videos also appear in media. Meta CDN media URLs are signed and expire.",
>                     "items": {
>                       "type": "object",
>                       "properties": {
>                         "title": {
>                           "type": "string",
>                           "description": "Card headline."
>                         },
>                         "body": {
>                           "type": "string",
>                           "description": "Card body text."
>                         },
>                         "caption": {
>                           "type": "string",
>                           "description": "Card display caption, usually the destination domain."
>                         },
>                         "linkUrl": {
>                           "type": "string",
>                           "description": "Card destination URL."
>                         },
>                         "linkDescription": {
>                           "type": "string",
>                           "description": "Card secondary description line."
>                         },
>                         "ctaText": {
>                           "type": "string",
>                           "description": "Card call-to-action label (e.g. \"Shop Now\")."
>                         },
>                         "ctaType": {
>                           "type": "string",
>                           "description": "Card call-to-action type (e.g. \"SHOP_NOW\")."
>                         },
>                         "image": {
>                           "type": "string",
>                           "description": "Card image URL. For a video card this is the poster frame."
>                         },
>                         "videoUrl": {
>                           "type": "string",
>                           "description": "Card video file URL (HD when supplied, otherwise SD). Present only on video cards."
>                         }
>                       }
>                     }
>                   },
>                   "caption": {
>                     "type": "string",
>                     "description": "Caption line of the ad creative, usually the advertiser's display domain."
>                   },
>                   "linkDescription": {
>                     "type": "string",
>                     "description": "Description text shown under the ad's link."
>                   },
>                   "pageUrl": {
>                     "type": "string",
>                     "description": "Canonical Facebook URL of the advertising page."
>                   },
>                   "pageCategories": {
>                     "type": "array",
>                     "items": {
>                       "type": "string"
>                     },
>                     "description": "Categories Facebook lists the advertising page under."
>                   },
>                   "pageLikes": {
>                     "type": "integer",
>                     "description": "Like count of the advertising page."
>                   },
>                   "isReshared": {
>                     "type": "boolean",
>                     "description": "Whether the ad creative is a reshare of another post."
>                   },
>                   "pageDeleted": {
>                     "type": "boolean",
>                     "description": "Whether the advertising page has been deleted."
>                   },
>                   "categories": {
>                     "type": "array",
>                     "items": {
>                       "type": "string"
>                     },
>                     "description": "Ad Library categories the ad is filed under."
>                   },
>                   "title": {
>                     "type": "string",
>                     "description": "Headline of the ad creative."
>                   },
>                   "ctaText": {
>                     "type": "string",
>                     "description": "Call-to-action button label on the ad."
>                   },
>                   "ctaType": {
>                     "type": "string",
>                     "description": "Call-to-action button type on the ad, e.g. \"SHOP_NOW\"."
>                   },
>                   "linkUrl": {
>                     "type": "string",
>                     "description": "Destination URL the ad links to."
>                   }
>                 }
>               }
>             },
>             "totalResults": {
>               "type": "integer",
>               "description": "Total number of ads Facebook reports for the page."
>             }
>           }
>         }
>       ]
>     }
>   }
> }
> ```

## Fields that must never come back empty

* `displayFormat`
* `id`
* `pageId`
* `pageName`
* `platforms`
* `startDate`
* `text`

The repository marks these fields as ones every source must be able to fill. An empty value is only correct when the entity itself genuinely has nothing there.

## Not found, and how it differs from empty

When the entity does not exist, answer 2xx with the not-found shape:

```json theme={"dark"}
{
  "found": false,
  "data": null
}
```

An empty list is not a not-found: when the entity exists and has nothing to return, answer 2xx with `found: true` and an empty `ads` array.

This output schema declares no `reason` field, so `found: false` is the whole not-found answer.

## Example request

```json theme={"dark"}
{
  "pageId": "15087023444",
  "sortBy": "recent"
}
```

The compatibility checks fire the schema's example at your endpoint. After that, your answers are graded against what the currently serving source returned for the same real customer inputs.

## Next

* [The operator endpoint contract](https://getanyapi.com/docs/sell/operator-endpoint-contract.md) for signing, budgets, and the live trial.
* [Every API open to sellers](https://getanyapi.com/docs/sell/apis/index.md).
* Want to sell an API that is not on that list? Email [support@getanyapi.com](mailto:support@getanyapi.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.