TIKTOK AD LIBRARY API

Ad Library Search

Retrieve ad library search from TikTok Ad Library with a single API request.

GET/api/data/v1/tiktok/ad-library/search
1credit base cost

Request parameters

Up to 1 credit

General ad search. Provide either query or advertiser_name, not both.

Advertiser name to resolve through TikTok's typeahead and search by advertiser entity. Falls back to TikTok's name search when no entity matches. Provide either advertiser_name or query, not both.

TikTok advertiser business ID from a See all ads link. Use it with advertiser_name to pin the exact advertiser. Required companion: advertiser_name; ID-only searches return 400 because TikTok ignores the ID without the name.

Inclusive lower bound for the ad's last shown date; end_time is the inclusive upper bound. Supply start_time and end_time together as positive base-10 safe integers, no greater than 9007199254740991, in Unix seconds (preferred) or milliseco

Inclusive upper bound for the ad's last shown date; start_time is the inclusive lower bound. Supply start_time and end_time together as positive base-10 safe integers, no greater than 9007199254740991, in Unix seconds (preferred) or millise

Filter by the ad's targeting/delivery country, not the advertiser's registration country. Omitted region defaults to all supported countries, not every country worldwide. Values are case-insensitive; choose all or one of the listed country

Opaque cursor returned from the previous response. Repeat the same query or advertiser_name, adv_biz_ids when used, and any explicit start_time, end_time and region filters with every returned cursor. Pass the cursor unchanged; it does not

Try in the console

Live requests use your prepaid balance. Cached responses cost zero where supported.

curl --request GET \
  --url 'https://fetchgoblin.com/api/data/v1/tiktok/ad-library/search?query=The+Creator+Loop' \
  --header 'x-api-key: YOUR_FETCHGOBLIN_API_KEY'

Response

Example
{
  "success": true,
  "source": "tiktok_public_ads_library",
  "advertiser_name": "Gymshark",
  "resolved_advertiser_name": "GYMSHARK LTD",
  "advertiser_matches": [
    {
      "name": "GYMSHARK LTD",
      "ids": "7078923208527618049"
    }
  ],
  "ads": [
    {
      "id": "1871655924410641",
      "url": "https://library.tiktok.com/ads/detail/?ad_id=1871655924410641",
      "name": "GYMSHARK LTD",
      "adv_biz_ids": "7078923208527618049",
      "audit_status": "1",
      "type": "2",
      "first_shown_date": 1784937600000,
      "last_shown_date": 1785024000000,
      "videos": [
        {
          "video_url": "https://library.tiktok.com/api/v1/cdn/...",
          "cover_img": "https://p16-common-sign.tiktokcdn.com/..."
        }
      ],
      "estimated_audience": "1K-10K",
      "spent": "",
      "impression": 0,
      "show_mode": 1,
      "image_urls": [],
      "rejection_info": null,
      "sor_audit_status": "1"
    }
  ],
  "total": 62344,
  "has_more": true,
  "cursor": "opaque cursor for the next page",
  "credits_charged": 1,
  "credits_remaining": 1000,
  "request_id": "00000000-0000-4000-8000-000000000000"
}
Illustrative response with example values adapted for FetchGoblin. Run a request to retrieve current platform data.

Response shape

This schema describes the documented data shape. Some platform fields may be absent or null. The response also includes your FetchGoblin request ID and current credit balance.

View JSON Schema +
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "source": {
      "type": "string"
    },
    "advertiser_name": {
      "type": "string"
    },
    "resolved_advertiser_name": {
      "type": "string"
    },
    "advertiser_matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "ids": {
            "type": "string"
          }
        }
      }
    },
    "ads": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "adv_biz_ids": {
            "type": "string"
          },
          "audit_status": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "first_shown_date": {
            "type": "integer"
          },
          "last_shown_date": {
            "type": "integer"
          },
          "videos": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "video_url": {
                  "type": "string"
                },
                "cover_img": {
                  "type": "string"
                }
              }
            }
          },
          "estimated_audience": {
            "type": "string"
          },
          "spent": {
            "type": "string"
          },
          "impression": {
            "type": "integer"
          },
          "show_mode": {
            "type": "integer"
          },
          "image_urls": {
            "type": "array"
          },
          "rejection_info": {
            "type": [
              "string",
              "object",
              "array",
              "number",
              "boolean",
              "null"
            ]
          },
          "sor_audit_status": {
            "type": "string"
          }
        }
      }
    },
    "total": {
      "type": "integer"
    },
    "has_more": {
      "type": "boolean"
    },
    "cursor": {
      "type": "string"
    },
    "credits_charged": {
      "type": "integer",
      "minimum": 0,
      "description": "FetchGoblin credits charged for this request."
    },
    "credits_remaining": {
      "type": "integer",
      "description": "Your FetchGoblin credit balance after this request."
    },
    "request_id": {
      "type": "string",
      "format": "uuid",
      "description": "FetchGoblin request identifier."
    }
  }
}