api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "ads": {
          "description": "Ads returned for the requested company or page. This array may be empty when the lookup resolves but no ads match the filters.",
          "items": {
            "description": "A single Facebook company ad.",
            "properties": {
              "adId": {
                "description": "Platform ad id when available.",
                "nullable": true,
                "type": "string"
              },
              "campaign": {
                "description": "Campaign collation metadata for this ad.",
                "properties": {
                  "collationCount": {
                    "description": "Number of ads in the campaign collation when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "collationId": {
                    "description": "Campaign collation id when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "collationId",
                  "collationCount"
                ],
                "type": "object"
              },
              "categories": {
                "description": "Ad categories reported by the platform.",
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              "countries": {
                "description": "Countries targeted or reached by the ad when available.",
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              "creative": {
                "description": "Creative content for this ad.",
                "properties": {
                  "bodyText": {
                    "description": "Primary ad body text when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "callToAction": {
                    "description": "Call-to-action label when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "caption": {
                    "description": "Ad caption when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "cards": {
                    "description": "Carousel cards attached to the creative.",
                    "items": {
                      "description": "Carousel card for a Facebook ad creative.",
                      "properties": {
                        "body": {
                          "description": "Card body text when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "caption": {
                          "description": "Card caption when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "imageUrl": {
                          "description": "Card image URL when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "linkUrl": {
                          "description": "Card link URL when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "title": {
                          "description": "Card title when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "videoUrl": {
                          "description": "Card video URL when available.",
                          "nullable": true,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "body",
                        "caption",
                        "linkUrl",
                        "imageUrl",
                        "videoUrl"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "displayFormat": {
                    "description": "Display format for the creative when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "images": {
                    "description": "Image assets attached to the creative.",
                    "items": {
                      "description": "Image asset for a Facebook ad creative.",
                      "properties": {
                        "height": {
                          "description": "Image height in pixels when available.",
                          "minimum": 0,
                          "type": "integer"
                        },
                        "url": {
                          "description": "Image URL when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "width": {
                          "description": "Image width in pixels when available.",
                          "minimum": 0,
                          "type": "integer"
                        }
                      },
                      "required": [
                        "url"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "linkDescription": {
                    "description": "Link description when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "linkUrl": {
                    "description": "Primary link URL when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "title": {
                    "description": "Ad title when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "videos": {
                    "description": "Video assets attached to the creative.",
                    "items": {
                      "description": "Video asset for a Facebook ad creative.",
                      "properties": {
                        "hdUrl": {
                          "description": "High-definition video URL when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "previewImageUrl": {
                          "description": "Video preview image URL when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "sdUrl": {
                          "description": "Standard-definition video URL when available.",
                          "nullable": true,
                          "type": "string"
                        }
                      },
                      "required": [
                        "hdUrl",
                        "sdUrl",
                        "previewImageUrl"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "bodyText",
                  "title",
                  "caption",
                  "linkUrl",
                  "linkDescription",
                  "callToAction",
                  "displayFormat",
                  "images",
                  "videos",
                  "cards"
                ],
                "type": "object"
              },
              "endedAt": {
                "description": "ISO-8601 timestamp for when the ad ended, when available.",
                "nullable": true,
                "type": "string"
              },
              "id": {
                "description": "Stable identifier for the ad.",
                "minLength": 1,
                "type": "string"
              },
              "impressions": {
                "description": "Impressions metadata when available.",
                "nullable": true,
                "properties": {
                  "index": {
                    "description": "Impressions index when available.",
                    "nullable": true,
                    "type": "integer"
                  },
                  "text": {
                    "description": "Human-readable impressions label when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "index"
                ],
                "type": "object"
              },
              "isActive": {
                "description": "Whether the ad is currently active.",
                "type": "boolean"
              },
              "page": {
                "description": "Advertiser page summary for this ad.",
                "properties": {
                  "id": {
                    "description": "Facebook page id for the advertiser when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "isDeleted": {
                    "description": "Whether the advertiser page is marked deleted.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "name": {
                    "description": "Display name for the advertiser page when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "profilePictureUrl": {
                    "description": "Profile picture URL for the advertiser page when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "url": {
                    "description": "Public Facebook URL for the advertiser page when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "url",
                  "isDeleted",
                  "profilePictureUrl"
                ],
                "type": "object"
              },
              "publisherPlatforms": {
                "description": "Publisher platforms where the ad ran or is running.",
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              "spend": {
                "description": "Spend metadata when available.",
                "nullable": true,
                "properties": {
                  "amount": {
                    "description": "Spend amount text when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "currency": {
                    "description": "Currency code for spend when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "amount",
                  "currency"
                ],
                "type": "object"
              },
              "startedAt": {
                "description": "ISO-8601 timestamp for when the ad started, when available.",
                "nullable": true,
                "type": "string"
              },
              "url": {
                "description": "Public Facebook Ad Library URL for this ad when available.",
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "id",
              "adId",
              "url",
              "page",
              "campaign",
              "isActive",
              "publisherPlatforms",
              "startedAt",
              "endedAt",
              "categories",
              "countries",
              "impressions",
              "spend",
              "creative"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "lookupStatus": {
          "description": "Whether the company or page resolved for this request.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        },
        "page": {
          "description": "Pagination information for the current response.",
          "properties": {
            "hasMore": {
              "description": "Whether another page of ads can be requested.",
              "type": "boolean"
            },
            "nextCursor": {
              "description": "Cursor to pass as `cursor` in the next request when `hasMore` is true; otherwise null.",
              "nullable": true,
              "type": "string"
            }
          },
          "required": [
            "nextCursor",
            "hasMore"
          ],
          "type": "object"
        }
      },
      "required": [
        "lookupStatus",
        "ads",
        "page"
      ],
      "type": "object"
    },
    "meta": {
      "description": "Metadata describing the request and billing outcome.",
      "properties": {
        "cached": {
          "description": "True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.",
          "type": "boolean"
        },
        "creditsCharged": {
          "description": "Credits charged for this request.",
          "minimum": 0,
          "type": "integer"
        },
        "requestId": {
          "description": "Unique request identifier for tracing this API call.",
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Public API version that served the response.",
          "enum": [
            "v1"
          ],
          "type": "string"
        }
      },
      "required": [
        "requestId",
        "creditsCharged",
        "version"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "type": "object"
}