api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "ads": {
          "description": "Ads returned for the requested search. This array may be empty when no ads match the filters.",
          "items": {
            "description": "Summary of a TikTok Ad Library ad.",
            "properties": {
              "brandName": {
                "description": "Brand or advertiser name when available.",
                "nullable": true,
                "type": "string"
              },
              "cost": {
                "description": "Relative cost signal when available.",
                "nullable": true,
                "type": "number"
              },
              "ctr": {
                "description": "Click-through rate when available.",
                "nullable": true,
                "type": "number"
              },
              "id": {
                "description": "Stable identifier for the ad.",
                "minLength": 1,
                "type": "string"
              },
              "industryKey": {
                "description": "Industry key reported for the ad when available.",
                "nullable": true,
                "type": "string"
              },
              "likeCount": {
                "description": "Like count when available.",
                "minimum": 0,
                "nullable": true,
                "type": "integer"
              },
              "objective": {
                "description": "Campaign objective key when available.",
                "nullable": true,
                "type": "string"
              },
              "title": {
                "description": "Ad title or caption when available.",
                "nullable": true,
                "type": "string"
              },
              "video": {
                "description": "Video creative when available.",
                "nullable": true,
                "properties": {
                  "coverUrl": {
                    "description": "Cover image URL when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "durationSeconds": {
                    "description": "Video duration in seconds when available.",
                    "nullable": true,
                    "type": "number"
                  },
                  "height": {
                    "description": "Video height in pixels when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "id": {
                    "description": "Video id when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "urls": {
                    "description": "Playback URLs by resolution when available.",
                    "nullable": true,
                    "properties": {
                      "p1080": {
                        "description": "1080p video URL when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "p360": {
                        "description": "360p video URL when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "p480": {
                        "description": "480p video URL when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "p540": {
                        "description": "540p video URL when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "p720": {
                        "description": "720p video URL when available.",
                        "nullable": true,
                        "type": "string"
                      }
                    },
                    "required": [
                      "p360",
                      "p480",
                      "p540",
                      "p720",
                      "p1080"
                    ],
                    "type": "object"
                  },
                  "width": {
                    "description": "Video width in pixels when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "required": [
                  "id",
                  "durationSeconds",
                  "coverUrl",
                  "width",
                  "height",
                  "urls"
                ],
                "type": "object"
              }
            },
            "required": [
              "id",
              "title",
              "brandName",
              "cost",
              "ctr",
              "likeCount",
              "industryKey",
              "objective",
              "video"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "advertiserName": {
          "description": "Advertiser name filter that was evaluated, when searching the public Ads Library.",
          "nullable": true,
          "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"
            },
            "totalResultsEstimate": {
              "description": "Estimated total number of matching ads when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            }
          },
          "required": [
            "nextCursor",
            "hasMore",
            "totalResultsEstimate"
          ],
          "type": "object"
        },
        "query": {
          "description": "Keyword query that was evaluated for this response.",
          "type": "string"
        }
      },
      "required": [
        "query",
        "advertiserName",
        "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"
}