@scrapecreators/cli 1.0.27 → 1.0.29

package/api-config/telegram-apis.js

@@ -0,0 +1,132 @@
+const sampleTelegramPost = {
+  id: "543",
+  channel_handle: "durov",
+  url: "https://t.me/durov/543",
+  author_name: "Pavel Durov",
+  author_url: "https://t.me/durov",
+  text: "Telegram has applied for the .gram domain zone. If approved, Telegram users could get their own second-level domains.",
+  published_at: "2026-08-18T17:37:31+00:00",
+  view_count: 1210000,
+  view_count_text: "1.21M",
+  reactions: [
+    {
+      emoji: "⭐",
+      emoji_id: null,
+      count: 16300,
+      count_text: "16.3K",
+    },
+    {
+      emoji: null,
+      emoji_id: "5373223594484587136",
+      count: 44700,
+      count_text: "44.7K",
+    },
+  ],
+  reaction_count: 89300,
+  forwarded_from: null,
+  media: [],
+  link_preview: null,
+};
+
+const sampleTelegramChannel = {
+  handle: "telegram",
+  name: "Telegram News",
+  description: "The official Telegram on Telegram. Much recursion. Very Telegram. Wow.",
+  url: "https://t.me/telegram",
+  avatar_url: "https://cdn1.telesco.pe/file/...",
+  is_verified: true,
+  subscriber_count: 9780000,
+  subscriber_count_text: "9.78M",
+  member_count: null,
+  member_count_text: null,
+  photo_count: 14,
+  video_count: 225,
+  file_count: null,
+  link_count: 372,
+};
+
+export const telegramApis = {
+  id: "telegram",
+  name: "Telegram",
+  description: "Scrape public Telegram channels, groups, and posts",
+  endpoints: [
+    {
+      name: "Channel Details",
+      method: "GET",
+      description: "Get public Telegram channel or group details from its web preview.",
+      fullDescription:
+        "Retrieves public Telegram channel or group metadata including its name, description, avatar, verification status, subscriber or member count, and public media counters. This endpoint uses Telegram's public web preview and does not use a logged-in Telegram account. Private channels, invite-only groups, numeric IDs, and channels with no public web preview are not supported.",
+      path: "/v1/telegram/channel",
+      sampleResponse: sampleTelegramChannel,
+      params: [
+        {
+          name: "handle",
+          type: "string",
+          required: true,
+          placeholder: "telegram",
+          description:
+            "Public Telegram handle, @handle, or t.me channel URL.",
+        },
+      ],
+    },
+    {
+      name: "Channel Posts",
+      method: "GET",
+      description: "Get one page of recent public posts from a Telegram channel or group.",
+      fullDescription:
+        "Retrieves one public web-preview page of Telegram posts with text, publish date, views, reactions when exposed, forwards, media previews, and link previews. Pass the returned cursor to fetch the previous page. Empty and terminal pages are not charged. Telegram does not expose every field on every public post, so reactions and downloadable media URLs can be absent. This endpoint does not support private or invite-only channels and groups.",
+      path: "/v1/telegram/channel/posts",
+      paginationField: "cursor",
+      sampleResponse: {
+        channel: {
+          ...sampleTelegramChannel,
+          handle: "durov",
+          name: "Pavel Durov",
+          description: "Founder of Telegram.",
+          url: "https://t.me/durov",
+          subscriber_count: 11100000,
+          subscriber_count_text: "11.1M",
+        },
+        posts: [sampleTelegramPost],
+        cursor: "523",
+        has_more: true,
+      },
+      params: [
+        {
+          name: "handle",
+          type: "string",
+          required: true,
+          placeholder: "durov",
+          description:
+            "Public Telegram handle, @handle, or t.me channel URL.",
+        },
+        {
+          name: "cursor",
+          type: "string",
+          required: false,
+          placeholder: "523",
+          description:
+            "Numeric cursor returned by the previous page. Omit it for the latest posts.",
+        },
+      ],
+    },
+    {
+      name: "Post Details",
+      method: "GET",
+      description: "Get one public Telegram post by URL.",
+      fullDescription:
+        "Retrieves one public Telegram post with its text, publish date, views, reactions when exposed, forward source, media previews, and link preview. This endpoint uses Telegram's public post widget without a logged-in account. Private and invite-only posts are not supported.",
+      path: "/v1/telegram/post",
+      sampleResponse: sampleTelegramPost,
+      params: [
+        {
+          name: "url",
+          type: "string",
+          required: true,
+          placeholder: "https://t.me/durov/543",
+          description: "Public Telegram post URL.",
+        },
+      ],
+    },
+  ],
+};

