api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "ad": {
          "description": "Ad details when found; otherwise null.",
          "nullable": true,
          "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"
                },
                "callToActionType": {
                  "description": "Call-to-action type 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 Library 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 Library ad creative.",
                    "properties": {
                      "resizedUrl": {
                        "description": "Resized image URL when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "url": {
                        "description": "Image URL when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "watermarkedResizedUrl": {
                        "description": "Watermarked resized image URL when available.",
                        "nullable": true,
                        "type": "string"
                      }
                    },
                    "required": [
                      "url",
                      "resizedUrl",
                      "watermarkedResizedUrl"
                    ],
                    "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 Library 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",
                "callToActionType",
                "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": {
                "categories": {
                  "description": "Public categories for the advertiser page when available.",
                  "items": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "type": "array"
                },
                "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"
                },
                "likeCount": {
                  "description": "Advertiser page like count when available.",
                  "minimum": 0,
                  "nullable": true,
                  "type": "integer"
                },
                "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",
                "likeCount",
                "categories"
              ],
              "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"
        },
        "lookupStatus": {
          "description": "Whether the ad was found in the Ad Library.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        },
        "transcript": {
          "description": "Plain transcript text when requested and available. May be null when speech is not detected, the video exceeds supported length, or transcription is otherwise unavailable.",
          "nullable": true,
          "type": "string"
        }
      },
      "required": [
        "lookupStatus",
        "ad",
        "transcript"
      ],
      "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"
}