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

queryoptional

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

advertiser_nameoptional

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.

adv_biz_idsoptional

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.

cursoroptional

Opaque cursor returned from the previous response.

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"
}

Example data from the API specification. Run a request to retrieve current 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."
    }
  }
}

More TikTok Ad Library endpoints Errors and credit accounting