Ad Library Search

Immutable Catalog Entry

This descriptor comes from the active versioned Portal catalog.

READscrape-creators.scrape_creators_tiktok_ad_library_get_v1_tiktok_ad_library_search

• Contract tier: legacy
• Risk: read
• Catalog version: scrape-creators-2026.07.12.1
• Descriptor hash: 1641b010ebe396071d502bbca0d8016df347e1dabaa6219388ecc554a85e33d0

Use this when you need ScrapeCreators TikTok Ad Library data from GET /v1/tiktok/ad-library/search for Ad Library Search. Searches TikTok Creative Center Top Ads, the ad library page at ads.tiktok.com/business/creativecenter/inspiration/topads. Supports US and other 2-letter regions, period filters, sorting, keyword search, and cursor pagination. Returns TikTok's public top ad material objects, including ad title, metrics, video info, landing page, and pagination. Returns the ScrapeCreators response in the standard MCP envelope with ok/data/error/meta. This is read-only. Requires the portal grant header and a ScrapeCreators BYOK API key.

Request Body

{
  "jsonrpc": "2.0",
  "id": "scrape-creators-scrape-creators-tiktok-ad-library-get-v1-tiktok-ad-library-search-example",
  "method": "tools/call",
  "params": {
    "name": "scrape-creators.scrape_creators_tiktok_ad_library_get_v1_tiktok_ad_library_search",
    "arguments": {
      "body": "",
      "likes": "top_1_20",
      "limit": "",
      "query": "",
      "cursor": "",
      "params": "",
      "period": "7",
      "region": "DZ",
      "compact": "",
      "duration": "under_10s"
    }
  }
}

Arguments Schema

{
  "type": "object",
  "properties": {
    "body": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "null"
        }
      ],
      "title": "Body",
      "default": null,
      "description": "JSON request body for provider endpoints that accept one."
    },
    "likes": {
      "enum": [
        "top_1_20",
        "top_21_40",
        "top_41_60",
        "top_61_80",
        "top_81_100"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Likes",
      "default": null,
      "description": "Likes percentile filter."
    },
    "limit": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Limit",
      "default": null,
      "description": "Number of ads to return, max 50. Defaults to 20."
    },
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Query",
      "default": null,
      "description": "Optional keyword to search ad titles/content."
    },
    "cursor": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cursor",
      "default": null,
      "description": "Page number to fetch. Use the cursor returned from the previous response, like 3 for page 3."
    },
    "params": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "title": "Params",
      "default": null,
      "description": "Optional advanced query parameter object. Prefer the documented top-level parameters when available."
    },
    "period": {
      "enum": [
        "7",
        "30",
        "180"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Period",
      "default": null,
      "description": "Time window for Top Ads."
    },
    "region": {
      "enum": [
        "DZ",
        "AR",
        "AU",
        "AT",
        "AZ",
        "BH",
        "BD",
        "BY",
        "BE",
        "BO",
        "BR",
        "BG",
        "KH",
        "CA",
        "CL",
        "CO",
        "CR",
        "HR",
        "CY",
        "CZ",
        "DK",
        "DO",
        "EC",
        "EG",
        "EE",
        "FI",
        "FR",
        "DE",
        "GR",
        "GT",
        "JO",
        "HU",
        "ID",
        "IQ",
        "IE",
        "IL",
        "IT",
        "JP",
        "KZ",
        "KE",
        "KW",
        "LV",
        "LB",
        "MY",
        "MX",
        "MA",
        "NL",
        "NZ",
        "NG",
        "NO",
        "OM",
        "PK",
        "PA",
        "PY",
        "PE",
        "PH",
        "PL",
        "PT",
        "PR",
        "QA",
        "LT",
        "RO",
        "SA",
        "RS",
        "SG",
        "SK",
        "SI",
        "ZA",
        "KR",
        "ES",
        "LK",
        "SE",
        "CH",
        "TW",
        "TH",
        "TR",
        "AE",
        "GB",
        "US",
        "UY",
        "VN"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Region",
      "default": null,
      "description": "Country code. Defaults to US."
    },
    "compact": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Compact",
      "default": null,
      "description": "When true, trims large list payloads before returning them to the agent."
    },
    "duration": {
      "enum": [
        "under_10s",
        "10_20s",
        "20_30s",
        "30_40s",
        "40_50s",
        "over_50s"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Duration",
      "default": null,
      "description": "Video duration filter."
    },
    "industry": {
      "enum": [
        "apparel_accessories",
        "appliances",
        "apps",
        "baby_kids_maternity",
        "beauty_personal_care",
        "business_services",
        "ecommerce_non_app",
        "education",
        "financial_services",
        "food_beverage",
        "games",
        "health",
        "home_improvement",
        "household_products",
        "life_services",
        "news_entertainment",
        "pets",
        "sports_outdoor",
        "tech_electronics",
        "travel",
        "vehicle_transportation"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Industry",
      "default": null,
      "description": "Industry filter."
    },
    "order_by": {
      "enum": [
        "for_you",
        "impression",
        "play_2s_rate",
        "play_6s_rate",
        "cvr",
        "ctr",
        "like"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Order By",
      "default": null,
      "description": "Sort metric. Defaults to for_you."
    },
    "ad_format": {
      "enum": [
        "spark_ads",
        "non_spark_ads"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Ad Format",
      "default": null,
      "description": "Ad format filter."
    },
    "max_items": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Max Items",
      "default": null,
      "description": "Maximum number of list items to return when compacting provider responses."
    },
    "objective": {
      "enum": [
        "app_installs",
        "conversions",
        "lead_generation",
        "product_sales",
        "reach",
        "traffic",
        "video_views"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Objective",
      "default": null,
      "description": "Campaign objective filter."
    },
    "ad_language": {
      "enum": [
        "en",
        "es",
        "ar",
        "vi",
        "th",
        "de",
        "id",
        "pt",
        "fr",
        "ms",
        "nl",
        "ja",
        "it",
        "ro",
        "zh-Hant",
        "ko"
      ],
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Ad Language",
      "default": null,
      "description": "Ad language filter."
    },
    "include_raw": {
      "type": "boolean",
      "title": "Include Raw",
      "default": false,
      "description": "When true, returns both compact normalized data and the raw provider payload; this can be large."
    },
    "path_params": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "title": "Path Params",
      "default": null,
      "description": "Path template values for endpoints that expose path placeholders."
    },
    "search_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Search Query",
      "default": null,
      "description": "Alias for query: Optional keyword to search ad titles/content."
    },
    "cache_ttl_seconds": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cache Ttl Seconds",
      "default": null,
      "description": "Optional cache lifetime for idempotent GET requests."
    },
    "confirm_high_cost": {
      "type": "boolean",
      "title": "Confirm High Cost",
      "default": false,
      "description": "Set true only when intentionally running a high-credit or write-intent request."
    }
  },
  "additionalProperties": false
}

