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.
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
Full input JSON Schema
{
"$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 |
Full output JSON Schema
Full output JSON Schema
{
"$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
displayFormatidpageIdpageNameplatformsstartDatetext
Not found, and how it differs from empty
When the entity does not exist, answer 2xx with the not-found shape:{
"found": false,
"data": null
}
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
{
"pageId": "15087023444",
"sortBy": "recent"
}
Next
- The operator endpoint contract for signing, budgets, and the live trial.
- Every API open to sellers.
- Want to sell an API that is not on that list? Email support@getanyapi.com.