package/api-config/tiktok-apis.js

@@ -180,12 +180,85 @@ export const tiktokBaseApis = {
         ],
       },
     },
+    {
+      name: "Collection Videos",
+      method: "GET",
+      description:
+        "Scrapes the videos in a public TikTok collection. Pass cursor to get more videos.",
+      fullDescription:
+        "Fetches the videos saved in a public TikTok collection, which TikTok also calls a playlist. Pass the collection URL. Returns `videos` using TikTok's native web video object format, including `id`, `desc`, `author`, `stats`, and `video`. To fetch the next page, pass the previous response's `max_cursor` as `cursor` when `has_more` is true.",
+      path: "/v1/tiktok/collection/videos",
+      paginationField: "max_cursor",
+      params: [
+        {
+          name: "url",
+          type: "string",
+          required: true,
+          description: "Public TikTok collection URL",
+          placeholder:
+            "https://www.tiktok.com/@kibblemaster808/collection/Want-to-go-7665668414573546258",
+        },
+        {
+          name: "cursor",
+          type: "string",
+          required: false,
+          description:
+            "Cursor to get more videos. Use max_cursor from the previous response.",
+          placeholder: "4",
+        },
+      ],
+      sampleResponse: {
+        success: true,
+        credits_remaining: 100,
+        collection_id: "7665668414573546258",
+        has_more: false,
+        max_cursor: "5",
+        status_code: 0,
+        status_msg: "",
+        videos: [
+          {
+            AIGCDescription: "",
+            CategoryType: 116,
+            IsHDBitrate: false,
+            ShowAIGC: true,
+            anchors: [
+              {
+                description: "CapCut · Video Editor",
+                type: 54,
+              },
+            ],
+            author: {
+              id: "7506421330087576593",
+              uniqueId: "miotravelapp",
+              nickname: "miotravelapp",
+            },
+            createTime: 1784185607,
+            desc: "How often do you reckon they think about the Roman Empire? 🐈‍⬛",
+            id: "7663018809392909588",
+            stats: {
+              collectCount: 18900,
+              commentCount: 359,
+              diggCount: 113000,
+              playCount: 865200,
+              shareCount: 15700,
+            },
+            video: {
+              duration: 68,
+              height: 1024,
+              width: 576,
+              cover:
+                "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/oUYM7iBIKB1BL5CGgwAtAiwJEfLCFXAiX9IAEA~tplv-tiktokx-origin.image",
+            },
+          },
+        ],
+      },
+    },
     {
       name: "Profile Videos",
       method: "GET",
       description:
-        "Scrapes videos from a TikTok profile. Pass cursor to get more videos.",
-      fullDescription: "Fetches videos posted by a TikTok user, sortable by latest or most popular — use this to get a creator's video feed or TikToks. Returns `aweme_list`, an array of video objects each containing `aweme_id`, `desc` (caption), `statistics` (play_count, digg_count/likes, comment_count, share_count, collect_count/saves), and `video` (download URLs, duration, cover image). Paginate with `max_cursor` from the previous response.",
+        "Scrapes videos from a TikTok profile. Pass cursor to get more videos. If a profile should have videos but returns none, try `region=US` or another relevant region.",
+      fullDescription: "Fetches videos posted by a TikTok user, sortable by latest or most popular — use this to get a creator's video feed or TikToks. Returns `aweme_list`, an array of video objects each containing `aweme_id`, `desc` (caption), `statistics` (play_count, digg_count/likes, comment_count, share_count, collect_count/saves), and `video` (download URLs, duration, cover image). Paginate with `max_cursor` from the previous response. If a profile should have videos but returns none, try `region=US` or another relevant two-letter country code.",
       path: "/v3/tiktok/profile/videos",
       paginationField: "max_cursor",
       params: [
@@ -223,8 +296,9 @@ export const tiktokBaseApis = {
           name: "region",
           type: "string",
           required: false,
-          placeholder: "US",
-          description: "Region (Country) you want the proxy in. Defaults to US.",
+          placeholder: "GB",
+          description:
+            "Region (country) for the proxy. Defaults to GB. If a profile should have videos but returns none, try US or another relevant two-letter country code.",
         },
         {
           name: "trim",
@@ -5543,10 +5617,10 @@ export const tiktokBaseApis = {
       },
     },
     {
-      name: "TikTok Live",
+      name: "Live",
       method: "GET",
       description: "Scrapes a TikTok user's live stream",
-      fullDescription: "Checks if a TikTok user is currently live streaming and retrieves their live room details. Returns `liveRoomUserInfo` (nickname, avatar, followerCount, roomId) and `liveRoom` (title, startTime, status, `liveRoomStats` with enterCount and userCount, plus `streamData` with playback URLs in multiple qualities).",
+      fullDescription: "Checks if a TikTok user is currently live streaming and retrieves their live room details. Use the top-level `is_live` boolean instead of checking TikTok's numeric status values yourself. Also returns `liveRoomUserInfo` (nickname, avatar, followerCount, roomId) and `liveRoom` (title, startTime, status, `liveRoomStats` with enterCount and userCount, plus `streamData` with playback URLs in multiple qualities).",
       path: "/v1/tiktok/user/live",
       params: [
         {
@@ -5559,6 +5633,7 @@ export const tiktokBaseApis = {
       ],
       sampleResponse: {
         success: true,
+        is_live: true,
         liveRoomUserInfo: {
           avatarLarger:
             "https://p19-pu-sign-useast8.tiktokcdn-us.com/tos-useast5-avt-0068-tx/b169e9223700dc8d20d327510eb47f94~tplv-tiktokx-cropcenter:1080:1080.webp?dr=9640&refresh_token=c39a7259&x-expires=1751918400&x-signature=2Q%2F13wVO%2F%2F5OFBDinwMuULyBINc%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=useast5",
@@ -5661,6 +5736,45 @@ export const tiktokBaseApis = {
         },
       },
     },
+    {
+      name: "Live Info",
+      method: "GET",
+      description: "Gets info for a TikTok live room, including like count.",
+      fullDescription:
+        "Gets curated room-level info for a TikTok live using TokAPI's live info endpoint. Use `/v1/tiktok/user/live` first to find the `room_id`. If you only have a TikTok handle and need the user's numeric id, use `/v1/tiktok/profile` first to get `user.id`. This endpoint is separate from `/v1/tiktok/user/live` because it uses a different upstream call and returns a smaller response with the most relevant fields: `room_id`, `like_count`, `viewer_count`, `status`, `title`, `cover_url`, and `owner`.",
+      path: "/v1/tiktok/live",
+      params: [
+        {
+          name: "room_id",
+          type: "string",
+          required: true,
+          description:
+            "TikTok live room id. Get this from `/v1/tiktok/user/live` in `liveRoomUserInfo.roomId` or `liveRoom.id` when the user is live.",
+          placeholder: "7523685855395842871",
+        },
+        {
+          name: "user_id",
+          type: "string",
+          required: true,
+          description:
+            "TikTok numeric user id for the live owner. Get this from `/v1/tiktok/profile` in `user.id`.",
+          placeholder: "6742945285876515845",
+        },
+      ],
+      sampleResponse: {
+        room_id: "7523685855395842871",
+        like_count: 4317,
+        viewer_count: 268,
+        status: "live",
+        title: "6'13 Grateful Streamer",
+        cover_url: "https://p16-webcast.tiktokcdn-us.com/webcast/cover.jpeg",
+        owner: {
+          id: "6742945285876515845",
+          username: "thejustalex",
+          display_name: "JustAlex",
+        },
+      },
+    },
     {
       name: "Comments",
       method: "GET",
@@ -10721,6 +10835,96 @@ export const tiktokBaseApis = {
         },
       ],
     },
+    {
+      name: "Search Suggestions",
+      method: "GET",
+      description: "Gets TikTok autocomplete search suggestions for a query.",
+      fullDescription:
+        "Gets the autocomplete suggestions TikTok shows while someone is typing in search. Returns `suggestions`, a clean array of suggested search terms and the most useful metadata for each suggestion.",
+      path: "/v1/tiktok/search/suggestions",
+      sampleResponse: {
+        success: true,
+        credits_remaining: 49995926120,
+        suggestions: [
+          {
+            text: "dogs cute",
+            position: 0,
+            language: "en",
+            score: 0.011535803,
+          },
+          {
+            text: "Dogs In Snow",
+            position: 1,
+            language: "en",
+            score: 0.0013200018,
+          },
+          {
+            text: "dogs season",
+            position: 2,
+            language: "en",
+            score: 0.0013042383,
+          },
+          {
+            text: "dogs with kids",
+            position: 3,
+            language: "en",
+            score: 0.0012028236,
+          },
+          {
+            text: "dogs protecting owners",
+            position: 4,
+            language: "en",
+            score: 0.0008062465,
+          },
+          {
+            text: "dogseven",
+            position: 5,
+            language: "en",
+            score: 0.0011085697,
+          },
+          {
+            text: "Dogs Video",
+            position: 6,
+            language: "en",
+            score: 0.003553978,
+          },
+          {
+            text: "dogs edit",
+            position: 7,
+            language: "en",
+            score: 0.0014429367,
+          },
+          {
+            text: "dogs funny videos",
+            position: 8,
+            language: "en",
+            score: 0.0039043615,
+          },
+          {
+            text: "dogs eating foods",
+            position: 9,
+            language: "en",
+            score: 0.001083838,
+          },
+        ],
+      },
+      params: [
+        {
+          name: "query",
+          type: "string",
+          required: true,
+          description: "Search query to get suggestions for",
+          placeholder: "dogs",
+        },
+        {
+          name: "region",
+          type: "string",
+          required: false,
+          description: "Region code for suggestions",
+          placeholder: "US",
+        },
+      ],
+    },
     {
       name: "Search by Hashtag",
       method: "GET",
@@ -15876,6 +16080,7 @@ export const tiktokBaseApis = {
     //     ],
     //   },
     // },
+    /* Retired July 16, 2026: TikTok no longer makes this data available.
     {
       name: "Get popular hashtags",
       method: "GET",
@@ -16047,6 +16252,7 @@ export const tiktokBaseApis = {
         },
       },
     },
+    */
     {
       name: "Get Song Details",
       method: "GET",

package/api-config/tiktok-shop-apis.js

@@ -47,7 +47,7 @@ export const tiktokShopApis = {
           ],
           placeholder: "US",
           description:
-            "Region to search shop products in.",
+            "Region to search shop products in. Non-US TikTok Shop regions are not reliable right now and may return limited or inconsistent results. Sorry for the inconvenience.",
         },
       ],
       sampleResponse: {
@@ -185,8 +185,8 @@ export const tiktokShopApis = {
       name: "Shop Products",
       method: "GET",
       description:
-        "Get the products from a TikTok Shop. This endpoint costs 1 credit per request. Use the cursor from the response to paginate through results.",
-      fullDescription: "Lists all products from a specific TikTok Shop store by its URL. Returns an array of product objects each with `title`, `cover` images, `url`, `price` info, `sold_count`, `review_count`, and `rating`. Paginate with `cursor` from the previous response; filter by region; use `sort_by=top` for best-selling products or `sort_by=new_releases` for newest products.",
+        "Get the products from a TikTok Shop. This endpoint costs 1 credit per request. Use the cursor from the response to paginate through results. Non-US shop catalog coverage depends on TikTok exposing that shop in the selected region.",
+      fullDescription: "Lists all products from a specific TikTok Shop store by its URL. Returns an array of product objects each with `title`, `cover` images, `url`, `price` info, `sold_count`, `review_count`, and `rating`. Paginate with `cursor` from the previous response; filter by region; use `sort_by=top` for best-selling products or `sort_by=new_releases` for newest products. Non-US shop catalog coverage depends on TikTok exposing that shop in the selected region, so some shops can return `not_found` outside the US even when they appear in shop search.",
       path: "/v1/tiktok/shop/products",
       params: [
         {
@@ -237,7 +237,7 @@ export const tiktokShopApis = {
           ],
           placeholder: "US",
           description:
-            "Region to get shop products from. Defaults to US if not provided.",
+            "Region to get shop products from. Defaults to US if not provided. Non-US regions are not reliable right now and may return `not_found` or limited catalog data even when the shop appears in search. Sorry for the inconvenience.",
         },
       ],
       sampleResponse: {
@@ -375,8 +375,8 @@ export const tiktokShopApis = {
       name: "Product Details",
       method: "GET",
       description:
-        "Get the details of a TikTok Shop Product! Get the exact amount of stock the product has, related tiktok videos promoting the product, and more!",
-      fullDescription: "Fetches full details for a specific TikTok Shop product by its URL, including stock levels and affiliate videos. Returns `product_info` with `product_base` (title, images, sold_count, price), `skus` (variants with exact `stock` counts), and `product_detail_review` (product_rating, review_count, sample reviews); also returns `shop_info` (shop_name, shop_rating, followers_count) and `related_videos` (affiliate TikToks promoting the product). Related videos are only available in the US region.",
+        "Get the details of a TikTok Shop Product. This endpoint currently supports US TikTok Shop products only.",
+      fullDescription: "Fetches full details for a specific US TikTok Shop product by its URL, including stock levels and affiliate videos. Returns `product_info` with `product_base` (title, images, sold_count, price), `skus` (variants with exact `stock` counts), and `product_detail_review` (product_rating, review_count, sample reviews); also returns `shop_info` (shop_name, shop_rating, followers_count) and `related_videos` (affiliate TikToks promoting the product). This endpoint currently supports the US region only.",
       path: "/v1/tiktok/product",
       params: [
         {
@@ -392,7 +392,7 @@ export const tiktokShopApis = {
           required: false,
           type: "string",
           description:
-            "Region the proxy will be set to so you can access products from that country. Use 2 letter country codes like US, GB, FR, etc. For England, don't use UK, use GB.",
+            "Region for the product details request. US is the reliable region right now; non-US regions should not be considered reliable and may return `bad_request` or missing product data. Sorry for the inconvenience.",
           placeholder: "US",
         },
       ],
@@ -770,7 +770,8 @@ export const tiktokShopApis = {
         },
         {
           name: "region",
-          description: "The region of the product. This is *very* important.",
+          description:
+            "The region of the product. US is the reliable region right now; non-US regions should not be considered reliable and may return limited or inconsistent review data. Sorry for the inconvenience.",
           type: "string",
           required: false,
           placeholder: "US",
@@ -931,7 +932,8 @@ export const tiktokShopApis = {
         {
           name: "region",
           type: "string",
-          description: "Region to put the proxy in",
+          description:
+            "Region to put the proxy in. Non-US TikTok Shop regions are not reliable right now and may return limited or inconsistent showcase data. Sorry for the inconvenience.",
           required: false,
           placeholder: "US",
         },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@scrapecreators/cli",
-  "version": "1.0.27",
-  "description": "CLI for the ScrapeCreators API — scrape 27+ social media platforms from the terminal",
+  "version": "1.0.29",
+  "description": "CLI for the ScrapeCreators API — use 180+ endpoints across 30+ platforms from the terminal",
   "type": "module",
   "bin": {
     "scrapecreators": "bin/scrapecreators.js"

package/src/cli.js

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { readFileSync } from "node:fs";
 import { registerApiCommands } from "./command-registry.js";
 import { authLogin, authStatus, authLogout } from "./commands/auth.js";
 import { configSet, configGet, configList } from "./commands/config.js";
@@ -7,13 +8,17 @@ import { listCommand } from "./commands/list.js";
 import { agentAddCommand } from "./commands/agent.js";
 import { runInteractive } from "./interactive.js";
 
+const { version } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
 export function run(argv) {
   const program = new Command();
 
   program
     .name("scrapecreators")
-    .description("CLI for the ScrapeCreators API — scrape 27+ social media platforms")
-    .version("1.0.0")
+    .description("CLI for the ScrapeCreators API — use 180+ endpoints across 30+ platforms")
+    .version(version)
     .option("--api-key <key>", "API key (overrides env and config)")
     .option("--format <format>", "output format: json, table, csv, markdown", "auto")
     .option("--json", "shorthand for compact JSON (default)")