Output Schema

{
  "type": "object",
  "required": [
    "ok",
    "data",
    "error",
    "meta"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Whether the local or provider operation completed successfully."
    },
    "data": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Bounded operation result when ok is true."
    },
    "meta": {
      "type": "object",
      "description": "Safe request, pagination, cache, and timing metadata.",
      "additionalProperties": true
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "description": "Safe structured error when ok is false."
    }
  },
  "description": "Scrape Creators MCP normalized response envelope.",
  "additionalProperties": false
}

Code Examples

cURL

curl -X POST 'https://portal.madpanda3d.com/api/mcp' \
  -H 'Authorization: Bearer mad_live_***' \
  -H 'Content-Type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": "scrape-creators-scrape-creators-tiktok-ad-library-get-v1-tiktok-ad-library-search-example",
  "method": "tools/call",
  "params": {
    "name": "scrape-creators.scrape_creators_tiktok_ad_library_get_v1_tiktok_ad_library_search",
    "arguments": {
      "body": "",
      "likes": "top_1_20",
      "limit": "",
      "query": "",
      "cursor": "",
      "params": "",
      "period": "7",
      "region": "DZ",
      "compact": "",
      "duration": "under_10s"
    }
  }
}'

Node.js

const response = await fetch('https://portal.madpanda3d.com/api/mcp', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mad_live_***',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "jsonrpc": "2.0",
  "id": "scrape-creators-scrape-creators-tiktok-ad-library-get-v1-tiktok-ad-library-search-example",
  "method": "tools/call",
  "params": {
    "name": "scrape-creators.scrape_creators_tiktok_ad_library_get_v1_tiktok_ad_library_search",
    "arguments": {
      "body": "",
      "likes": "top_1_20",
      "limit": "",
      "query": "",
      "cursor": "",
      "params": "",
      "period": "7",
      "region": "DZ",
      "compact": "",
      "duration": "under_10s"
    }
  }
}),
});
const data = await response.json();
console.log(data);

Python

import requests

url = 'https://portal.madpanda3d.com/api/mcp'
headers = {
    'Authorization': 'Bearer mad_live_***',
    'Content-Type': 'application/json',
}
payload = {
  "jsonrpc": "2.0",
  "id": "scrape-creators-scrape-creators-tiktok-ad-library-get-v1-tiktok-ad-library-search-example",
  "method": "tools/call",
  "params": {
    "name": "scrape-creators.scrape_creators_tiktok_ad_library_get_v1_tiktok_ad_library_search",
    "arguments": {
      "body": "",
      "likes": "top_1_20",
      "limit": "",
      "query": "",
      "cursor": "",
      "params": "",
      "period": "7",
      "region": "DZ",
      "compact": "",
      "duration": "under_10s"
    }
  }
}
response = requests.post(url, headers=headers, json=payload, timeout=60)
print(response.json())

Example Responses

200 Success

{
  "ok": true,
  "message": "Tool scrape-creators.scrape_creators_tiktok_ad_library_get_v1_tiktok_ad_library_search executed successfully.",
  "note": "Response shape varies by MCP tool. Inspect live responses for exact fields."
}

502 Upstream Error

{
  "ok": false,
  "classification": "upstream_http_error",
  "message": "Upstream MCP returned a non-success status."
}