@scrapecreators/cli 1.0.27 → 1.0.28

package/api-config/apis.js

@@ -3,11 +3,23 @@ import { tiktokShopApis } from "./tiktok-shop-apis.js";
 import { instagramBaseApis } from "./instagram-apis.js";
 import { githubApis } from "./github-apis.js";
 import { kwaiApis } from "./kwai-apis.js";
+import { telegramApis } from "./telegram-apis.js";
+
+const withPostVariant = (endpoint) => [
+  endpoint,
+  {
+    ...endpoint,
+    method: "POST",
+    docsPath: `${endpoint.path}/post`,
+    postParamsInBody: true,
+  },
+];
 
 export const apis = [
   tiktokBaseApis,
   tiktokShopApis,
   instagramBaseApis,
+  telegramApis,
   {
     id: "youtube",
     name: "YouTube",
@@ -19,7 +31,7 @@ export const apis = [
         description:
           "Get comprehensive channel information including stats and metadata. Can pass channelId, handle, or url.",
         fullDescription:
-          "Retrieves comprehensive YouTube channel profile data including name, avatar images, subscriber count (subscribers), total video and view counts, join date, tags, and linked social accounts like Twitter and Instagram. Accepts a channelId, handle, or full channel URL as input. Returns channel metadata such as country, email, and external store links when available.",
+          "Retrieves comprehensive YouTube channel profile data including name, avatar images, subscriber count (subscribers), total video and view counts, join date, tags, and linked social accounts like Twitter and Instagram. Accepts a channelId, handle, or full channel URL as input. Returns channel metadata such as country, email, and external store links when available. Contact fields come from the submitted public profile. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL.",
         path: "/v1/youtube/channel",
         sampleResponse: {
           channelId: "UCxcTeAKWJca6XyJ37_ZoKIQ",
@@ -576,10 +588,41 @@ export const apis = [
         name: "Video/Short Details",
         method: "GET",
         description:
-          "Get complete information about a video or short.",
+          "Get complete information about a video or short. isPaidPromotion tells you whether YouTube marks the video as including paid promotion. Also includes YouTube's most-replayed heatmap when YouTube exposes it. most_replayed is null when the graph is not available. Age-restricted videos return 403 because we only use the public logged-out YouTube source.",
         fullDescription:
-          "Fetches full details for a YouTube video or short, including title, description, thumbnail, view count (views), like count (likes), comment count, publish date, duration, genre, keywords, chapters, collaborators, and available caption tracks (subtitles/captions). Also returns related recommended videos in watchNextVideos and channel info for the uploader.",
+          "Fetches full details for a YouTube video or short, including title, description, thumbnail, view count (views), like count (likes), comment count, publish date, duration, genre, keywords, chapters, collaborators, and available caption tracks (subtitles/captions). isPaidPromotion is true when YouTube marks the video as including paid promotion and false when it does not. Also returns related recommended videos in watchNextVideos and channel info for the uploader. When YouTube exposes its public Most replayed graph, most_replayed contains normalized graph buckets in markers and YouTube's highlighted ranges in ranges. The field is null when the graph is not available. YouTube says the graph may be unavailable when the channel has active strikes, the content is potentially inappropriate, the video is too new or has too few views, or its systems deem the video ineligible for another reason. YouTube does not publish fixed age or view-count thresholds. Age-restricted videos return 403 with message: \"This video is age restricted\" because Scrape Creators only uses the public logged-out YouTube source.",
         path: "/v1/youtube/video",
+        errorResponseExamples: {
+          403: {
+            success: false,
+            credits_remaining: 100,
+            error: "forbidden",
+            errorStatus: 403,
+            message: "This video is age restricted",
+          },
+        },
+        responseFields: [
+          {
+            path: "isPaidPromotion",
+            description:
+              "Boolean. True when YouTube marks the video as including paid promotion; otherwise false.",
+          },
+          {
+            path: "most_replayed",
+            description:
+              "YouTube's public Most replayed heatmap, or null when YouTube does not show the graph for this video.",
+          },
+          {
+            path: "most_replayed.markers",
+            description:
+              "Graph buckets with startMillis, durationMillis, and intensityScoreNormalized.",
+          },
+          {
+            path: "most_replayed.ranges",
+            description:
+              "YouTube-highlighted replay ranges with visibleTimeRangeStartMillis, visibleTimeRangeEndMillis, decorationTimeMillis, and the localized label.",
+          },
+        ],
         sampleResponse: {
           success: true,
           credits_remaining: 33851527,
@@ -655,6 +698,8 @@ export const apis = [
           genre: "People & Blogs",
           durationMs: 348000,
           durationFormatted: "00:05:48",
+          isPaidPromotion: false,
+          most_replayed: null,
           captionTracks: [
             {
               baseUrl:
@@ -679,7 +724,7 @@ export const apis = [
             type: "string",
             required: true,
             description: "YouTube video or short URL",
-            placeholder: "https://www.youtube.com/watch?v=Y2Ah_DFr8cw",
+            placeholder: "https://youtu.be/gTCi7PaOPLY",
           },
           {
             name: "language",
@@ -693,9 +738,9 @@ export const apis = [
       {
         name: "Transcript",
         method: "GET",
-        description: "Get transcript of a video or short",
+        description: "Get publicly available captions or a transcript from a YouTube video or Short",
         fullDescription:
-          "Retrieves the captions, subtitles, or transcript of a YouTube video or short. Returns both a timestamped transcript array with start/end times and a plain-text version in transcript_only_text. Supports specifying a language code. Note: the video must be under 2 minutes for transcript extraction to work.",
+          "Retrieves the captions, subtitles, or transcript of a YouTube video or Short. Returns both a timestamped transcript array with start/end times and a plain-text version in transcript_only_text. Supports specifying a language code. There is no two-minute limit for YouTube. Long videos, including podcasts, work when YouTube exposes public captions. If no matching caption track is available, the transcript fields return null.",
         path: "/v1/youtube/video/transcript",
         params: [
           {
@@ -1103,7 +1148,8 @@ export const apis = [
             name: "query",
             type: "string",
             required: true,
-            description: "Search query",
+            description:
+              'Search query. For stricter title matching, use YouTube\'s intitle: operator, for example intitle:"Foursquare Swarm". Quoted queries by themselves may still be broadened by YouTube when no fresh exact matches are available.',
           },
           {
             name: "uploadDate",
@@ -1166,6 +1212,52 @@ export const apis = [
           },
         ],
       },
+      {
+        name: "Search Typeahead",
+        method: "GET",
+        description:
+          "Get the live autocomplete suggestions shown in YouTube's search dropdown.",
+        fullDescription:
+          "Returns the live search suggestions YouTube displays while a user types. Each result includes the suggested text and whether it is a normal query or a channel. When YouTube returns a channel suggestion, the response also includes its public channel ID, handle, name, and thumbnail.",
+        path: "/v1/youtube/search/typeahead",
+        sampleResponse: {
+          success: true,
+          credits_remaining: 100,
+          data: {
+            query: "mr beast",
+            suggestions: [
+              {
+                text: "mrbeast",
+                type: "channel",
+                channel: {
+                  id: "UCX6OQ3DkcsbYNE6H8uQQuVA",
+                  handle: "@MrBeast",
+                  name: "MrBeast",
+                  thumbnailUrl:
+                    "https://yt3.googleusercontent.com/example=s88-c-k-c0x00ffffff-no-rj",
+                },
+              },
+              {
+                text: "mr beast give me some money",
+                type: "query",
+              },
+              {
+                text: "mrbeast gaming",
+                type: "query",
+              },
+            ],
+          },
+        },
+        params: [
+          {
+            name: "query",
+            type: "string",
+            required: true,
+            description: "Partial or complete YouTube search query",
+            placeholder: "mr beast",
+          },
+        ],
+      },
       {
         name: "Search by Hashtag",
         method: "GET",
@@ -2643,7 +2735,7 @@ export const apis = [
         description:
           "Search for public LinkedIn posts by keyword. Uses Google Search to find indexed posts, then scrapes the public LinkedIn pages.",
         fullDescription:
-          "Finds public LinkedIn posts, feed updates, and Pulse articles by keyword using Google Search, then returns post details such as description, author, media, images, like count, comment count, and published date when LinkedIn exposes them publicly. Results depend on what Google has indexed, so this is best-effort and not a complete LinkedIn-native search. Use date_posted for recent posts and pass the returned cursor to fetch the next page.",
+          "Finds public LinkedIn posts, feed updates, and Pulse articles by keyword using Google Search, then returns post details such as description, author, media, images, like count, comment count, and published date when LinkedIn exposes them publicly. Results depend on what Google has indexed, so this is best-effort and not a complete LinkedIn-native search. Use date_posted for recent posts and pass the returned cursor to fetch the next page. Cursors are limited to pages 1 through 11; cursor 12 or greater returns a 400 response.",
         path: "/v1/linkedin/search/posts",
         paginationField: "cursor",
         params: [
@@ -2666,7 +2758,7 @@ export const apis = [
             name: "cursor",
             type: "string",
             required: false,
-            description: "The cursor returned from the previous response",
+            description: "The cursor returned from the previous response. The maximum cursor is 11; cursor 12 or greater returns a 400 response.",
             placeholder: "2",
           },
         ],
@@ -2949,7 +3041,7 @@ export const apis = [
         method: "GET",
         description: "Get public Facebook profile information",
         fullDescription:
-          "Retrieves public Facebook page details including category, address, email, phone, website, services, priceRange, rating, likeCount, and followerCount. Also returns adLibrary status with the page's ad activity and pageId. Optionally includes businessHours when get_business_hours is set to true.",
+          "Retrieves public Facebook page details including category, address, email, phone, website, services, priceRange, rating, likeCount, talkingAboutCount, and followerCount. talkingAboutCount is nullable and only returned when Facebook exposes it publicly. Also returns adLibrary status with the page's ad activity and pageId. Optionally includes businessHours when get_business_hours is set to true. Contact fields come from the submitted public profile. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL. If Facebook shows an 18+ content gate, the response is still 200 with account_status: \"age-restricted\" and isPrivate: true. If Facebook shows a private content gate, the response is still 200 with account_status: \"private\" and isPrivate: true. If the page is not found, the response is 404 with accountDoesNotExist: true and isPrivate: false. Set include_gated_profile=true to also return limited public fields (such as id, name, category, likeCount, profilePicSmall, and links) when a profile is gated or age-restricted. This option only affects gated/age-restricted profiles — public profiles still return the normal full response.",
         path: "/v1/facebook/profile",
         sampleResponse: {
           success: true,
@@ -3072,6 +3164,7 @@ export const apis = [
             },
           ],
           id: "100088017857524",
+          isPrivate: false,
           name: "Mantraindian",
           url: "https://www.facebook.com/mantraindianfolsom",
           gender: "UNKNOWN",
@@ -3127,8 +3220,56 @@ export const apis = [
           rating: "Not yet rated (1 review)",
           ratingCount: null,
           likeCount: 3224,
+          talkingAboutCount: 418,
           followerCount: 3200,
         },
+        privateResponse: {
+          success: true,
+          credits_remaining: 100,
+          url: "https://www.facebook.com/VinnysDriveBar/",
+          account_status: "private",
+          isPrivate: true,
+          message: "Profile is private",
+        },
+        ageRestrictedResponse: {
+          success: true,
+          credits_remaining: 100,
+          url: "https://www.facebook.com/profile.php?id=999244349946937",
+          account_status: "age-restricted",
+          isPrivate: true,
+          message: "Profile is age restricted",
+        },
+        gatedProfileResponse: {
+          success: true,
+          credits_remaining: 298984,
+          id: "1581499185460975",
+          name: "Galopim Livros",
+          url: "https://www.facebook.com/livrosgalopim/",
+          profilePicSmall:
+            "https://scontent-phl2-1.xx.fbcdn.net/v/t39.30808-1/459791315_1253431156111407_5370275117423562096_n.jpg?stp=dst-jpg_p200x200_tt6&_nc_cat=110&ccb=1-7&_nc_sid=418b77&_nc_ohc=Pi3YpShkQiYQ7kNvwEYPNxb&_nc_oc=AdrjmBEW-EsVxhFGkvcfpAoKyqM65UHc9gnY6PsWlNZdu2_nIx1mc6tK9SAVVvNgUYg&_nc_zt=24&_nc_ht=scontent-phl2-1.xx&_nc_gid=aEVhmS9KLeHxBKf28_0baA&_nc_ss=7f289&oh=00_AQBmzIQzEFDGjobJ0GwIzhko6nFrshbjeDFEUKLwK_bQIg&oe=6A652D51",
+          category: "Bookstore",
+          links: ["https://www.instagram.com/livros_galopim/"],
+          likeCount: 16576,
+          pageAlias: "livrosgalopim",
+          verification: "NOT_VERIFIED",
+          entityType: "PERSON_PROFILE",
+          igUsername: "livros_galopim",
+          igFollowerCount: 657,
+          igVerification: false,
+          pageIsDeleted: false,
+        },
+        errorResponseExamples: {
+          404: {
+            success: true,
+            credits_remaining: 100,
+            data: {
+              url: "https://www.facebook.com/TatnuckDrivingRangeandIceCream/",
+              accountDoesNotExist: true,
+              isPrivate: false,
+              message: "Account doesn't exist",
+            },
+          },
+        },
         params: [
           {
             name: "url",
@@ -3144,6 +3285,14 @@ export const apis = [
             description: "Get the business's hours",
             placeholder: "true",
           },
+          {
+            name: "include_gated_profile",
+            type: "string",
+            required: false,
+            description:
+              "When true, returns limited public fields for gated or age-restricted profiles. Ignored for normal public profiles — those still return the full response.",
+            placeholder: "true",
+          },
         ],
       },
       {
@@ -4578,13 +4727,92 @@ export const apis = [
           "has_next_page": true
         },
       },
+      {
+        name: "Facebook Group Info",
+        method: "GET",
+        description: "Get the public About-page information for a Facebook group.",
+        fullDescription:
+          "Fetches the public information shown on a Facebook group's About page, including its description, privacy and visibility, member and activity counts, categories, administrators and moderators when Facebook exposes them, group history, and rules. Provide either url or group_id.",
+        path: "/v1/facebook/group",
+        params: [
+          {
+            name: "url",
+            type: "string",
+            description: "The Facebook group URL. Group sub-page URLs such as /about work too.",
+            required: false,
+            placeholder: "https://www.facebook.com/groups/366190054572553/about",
+          },
+          {
+            name: "group_id",
+            type: "string",
+            description: "The numeric Facebook group ID. Provide this instead of url if you already have it.",
+            required: false,
+            placeholder: "366190054572553",
+          },
+        ],
+        sampleResponse: {
+          success: true,
+          credits_remaining: 49999999999,
+          credits_charged: 1,
+            id: "366190054572553",
+            url: "https://www.facebook.com/groups/366190054572553",
+            name: "Python Programming",
+            description: "Let's share our knowledge on Python Programming",
+            privacy: {
+              label: "Public",
+              description: "Anyone can see who's in the group and what they post.",
+            },
+            visibility: {
+              label: "Visible",
+              description: "Anyone can find this group.",
+            },
+            categories: [
+              { id: "242504017103922", name: "Software & tech" },
+              { id: "202183377053878", name: "Engineering" },
+            ],
+            created_at: "2020-10-14T15:45:03.000Z",
+            history_summary: "Group created on October 14, 2020. Name last changed on October 16, 2020.",
+            member_count: 710386,
+            member_count_text: "710,386 total members",
+            administrator_count: 3,
+            moderator_count: 0,
+            administrators: [
+              {
+                id: "pfbid029b9bjf9rZfL4v9EHdxt1uxng857G4UqwpZjbCHySg88UYWu2XL5ivSixWhXBnZMnl",
+                name: "Nusrat Jahan",
+                url: "https://www.facebook.com/people/Nusrat-Jahan/pfbid029b9bjf9rZfL4v9EHdxt1uxng857G4UqwpZjbCHySg88UYWu2XL5ivSixWhXBnZMnl/",
+                profile_picture_url: "https://scontent.xx.fbcdn.net/example.jpg",
+              },
+            ],
+            moderators: [],
+            activity: {
+              posts_last_day: 16,
+              posts_last_month: 512,
+              new_members_text: "No new members in the last week",
+            },
+            rules: [
+              {
+                id: "366191957905696",
+                title: "Be Kind and Courteous",
+                description: "We're all in this together to create a welcoming environment. Let's treat everyone with respect.",
+              },
+            ],
+            about_info: [
+              {
+                type: "XFBPrivacyGroupsAboutInfoItem",
+                label: "Public",
+                description: "Anyone can see who's in the group and what they post.",
+              },
+            ],
+        },
+      },
       {
         name: "Facebook Group Posts",
         method: "GET",
         description:
           "Get a public Facebook groups posts. Only can get 3 posts at a time :( (Facebook API limit)",
         fullDescription:
-          "Fetches posts from a public Facebook group, limited to 3 posts per page due to API limitations. Each post includes id, text, url, reactionCount, commentCount, publishTime, videoDetails, and topComments. Supports sorting by TOP_POSTS, RECENT_ACTIVITY, CHRONOLOGICAL, or CHRONOLOGICAL_LISTINGS, with cursor-based pagination.",
+          "Fetches posts from a public Facebook group, limited to 3 posts per page due to API limitations. Each post includes id, text, url, reactionCount, commentCount, publishTime, videoDetails, and topComments. Results are chronological by default. Supports TOP_POSTS, RECENT_ACTIVITY, CHRONOLOGICAL, and CHRONOLOGICAL_LISTINGS with cursor-based pagination.",
         path: "/v1/facebook/group/posts",
         params: [
           {
@@ -4604,9 +4832,9 @@ export const apis = [
           {
             name: "sort_by",
             type: "select",
-            description: "How to sort the posts",
+            description: "How to sort the posts. Defaults to CHRONOLOGICAL.",
             required: false,
-            placeholder: "TOP_POSTS",
+            placeholder: "CHRONOLOGICAL",
             options: [
               "TOP_POSTS",
               "RECENT_ACTIVITY",
@@ -4842,7 +5070,7 @@ export const apis = [
         method: "GET",
         description: "Search Facebook Marketplace listings",
         fullDescription:
-          "Searches Facebook Marketplace listings by keyword and lat/lng. Supports pagination with the returned cursor. Pass the cursor value back as-is. When sort_by is creation_time_descend, Facebook can still return slightly different ordering between identical requests. For alerting/new-item workflows, scrape multiple pages and dedupe by listing id instead of relying on page 1 item order being identical every run.",
+          "Searches Facebook Marketplace listings by keyword and lat/lng. Pass category_id to restrict results to the numeric Facebook Marketplace category ID returned on listing results. Supports pagination with the returned cursor. Pass the cursor value back as-is. When sort_by is creation_time_descend, Facebook can still return slightly different ordering between identical requests. For alerting/new-item workflows, scrape multiple pages and dedupe by listing id instead of relying on page 1 item order being identical every run.",
         path: "/v1/facebook/marketplace/search",
         params: [
           {
@@ -4852,6 +5080,13 @@ export const apis = [
             required: true,
             placeholder: "bike",
           },
+          {
+            name: "category_id",
+            type: "string",
+            description: "Numeric Facebook Marketplace category ID. Listing results include this value as category_id.",
+            required: false,
+            placeholder: "1658310421102081",
+          },
           {
             name: "lat",
             type: "number",
@@ -5081,9 +5316,9 @@ export const apis = [
       {
         name: "Marketplace Item",
         method: "GET",
-        description: "Get a Facebook Marketplace item",
+        description: "Get a Facebook Marketplace item, including rental listing_date_text and availability_text when Facebook exposes them.",
         fullDescription:
-          "Fetches details for a Facebook Marketplace item by item id or Marketplace item URL, including title, description, price, location, condition, photos, seller, and availability flags.",
+          "Fetches details for a Facebook Marketplace item by item id or Marketplace item URL, including title, description, price, location, condition, photos, seller, and availability flags. Rental listings can include listing_date_text and availability_text from Facebook's Marketplace GraphQL response, for example 'Listed over a week ago' and 'Available now'. creation_time can still be null when Facebook does not expose an exact timestamp.",
         path: "/v1/facebook/marketplace/item",
         params: [
           {
@@ -5109,6 +5344,8 @@ export const apis = [
           "title": "Specialized Hardrock GSX - Super Clean Vintage Restomod - INCLUDES FREE TUNE UP",
           "description": "Was going to hang on to this one bc I absolutely love how it looks, but the 20” frame is just bit too large for me. Riders over 6’ would be comfy on this one. Currently in a 3x7 set up with an XT derailleur at the rear. Looks great in person. Come ride it!  These never last long. \n\nCASH ONLY, PLEASE. NEAR 183/BRAKER.  \n\n$380 OBO. \n\nKey points:\n\n- Maxxis DTH tires (26”)\n- Shimano Deore XT rear derailleur \n- Shimano front derailleur\n- vintage Specialized steel frame (20”)\n- vintage Sakae triple crankset (170mm)\n- vintage Sakae SR Custom handlebar\n- vintage Suntour stem shifter\n- vintage Shimano brakes\n- Specialized Avatar 143 saddle\n- new chain\n- fresh cables\n- fresh housing\n- fresh grease and lube\n- fresh lube in cable housings\n- fresh handlebar tape\n- drive train cleaned and lubed\n- derailluers adjusted and fine tuned\n- brakes adjusted and fine tuned\n- deep cleaning/detail\n- frame polished\n- frame waxed\n- INCLUDES ONE FREE TUNE UP\n",
           "creation_time": "2026-05-15T16:57:39.000Z",
+          "listing_date_text": null,
+          "availability_text": null,
           "location_text": "Austin, TX",
           "location": {
             "latitude": 30.401916503906,
@@ -5719,7 +5956,7 @@ export const apis = [
         description:
           "Pass the Ad ID and get back details about the ad. Be careful that if an ad has multiple versions, you're actually going to want to get the title from the 'cards' object.",
         fullDescription:
-          "Retrieves detailed information about a specific Facebook ad by its ID or URL. Returns adArchiveID, pageName, isActive, startDate, endDate, and a snapshot containing body, images, videos, display_format, link_url, and cta_text. For ads with multiple versions, the ad creative is found in the snapshot.cards array rather than snapshot.body.",
+          "Retrieves detailed information about a specific Facebook ad by its ID or URL. Returns adArchiveID, pageName, isActive, startDate, endDate, and a snapshot containing body, images, videos, display_format, link_url, and cta_text. Regulated ads may also include source-dependent aaa_info using the structure shown below. Political and social issue delivery data is normalized to location_audience and age_country_gender_reach_breakdown. Political location_audience rows include reach, and political delivery values are fractional shares, so 0.08 means 8%. Regional transparency data may use absolute reach counts. For ads with multiple versions, the ad creative is found in the snapshot.cards array rather than snapshot.body.",
         path: "/v1/facebook/adLibrary/ad",
         sampleResponse: {
           adid: 0,
@@ -6104,13 +6341,13 @@ export const apis = [
           },
         ],
       },
-      {
+      ...withPostVariant({
         name: "Search",
         method: "GET",
         description:
-          "Search the Facebook (Meta) Ad Library By Keyword. This endpoint will tap out around 1,500 results, beacuse the cursor becomes too big for a GET request. If you need more results, call this endpoint as a POST, and pass the query params in the body.",
+          "Search the Facebook (Meta) Ad Library by keyword. Use GET for normal requests. If the cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body.",
         fullDescription:
-          "Searches the Meta Ad Library by keyword and returns matching ads. Each result includes ad_archive_id, page_name, is_active, publisher_platform, and a snapshot with body text, images, videos, and cta_text. Results cap around 1,500 via GET due to cursor size limits; switch to POST method with body params for larger result sets.",
+          "Searches the Meta Ad Library by keyword and returns matching ads. Supports filtering by language with a 2-letter code such as EN or ES. Each result includes ad_archive_id, page_name, is_active, publisher_platform, and a snapshot with body text, images, videos, and cta_text. Both GET and POST are supported. Use GET for normal requests. If the cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body.",
         path: "/v1/facebook/adLibrary/search/ads",
         sampleResponse: {
           searchResults: [
@@ -6366,6 +6603,14 @@ export const apis = [
               "This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.",
             placeholder: "ALL",
           },
+          {
+            name: "language",
+            type: "string",
+            required: false,
+            description:
+              "Language to filter ads on. Needs to be a 2 letter language code, such as EN, ES, or FR.",
+            placeholder: "EN",
+          },
           {
             name: "status",
             type: "select",
@@ -6423,15 +6668,15 @@ export const apis = [
             placeholder: "false",
           },
         ],
-      },
-      {
+      }),
+      ...withPostVariant({
         name: "Company Ads",
         method: "GET",
         paginationField: "cursor",
         description:
-          "Get all the ads a company has running. If params become too large, make this a POST request and pass the params in the body.",
+          "Get all the ads a company has running. Use GET for normal requests. If the cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body.",
         fullDescription:
-          "Fetches all ads currently running for a specific company from the Meta Ad Library. Each ad includes ad_archive_id, page_name, is_active, publisher_platform, and a snapshot with body, images, videos, and display_format. Supports filtering by country, media_type, date range, and language with cursor-based pagination.",
+          "Fetches all ads currently running for a specific company from the Meta Ad Library. Each ad includes ad_archive_id, page_name, is_active, publisher_platform, and a snapshot with body, images, videos, and display_format. Supports filtering by country, media_type, date range, and language with cursor-based pagination. Both GET and POST are supported. If the cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body.",
         path: "/v1/facebook/adLibrary/company/ads",
         youtubeId: "M_wgqCtznjM",
         codeExample:
@@ -6757,7 +7002,7 @@ export const apis = [
             placeholder: "false",
           },
         ],
-      },
+      }),
       {
         name: "Search for Companies",
         method: "GET",
@@ -6825,187 +7070,95 @@ export const apis = [
       {
         name: "Ad Library Search",
         method: "GET",
-        description: "Search TikTok Creative Center Top Ads by region, period, and keyword.",
+        description: "Search TikTok's public Ads Library by general query or advertiser name.",
         fullDescription:
-          "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.",
+          "Searches TikTok's public Ads Library using either query for a general search or advertiser_name for advertiser-specific results. Advertiser-name searches resolve the name through TikTok's advertiser typeahead first, then search the selected advertiser entity. If TikTok has no matching entity, the API falls back to TikTok's name search so inputs such as The Creator Loop still return matching ads. Provide exactly one of query or advertiser_name. Results are global, sorted by the latest shown date, support cursor pagination, and include a public TikTok Ads Library URL for each ad.",
         path: "/v1/tiktok/ad-library/search",
         params: [
-          {
-            name: "region",
-            type: "select",
-            required: false,
-            description: "Country code. Defaults to US.",
-            options: ["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"],
-            placeholder: "US",
-          },
-          {
-            name: "period",
-            type: "select",
-            required: false,
-            description: "Time window for Top Ads.",
-            options: ["7", "30", "180"],
-            placeholder: "30",
-          },
           {
             name: "query",
             type: "string",
             required: false,
-            description: "Optional keyword to search ad titles/content.",
-            placeholder: "spotify",
-          },
-          {
-            name: "order_by",
-            type: "select",
-            required: false,
-            description: "Sort metric. Defaults to for_you.",
-            options: ["for_you", "impression", "play_2s_rate", "play_6s_rate", "cvr", "ctr", "like"],
-            placeholder: "for_you",
-          },
-          {
-            name: "industry",
-            type: "select",
-            required: false,
-            description: "Industry filter.",
-            options: ["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"],
-            placeholder: "beauty_personal_care",
-          },
-          {
-            name: "objective",
-            type: "select",
-            required: false,
-            description: "Campaign objective filter.",
-            options: ["app_installs", "conversions", "lead_generation", "product_sales", "reach", "traffic", "video_views"],
-            placeholder: "traffic",
-          },
-          {
-            name: "duration",
-            type: "select",
-            required: false,
-            description: "Video duration filter.",
-            options: ["under_10s", "10_20s", "20_30s", "30_40s", "40_50s", "over_50s"],
-            placeholder: "under_10s",
-          },
-          {
-            name: "likes",
-            type: "select",
-            required: false,
-            description: "Likes percentile filter.",
-            options: ["top_1_20", "top_21_40", "top_41_60", "top_61_80", "top_81_100"],
-            placeholder: "top_1_20",
-          },
-          {
-            name: "ad_format",
-            type: "select",
-            required: false,
-            description: "Ad format filter.",
-            options: ["spark_ads", "non_spark_ads"],
-            placeholder: "spark_ads",
+            description: "General ad search. Provide either query or advertiser_name, not both.",
+            placeholder: "The Creator Loop",
           },
           {
-            name: "ad_language",
-            type: "select",
+            name: "advertiser_name",
+            type: "string",
             required: false,
-            description: "Ad language filter.",
-            options: ["en", "es", "ar", "vi", "th", "de", "id", "pt", "fr", "ms", "nl", "ja", "it", "ro", "zh-Hant", "ko"],
-            placeholder: "en",
+            description: "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.",
+            placeholder: "Gymshark",
           },
           {
             name: "cursor",
-            type: "number",
-            required: false,
-            description: "Page number to fetch. Use the cursor returned from the previous response, like 3 for page 3.",
-            placeholder: "3",
-          },
-          {
-            name: "limit",
-            type: "number",
+            type: "string",
             required: false,
-            description: "Number of ads to return, max 50. Defaults to 20.",
-            placeholder: "20",
+            description: "Opaque cursor returned from the previous response.",
+            placeholder: "cursor from previous response",
           },
         ],
         sampleResponse: {
-          "success": true,
-          "credits_remaining": 49996315011,
-          "query": "",
-          "region": "US",
-          "period": 30,
-          "ads": [
+          success: true,
+          credits_remaining: 100,
+          credits_charged: 1,
+          source: "tiktok_public_ads_library",
+          advertiser_name: "Gymshark",
+          resolved_advertiser_name: "GYMSHARK LTD",
+          advertiser_matches: [
             {
-              "ad_title": "I thought this was a gimmick until I tried it! A wrinkled shirt, one button, and a few minutes later... ready to wear. Tap the link in bio and see why everyone’s talking about Bellairon before it sells out. @Bellairon LLC ",
-              "brand_name": "",
-              "cost": 1,
-              "ctr": 0.5,
-              "favorite": false,
-              "id": "7646829987799334920",
-              "industry_key": "label_22108000000",
-              "is_search": true,
-              "like": 92,
-              "objective_key": "campaign_objective_reach",
-              "video_info": {
-                "vid": "v12044gd0000d8erq07og65h1cq991gg",
-                "duration": 89.767,
-                "cover": "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068c799-us/oIbqBdvfEAiFpgvAOgrQHCF5R0mkDDLiEfvQDS~tplv-noop.image?dr=18692&refresh_token=2ac068a9&x-expires=1781231816&x-signature=hLbBkguntM4oX9tgdnKMMDYixAA%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my2&VideoID=v12044gd0000d8erq07og65h1cq991gg",
-                "video_url": {
-                  "540p": "https://v16m-default.tiktokcdn.com/64e64ad32f68588eee511da0114f0f2e/6a2b70c8/video/tos/maliva/tos-maliva-ve-0068c799-us/oIN2GPIRgHAUBHOeNfLk2HBSERoJeIALGC3jAE/?a=0&bti=NTU4QDM1NGA%3D&&bt=315&ft=cApXJCz7ThWHK-z9LGZmo0P&mime_type=video_mp4&rc=Omk6ZWQ7Nzc7OGY8PGVnOkBpajQ8Zms5cjN1OzMzZzczNEBgNDAzXl9hXjMxLzEvXjFiYSNkNm4uMmQ0bmJhLS1kMS9zcw%3D%3D&vvpl=1&l=20260612043527C18C959B9A8CF584D398&btag=e00090000",
-                  "720p": "https://v16m-default.tiktokcdn.com/4ee4e5763b088d7d77e4a9f4fce502b6/6a2b70c8/video/tos/maliva/tos-maliva-ve-0068c799-us/ooEipQa9HbhJ4ChzASIngUPhBAdXiABIvxU2E/?a=0&bti=NTU4QDM1NGA%3D&&bt=877&ft=cApXJCz7ThWHK-z9LGZmo0P&mime_type=video_mp4&rc=ZTg3OTQ0NTQzZGVpNWg6NkBpajQ8Zms5cjN1OzMzZzczNEBhNC0yMDViNi8xLV9hX2AuYSNkNm4uMmQ0bmJhLS1kMS9zcw%3D%3D&vvpl=1&l=20260612043527C18C959B9A8CF584D398&btag=e00090000"
-                },
-                "width": 720,
-                "height": 1280
-              }
+              name: "GYMSHARK LTD",
+              ids: "7078923208527618049",
             },
+          ],
+          ads: [
             {
-              "ad_title": "True Heroes go ALL IN or nothing. See yourself at the top!",
-              "brand_name": "",
-              "cost": 0,
-              "ctr": 0.29,
-              "favorite": false,
-              "id": "7640089122220736530",
-              "industry_key": "label_25100000000",
-              "is_search": true,
-              "like": 1115,
-              "objective_key": "campaign_objective_conversion",
-              "video_info": {
-                "vid": "v10033g50000d8jbia7og65q0198frmg",
-                "duration": 105.003,
-                "cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o8jPFEKAAIYhaBUQ6CM5tAZiBiKaaAuSi7Hzm~tplv-noop.image?dr=18692&refresh_token=3750a204&x-expires=1781231832&x-signature=RfXRGuG8N6d69HxYz2Z9XUKgdWU%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my2&VideoID=v10033g50000d8jbia7og65q0198frmg",
-                "video_url": {
-                  "1080p": "https://v16m-default.tiktokcdn.com/3dad0efc22921436631456d0eb262abc/6a2b70d8/video/tos/alisg/tos-alisg-ve-0051c001-sg/oEPIgOBQUJpQBtqKOFyFDfEMODsYfUAzNhBAIQ/?a=0&bti=NTU4QDM1NGA%3D&&bt=2989&ft=cApXJCz7ThWHK-z9LGZmo0P&mime_type=video_mp4&rc=OzU3NTU5ZTxlaDs0NmRoaEBpanU7NHQ5cmRlOzMzODYzNEBjMjBhYl5eXy0xMjY0L2MtYSNqYzYtMmQ0ZmdhLS1kMC1zcw%3D%3D&vvpl=1&l=20260612043527C18C959B9A8CF584D398&btag=e00088000",
-                  "360p": "https://v16m-default.tiktokcdn.com/6c204fed990c1083f8bbd68b500b660e/6a2b70d8/video/tos/alisg/tos-alisg-ve-0051c001-sg/oUYBAIDIFOzFBQOkIN1KABPDUsJQIQgfgqyOeE/?a=0&bti=NTU4QDM1NGA%3D&&bt=551&ft=cApXJCz7ThWHK-z9LGZmo0P&mime_type=video_mp4&rc=aDs3ZDRmNzM5OGg3NWZmOEBpanU7NHQ5cmRlOzMzODYzNEBgMS80NTAuXjQxXmBeYmNhYSNqYzYtMmQ0ZmdhLS1kMC1zcw%3D%3D&vvpl=1&l=20260612043527C18C959B9A8CF584D398&btag=e00088000",
-                  "480p": "https://v16m-default.tiktokcdn.com/c4a6191ed579f76eaf7b6a6611966b3b/6a2b70d8/video/tos/alisg/tos-alisg-ve-0051c001-sg/okAEI5qKBEgFlH2AAniQo8mC5AfH1KAIiAwHBA/?a=0&bti=NTU4QDM1NGA%3D&&bt=780&ft=cApXJCz7ThWHK-z9LGZmo0P&mime_type=video_mp4&rc=ODRmZWk6NzU1NDU4OWQ3NUBpanU7NHQ5cmRlOzMzODYzNEAwNDAwNS4xXl8xMDZiYTMyYSNqYzYtMmQ0ZmdhLS1kMC1zcw%3D%3D&vvpl=1&l=20260612043527C18C959B9A8CF584D398&btag=e00088000",
-                  "540p": "https://v16m-default.tiktokcdn.com/07591ee6ce0fc4ca315a41f1d87ee420/6a2b70d8/video/tos/alisg/tos-alisg-ve-0051c001-sg/oI2EoHAi5CI5ANF1AKQEmIHiqfs8qZBoABlAwn/?a=0&bti=NTU4QDM1NGA%3D&&bt=1063&ft=cApXJCz7ThWHK-z9LGZmo0P&mime_type=video_mp4&rc=ODZmPDQ5ZjY2NTw7NzQzOkBpanU7NHQ5cmRlOzMzODYzNEAuXmFjX2NhNjAxM140MzRiYSNqYzYtMmQ0ZmdhLS1kMC1zcw%3D%3D&vvpl=1&l=20260612043527C18C959B9A8CF584D398&btag=e00088000",
-                  "720p": "https://v16m-default.tiktokcdn.com/1404645b61626339c2e1d4c6df4ebb12/6a2b70d8/video/tos/alisg/tos-alisg-ve-0051c001-sg/okYmBiwEIK1QnHBHEAHu5oiSHAlWIAf52RAxAC/?a=0&bti=NTU4QDM1NGA%3D&&bt=1460&ft=cApXJCz7ThWHK-z9LGZmo0P&mime_type=video_mp4&rc=aDs5O2lpNTg0Mzc2NGc8N0BpanU7NHQ5cmRlOzMzODYzNEA2YGNhYmMuXjIxLWBfMV9eYSNqYzYtMmQ0ZmdhLS1kMC1zcw%3D%3D&vvpl=1&l=20260612043527C18C959B9A8CF584D398&btag=e00088000"
+              id: "1871655924410641",
+              url: "https://library.tiktok.com/ads/detail/?ad_id=1871655924410641",
+              name: "GYMSHARK LTD",
+              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/...",
                 },
-                "width": 720,
-                "height": 1280
-              }
+              ],
+              estimated_audience: "1K-10K",
+              spent: "",
+              impression: 0,
+              show_mode: 1,
+              image_urls: [],
+              rejection_info: null,
+              sor_audit_status: "1",
             },
           ],
-          "pagination": {
-            "has_more": true,
-            "page": 1,
-            "size": 20,
-            "total_count": 326
-          },
-          "total": 326,
-          "has_more": true,
-          "cursor": 2
+          total: 62344,
+          has_more: true,
+          cursor: "opaque cursor for the next page",
         },
+        responseFields: [
+          {
+            path: "ads[].url",
+            description: "Public TikTok Ads Library detail page for the ad.",
+          },
+        ],
       },
       {
         name: "Ad Library Ad",
         method: "GET",
-        description: "Gets details for a TikTok Creative Center Top Ad.",
+        description: "Gets details for a TikTok ad from either Creative Center Top Ads or TikTok's public Ads Library.",
         fullDescription:
-          "Fetches one TikTok Creative Center Top Ad by material/ad ID or URL. Uses the same Creative Center data behind pages like ads.tiktok.com/business/creativecenter/topads/{id}/pc/en, including title, metrics, video info, landing page, country codes, objective, industry, source, the Creative Center URL, summary/analysis, interactive time analysis graph data, and recommended-for-you ads when TikTok provides them.",
+          "Fetches one TikTok ad by ID or URL. It first checks Creative Center Top Ads (ads.tiktok.com), then TikTok's public transparency Ads Library (library.tiktok.com) when the ID is not a Top Ads material. Both sources return the same response shape. Fields TikTok does not expose for a public Ads Library ad are null, empty, or false as appropriate.",
         path: "/v1/tiktok/ad-library/ad",
         params: [
           {
             name: "ad_id",
             type: "string",
             required: true,
-            description: "TikTok Top Ads material/ad ID, or a Top Ads detail URL.",
-            placeholder: "7642386438915309575",
+            description: "Creative Center Top Ads material ID or URL, or a public Ads Library ad ID or library.tiktok.com detail URL.",
+            placeholder: "1869335220395266",
           },
         ],
         sampleResponse: {
@@ -9130,119 +9283,43 @@ export const apis = [
         description:
           "Get recent posts from a subreddit with engagement metrics",
         fullDescription:
-          "Fetches posts from a subreddit with sorting and filtering options. Each post includes title, author, selftext, score, ups, upvote_ratio, num_comments, created_utc, url, permalink, subreddit_subscribers, and is_video. Supports sort (best, hot, new, top, rising), timeframe filtering, pagination via the after token, and a trim parameter for lighter responses.",
+          "Fetches posts from a subreddit with sorting and filtering options. Each post includes title, author, link_flair_text when Reddit exposes it, selftext, score, ups, upvote_ratio, num_comments, created_utc, url, permalink, subreddit_subscribers, and is_video. Supports sort (best, hot, new, top, rising), timeframe filtering, pagination via the after token, and a trim parameter for lighter responses.",
         path: "/v1/reddit/subreddit",
         paginationField: "after",
         sampleResponse: {
           posts: [
             {
-              approved_at_utc: null,
+              id: "1lfbo7u",
+              author: "Vetro_Nodulare2",
+              author_fullname: "t2_16syu27ar1",
               subreddit: "AskReddit",
+              title: "What is a thing you love that lots of people hate?",
+              link_flair_text: null,
               selftext: "",
-              author_fullname: "t2_aelahp9al",
-              saved: false,
-              mod_reason_title: null,
-              gilded: 0,
-              clicked: false,
-              title:
-                "What are your thoughts on California’s bill that would ban most law enforcement officers from wearing face masks while on duty?",
-              link_flair_richtext: [],
-              subreddit_name_prefixed: "r/AskReddit",
-              hidden: false,
-              pwls: 6,
-              link_flair_css_class: null,
+              selftext_html: "",
               downs: 0,
-              top_awarded_type: null,
-              hide_score: false,
-              name: "t3_1ldr6b9",
-              quarantine: false,
-              link_flair_text_color: "dark",
-              upvote_ratio: 0.93,
-              author_flair_background_color: null,
-              subreddit_type: "public",
-              ups: 12606,
+              name: "t3_1lfbo7u",
+              upvote_ratio: 0.9,
+              ups: 45,
               total_awards_received: 0,
-              media_embed: {},
-              author_flair_template_id: null,
-              is_original_content: false,
-              user_reports: [],
-              secure_media: null,
-              is_reddit_media_domain: false,
-              is_meta: false,
-              category: null,
-              secure_media_embed: {},
-              link_flair_text: null,
-              can_mod_post: false,
-              score: 12606,
-              approved_by: null,
-              is_created_from_ads_ui: false,
-              author_premium: false,
-              thumbnail: "",
-              edited: false,
-              author_flair_css_class: null,
-              author_flair_richtext: [],
-              gildings: {},
-              content_categories: null,
-              is_self: true,
-              mod_note: null,
-              created: 1750176516,
-              link_flair_type: "text",
-              wls: 6,
-              removed_by_category: null,
-              banned_by: null,
-              author_flair_type: "text",
-              domain: "self.AskReddit",
-              allow_live_comments: false,
-              selftext_html: null,
-              likes: null,
-              suggested_sort: null,
-              banned_at_utc: null,
-              view_count: null,
-              archived: false,
-              no_follow: false,
-              is_crosspostable: false,
-              pinned: false,
+              score: 45,
+              created: 1750341959,
+              created_utc: 1750341959,
+              created_at_iso: "2025-06-19T16:45:59.000Z",
+              num_comments: 349,
+              url: "https://www.reddit.com/r/AskReddit/comments/1lfbo7u/what_is_a_thing_you_love_that_lots_of_people_hate/",
+              permalink:
+                "/r/AskReddit/comments/1lfbo7u/what_is_a_thing_you_love_that_lots_of_people_hate/",
+              subreddit_subscribers: null,
+              is_video: false,
               over_18: false,
-              all_awardings: [],
-              awarders: [],
-              media_only: false,
-              can_gild: false,
               spoiler: false,
-              locked: false,
-              author_flair_text: null,
-              treatment_tags: [],
-              visited: false,
-              removed_by: null,
-              num_reports: null,
-              distinguished: null,
+              domain: "self.AskReddit",
               subreddit_id: "t5_2qh1i",
-              author_is_blocked: false,
-              mod_reason_by: null,
-              removal_reason: null,
-              link_flair_background_color: "",
-              id: "1ldr6b9",
-              is_robot_indexable: true,
-              report_reasons: null,
-              author: "Ecstatic-Medium-6320",
-              discussion_type: null,
-              num_comments: 1921,
-              send_replies: false,
-              contest_mode: false,
-              mod_reports: [],
-              author_patreon_flair: false,
-              author_flair_text_color: null,
-              permalink:
-                "/r/AskReddit/comments/1ldr6b9/what_are_your_thoughts_on_californias_bill_that/",
-              stickied: false,
-              url: "https://www.reddit.com/r/AskReddit/comments/1ldr6b9/what_are_your_thoughts_on_californias_bill_that/",
-              subreddit_subscribers: 56098571,
-              created_utc: 1750176516,
-              num_crossposts: 1,
-              media: null,
-              is_video: false,
+              post_hint: "text",
             },
           ],
-          after: "t3_1ld8q7h",
+          after: "t3_1lfogps",
         },
         trimmedResponse: {
           posts: [
@@ -9252,6 +9329,9 @@ export const apis = [
               author_fullname: "t2_16syu27ar1",
               subreddit: "AskReddit",
               title: "What is a thing you love that lots of people hate?",
+              link_flair_text: null,
+              selftext: "",
+              selftext_html: "",
               downs: 0,
               name: "t3_1lfbo7u",
               upvote_ratio: 0.9,
@@ -9272,6 +9352,9 @@ export const apis = [
               subreddit: "AskReddit",
               title:
                 "What's the best physical pleasure you have ever experienced?",
+              link_flair_text: null,
+              selftext: "",
+              selftext_html: "",
               downs: 0,
               name: "t3_1leoazg",
               upvote_ratio: 0.91,
@@ -9493,11 +9576,58 @@ export const apis = [
         },
       },
       {
+        name: "Post",
+        method: "GET",
+        description: "Get information from a Reddit post without comments",
+        fullDescription:
+          "Retrieves public Reddit post details by URL without fetching or returning comments. Returns the text post body in selftext when present, plus the title, author, subreddit, score, upvote ratio, comment count, timestamps, permalink, and post flags. Accepts canonical Reddit post URLs and Reddit mobile share URLs.",
+        path: "/v1/reddit/post",
+        params: [
+          {
+            name: "url",
+            type: "string",
+            required: true,
+            description: "Reddit post URL",
+            placeholder:
+              "https://www.reddit.com/r/webscraping/comments/1q6pxwn/just_started_web_scraping_is_this_a_good_start/",
+          },
+        ],
+        sampleResponse: {
+          id: "1q6pxwn",
+          author: "franik33",
+          author_fullname: "t2_16xbknfp71",
+          subreddit: "webscraping",
+          title: "Just Started Web Scraping — Is This a Good Start?",
+          selftext:
+            "Hi everyone, I started getting into web scraping about 3–4 days ago. I already have some solid experience with Python, and my first scraping project was a public website. I managed to collect around 7,000 records and everything worked as expected. I’m curious whether this is considered a decent start for someone new to scraping, or if it’s fairly basic stuff.Also, I’d like to hear honest opinions: is web scraping still worth investing time in today (for projects, automation, or monetization), or is it becoming a waste of time due to market saturation and restrictions? Any real-world experiences or insights would be appreciated. Thanks in advance.",
+          downs: 0,
+          name: "t3_1q6pxwn",
+          upvote_ratio: 0.9230769230769231,
+          ups: 33,
+          total_awards_received: 0,
+          score: 33,
+          created: 1767816090,
+          created_utc: 1767816090,
+          created_at_iso: "2026-01-07T20:01:30.000Z",
+          num_comments: 53,
+          url: "https://www.reddit.com/r/webscraping/comments/1q6pxwn/just_started_web_scraping_is_this_a_good_start/",
+          permalink:
+            "/r/webscraping/comments/1q6pxwn/just_started_web_scraping_is_this_a_good_start/",
+          subreddit_subscribers: null,
+          is_video: false,
+          archived: true,
+          locked: false,
+          over_18: false,
+          spoiler: false,
+        },
+      },
+      ...withPostVariant({
         name: "Post Comments",
         method: "GET",
-        description: "Get comments + post information from a Reddit post",
+        description:
+          "Get comments and post information from a Reddit post. Pass one opaque cursor returned by the previous response to get the next page. Cursor batching is not supported. Use POST with the same JSON-body parameters if a cursor becomes too large for a GET URL.",
         fullDescription:
-          "Retrieves comments and post details from a Reddit post by URL. Returns the post with title, author, score, ups, upvote_ratio, num_comments, and created_utc, plus a comments array where each comment includes author, body, body_html, score, created_utc, parent_id, permalink, and nested replies. Supports cursor-based pagination for loading more comments and a trim parameter for lighter responses.",
+          "Retrieves comments and post details from a Reddit post by URL. Returns the post with title, author, score, ups, upvote_ratio, num_comments, and created_utc, plus a comments array where each comment includes author, body, body_html, score, created_utc, parent_id, permalink, and nested replies. Both GET and POST are supported. Use GET for normal requests. Pass one opaque cursor exactly as returned by more.cursor or replies.more.cursor to load the next page. Cursor batching and comma-separated cursor values are not supported. If an opaque cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body. Supports cursor-based pagination for loading more comments and a trim parameter for lighter responses.",
         path: "/v1/reddit/post/comments",
         params: [
           {
@@ -9512,8 +9642,8 @@ export const apis = [
             name: "cursor",
             type: "string",
             required: false,
-            description: "Cursor to get more comments, or replies.",
-            placeholder: "ed1lvsa,ed3fnpq,ed25l2w",
+            description: "One opaque cursor returned by the previous response to get more comments or replies. Do not combine multiple cursors.",
+            placeholder: "opaque_cursor_returned_by_previous_response",
           },
           {
             name: "trim",
@@ -10671,10 +10801,10 @@ export const apis = [
           ],
           more: {
             has_more: true,
-            cursor: "ed1jhoi,ed1f3kw,ed1qgjh,ed1e4vd,ed1benx",
+            cursor: "opaque_cursor_returned_by_previous_response",
           },
         },
-      },
+      }),
       // {
       //   name: "Simple Comments",
       //   method: "GET",
@@ -10857,9 +10987,9 @@ export const apis = [
       {
         name: "Search",
         method: "GET",
-        description: "Search Reddit for posts",
+        description: "Search Reddit for posts or comments",
         fullDescription:
-          "Searches across all of Reddit for posts matching a query. Each post includes title, author, selftext, subreddit, score, ups, upvote_ratio, num_comments, created_utc, url, permalink, and is_video. Supports sort (relevance, new, top, comment_count), timeframe filtering, pagination via the after token, and a trim parameter for lighter responses.",
+          "Searches across all of Reddit for posts or comments matching a query. Set filter to posts (the default) or comments. Post results include title, author, selftext, subreddit, score, ups, upvote_ratio, num_comments, created_utc, url, permalink, and is_video. Comment results include the matching body, author, votes, timestamps, comment URL, parent relationship, and post/subreddit context. Comment searches support relevance, new, and top sorting. Timeframe filtering applies to post searches. Pagination uses the after token, and trim returns a lighter response.",
         path: "/v1/reddit/search",
         paginationField: "after",
         params: [
@@ -10869,11 +10999,20 @@ export const apis = [
             required: true,
             description: "Search query",
           },
+          {
+            name: "filter",
+            type: "select",
+            required: false,
+            description: "Search posts or comments",
+            placeholder: "posts",
+            options: ["posts", "comments"],
+          },
           {
             name: "sort",
             type: "select",
             required: false,
-            description: "Sort by",
+            description:
+              "Sort by. Comment search supports relevance, new, and top; comment_count is for post search only.",
             placeholder: "relevance",
             options: ["relevance", "new", "top", "comment_count"],
           },
@@ -10881,7 +11020,7 @@ export const apis = [
             name: "timeframe",
             type: "select",
             required: false,
-            description: "Timeframe",
+            description: "Post search timeframe",
             placeholder: "all",
             options: ["all", "day", "week", "month", "year"],
           },
@@ -11829,7 +11968,7 @@ export const apis = [
         method: "GET",
         description: "Get Truth Social post",
         fullDescription:
-          "Fetches a single Truth Social post by URL, returning text, id, created_at, url, content, account details, media_attachments, card link previews, replies_count, reblogs_count, and favourites_count. Only posts from prominent public figures (e.g., Trump, Vance) are accessible without authentication.",
+          "Fetches a single Truth Social post by URL, returning text, id, created_at, url, content, account details, media_attachments, card link previews, replies_count, reblogs_count, and favourites_count. Set download_media=true to download attached images or video and return permanent Supabase URLs. Only posts from prominent public figures (e.g., Trump, Vance) are accessible without authentication.",
         path: "/v1/truthsocial/post",
         params: [
           {
@@ -11840,6 +11979,15 @@ export const apis = [
             placeholder:
               "https://truthsocial.com/@realDonaldTrump/posts/114315219437063160",
           },
+          {
+            name: "download_media",
+            type: "boolean",
+            required: false,
+            description:
+              "Set to true to download the attached video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.",
+            placeholder: false,
+            credits: 10,
+          },
         ],
         sampleResponse: {
           success: true,
@@ -14645,7 +14793,7 @@ export const apis = [
         method: "GET",
         description: "Search Google",
         fullDescription:
-          "Performs a Google search and returns organic results with url, title, and description for each result. Supports an optional region parameter (2-letter country code) to get localized results from a specific country.",
+          "Performs a Google search and returns organic results with url, title, and description for each result. Supports an optional region parameter (2-letter country code) to get localized results from a specific country. Pages 1 through 11 are supported; requests for page 12 or greater return a 400 response.",
         path: "/v1/google/search",
         params: [
           {
@@ -14675,7 +14823,7 @@ export const apis = [
             name: "page",
             type: "number",
             required: false,
-            description: "Page number to retrieve",
+            description: "Page number to retrieve. Must be between 1 and 11; page 12 or greater returns a 400 response.",
             placeholder: "1",
           }
         ],
@@ -17662,10 +17810,206 @@ export const apis = [
       },
     ],
   },
+  {
+    id: "apple-music",
+    name: "Apple Music",
+    description: "Scrape Apple Music artists, songs, albums, and search results",
+    endpoints: [
+      {
+        name: "Artist",
+        method: "GET",
+        description: "Get Apple Music artist",
+        fullDescription:
+          "Retrieves public Apple Music artist details, including artwork, editorial notes, top songs, albums, music videos, playlists, and related sections.",
+        path: "/v1/apple-music/artist",
+        params: [
+          {
+            name: "id",
+            type: "string",
+            required: false,
+            description: "Apple Music artist id. If you'd prefer to use the URL instead, you can use the url parameter instead.",
+            placeholder: "159260351",
+          },
+          {
+            name: "url",
+            type: "string",
+            required: false,
+            description: "Apple Music artist URL. If you'd prefer to use the id instead, you can use the id parameter instead.",
+            placeholder: "https://music.apple.com/us/artist/taylor-swift/159260351",
+          },
+        ],
+        sampleResponse: {
+          success: true,
+          credits_remaining: 49996588524,
+          data: {
+            id: "159260351",
+            kind: "artist",
+            name: "Taylor Swift",
+            url: "https://music.apple.com/us/artist/taylor-swift/159260351",
+            artwork: {
+              url: "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/70/30/3b/example/1200x1200bb.jpg",
+              width: 5998,
+              height: 5998,
+            },
+            editorial_notes: "The country world feigned surprise when Taylor Swift formally embraced pop...",
+            top_songs: [
+              {
+                id: "1833328840",
+                kind: "song",
+                title: "The Fate of Ophelia",
+                artist_name: "Taylor Swift",
+                url: "https://music.apple.com/us/album/the-fate-of-ophelia/1833328839?i=1833328840",
+                duration_ms: 226000,
+              },
+            ],
+            albums: [
+              {
+                id: "1468058165",
+                kind: "album",
+                title: "Lover",
+                subtitle: "Taylor Swift",
+                track_count: 18,
+                url: "https://music.apple.com/us/album/lover/1468058165",
+              },
+            ],
+          },
+        },
+      },
+      {
+        name: "Album",
+        method: "GET",
+        description: "Get Apple Music album",
+        fullDescription:
+          "Retrieves public Apple Music album details, including title, artist, artwork, release info, tracks, and more by the artist.",
+        path: "/v1/apple-music/album",
+        params: [
+          {
+            name: "id",
+            type: "string",
+            required: false,
+            description: "Apple Music album id. If you'd prefer to use the URL instead, you can use the url parameter instead.",
+            placeholder: "1468058165",
+          },
+          {
+            name: "url",
+            type: "string",
+            required: false,
+            description: "Apple Music album URL. If you'd prefer to use the id instead, you can use the id parameter instead.",
+            placeholder: "https://music.apple.com/us/album/lover/1468058165",
+          },
+        ],
+        sampleResponse: {
+          success: true,
+          credits_remaining: 49996588523,
+          data: {
+            id: "1468058165",
+            kind: "album",
+            title: "Lover",
+            artist_name: "Taylor Swift",
+            artist_url: "https://music.apple.com/us/artist/taylor-swift/159260351",
+            url: "https://music.apple.com/us/album/lover/1468058165",
+            track_count: 18,
+            release_info: "August 23, 2019\n18 songs, 1 hour 1 minute\n℗ 2019 Taylor Swift",
+            tracks: [
+              {
+                id: "1468058169",
+                kind: "song",
+                title: "I Forgot That You Existed",
+                duration_ms: 170651,
+                track_number: 1,
+                album_id: "1468058165",
+              },
+            ],
+          },
+        },
+      },
+      {
+        name: "Track",
+        method: "GET",
+        description: "Get Apple Music track",
+        fullDescription:
+          "Retrieves public Apple Music song details by id or URL. Album track URLs with an i= song id are supported.",
+        path: "/v1/apple-music/track",
+        params: [
+          {
+            name: "id",
+            type: "string",
+            required: false,
+            description: "Apple Music song id. Some songs have standalone song URLs; for album tracks, use the url parameter.",
+            placeholder: "1833328840",
+          },
+          {
+            name: "url",
+            type: "string",
+            required: false,
+            description: "Apple Music song URL or album track URL.",
+            placeholder: "https://music.apple.com/us/album/lover/1468058165?i=1468058169",
+          },
+        ],
+        sampleResponse: {
+          success: true,
+          credits_remaining: 49996588522,
+          data: {
+            id: "1468058169",
+            kind: "song",
+            title: "I Forgot That You Existed",
+            album: null,
+            url: "https://music.apple.com/us/album/i-forgot-that-you-existed/1468058165?i=1468058169",
+            duration_ms: 170651,
+            track_number: 1,
+            artist_name: null,
+            explicit: false,
+          },
+        },
+      },
+      {
+        name: "Search",
+        method: "GET",
+        description: "Search Apple Music",
+        fullDescription:
+          "Searches Apple Music and returns public result sections for artists, albums, songs, playlists, stations, and music videos. Use type=song, album, artist, playlist, or all.",
+        path: "/v1/apple-music/search",
+        params: [
+          {
+            name: "query",
+            type: "string",
+            required: true,
+            description: "Search query",
+            placeholder: "taylor swift",
+          },
+          {
+            name: "type",
+            type: "string",
+            required: false,
+            description: "Result type to return. Use all, song, album, artist, playlist, station, music_video, or radio_episode.",
+            placeholder: "song",
+          },
+        ],
+        sampleResponse: {
+          success: true,
+          credits_remaining: 49996588521,
+          data: {
+            query: "taylor swift",
+            type: "song",
+            results: [
+              {
+                id: "1833328840",
+                kind: "song",
+                title: "The Fate of Ophelia",
+                artist_name: "Taylor Swift",
+                url: "https://music.apple.com/us/album/the-fate-of-ophelia/1833328839?i=1833328840",
+                duration_ms: 226000,
+              },
+            ],
+          },
+        },
+      },
+    ],
+  },
   {
     id: "spotify",
     name: "Spotify",
-    description: "Scrape Spotify artists, songs, and albums",
+    description: "Scrape Spotify artists, songs, albums, playlists, and podcasts",
     endpoints: [
       {
         name: "Artist",
@@ -29686,6 +30030,89 @@ export const apis = [
           ]
         },
       },
+      {
+        name: "Playlist",
+        method: "GET",
+        description: "Get a Spotify playlist and its tracks",
+        fullDescription:
+          "Retrieves public Spotify playlist metadata and up to 50 tracks by playlist id or URL. For playlists with more tracks, pass the returned cursor into the next request until cursor is null.",
+        path: "/v1/spotify/playlist",
+        params: [
+          {
+            name: "id",
+            type: "string",
+            required: false,
+            description: "Spotify playlist id. If you'd prefer to use the URL instead, you can use the url parameter instead.",
+            placeholder: "37i9dQZF1DX4UtSsGT1Sbe",
+          },
+          {
+            name: "url",
+            type: "string",
+            required: false,
+            description: "Spotify playlist URL. If you'd prefer to use the id instead, you can use the id parameter instead.",
+            placeholder: "https://open.spotify.com/playlist/37i9dQZF1DX4UtSsGT1Sbe",
+          },
+          {
+            name: "cursor",
+            type: "string",
+            required: false,
+            description: "Cursor returned by the previous response. Omit it for the first page.",
+            placeholder: "50",
+          },
+        ],
+        sampleResponse: {
+          "success": true,
+          "credits_remaining": 100,
+          "id": "37i9dQZF1DX4UtSsGT1Sbe",
+          "uri": "spotify:playlist:37i9dQZF1DX4UtSsGT1Sbe",
+          "__typename": "Playlist",
+          "description": "The biggest songs of the 1980s. Cover: Madonna",
+          "followers": 12016730,
+          "images": [
+            {
+              "sources": [
+                {
+                  "height": null,
+                  "url": "https://i.scdn.co/image/ab67706f00000002fb8e01f2c022ab1a32e2c5a0",
+                  "width": null,
+                },
+              ],
+            },
+          ],
+          "name": "All Out 80s",
+          "ownerV2": {
+            "__typename": "User",
+            "name": "Spotify",
+            "uri": "spotify:user:spotify",
+            "username": "spotify",
+          },
+          "tracks": [
+            {
+              "id": "6r8k1vznHrzlEKYxL4dZEe",
+              "uri": "spotify:track:6r8k1vznHrzlEKYxL4dZEe",
+              "name": "La Isla Bonita",
+              "albumOfTrack": {
+                "name": "True Blue",
+                "uri": "spotify:album:6fmnT17jc2Sc69q3nza1eD",
+              },
+              "artists": [
+                {
+                  "profile": {
+                    "name": "Madonna",
+                  },
+                  "uri": "spotify:artist:6tbjWDEIzxoDsBA1FuhfPW",
+                },
+              ],
+              "duration": {
+                "totalMilliseconds": 242733,
+              },
+              "playcount": 785646615,
+            },
+          ],
+          "cursor": 50,
+          "totalCount": 150,
+        },
+      },
       {
         name: "Search",
         method: "GET",
@@ -32487,7 +32914,7 @@ export const apis = [
   {
     id: "snapchat",
     name: "Snapchat",
-    description: "Scrape Snapchat user profiles and thier stories",
+    description: "Scrape Snapchat user profiles and their stories",
     endpoints: [
       {
         name: "User Profile",
@@ -32845,6 +33272,267 @@ export const apis = [
           },
         ],
       },
+      {
+        name: "Spotlight by Link",
+        method: "GET",
+        description: "Get Snapchat Spotlight video data by URL",
+        fullDescription:
+          "Fetches public data for a Snapchat Spotlight video by URL. Returns the snap id, description, creator, engagement counts, thumbnail, and content URL when Snapchat exposes them publicly.",
+        path: "/v1/snapchat/spotlight",
+        sampleResponse: {
+          success: true,
+          credits_remaining: 49997863208,
+          spotlight: {
+            snapId:
+              "W7_EDlXWTBiXAEEniNoMPwAAYY2pvZnd0ZXVmAZ8fgG8pAZ8ff-_IAAAAAQ",
+            storyId:
+              "W7_EDlXWTBiXAEEniNoMPwAAYY2pvZnd0ZXVmAZ8fgG8pAZ8ff-_IAAAAAQ",
+            description:
+              "This is genuinely heartbreaking 💔 #relationship#funny#brainrot",
+            llmTitle: null,
+            llmDescription: null,
+            viewCount: 251845,
+            shareCount: 3807,
+            commentCount: 803,
+            engagementStats: {
+              viewCount: 251845,
+              shareCount: 3807,
+              commentCount: 803,
+              boostCount: 16203,
+              recommendCount: 2670,
+            },
+            creator: {
+              $case: "personCreator",
+              personCreator: {
+                username: "lilah4823",
+                url: "https://www.snapchat.com/@lilah4823",
+                name: "lilah",
+                followerCount: "0",
+                websiteUrl: "",
+              },
+            },
+            durationMs: 56939,
+            width: 540,
+            height: 960,
+            uploadDateMs: 1782915537473,
+            thumbnailUrl:
+              "https://cf-st.sc-cdn.net/d/TXqor3n6nwYvf2nDyAVlN.256.IRZXSOY?mo=GkcaDRoAGgAyAQRIA1AuYAFaEERmTGFyZ2VUaHVtYm5haWyiARAIgAIiCxIAKgdJUlpYU09ZogEQCJoKIgsSACoHSVJaWFNPWQ%3D%3D&uc=46",
+            contentUrl:
+              "https://cf-st.sc-cdn.net/d/TXqor3n6nwYvf2nDyAVlN.1034.IRZXSOY?mo=GkAaDRoAGgAyAQRIA1AuYAGiAS4IiggSHAoaIAFKEQoMY0Y9R0RFR0M5OU8uEPQDWgMQsz8iCxIAKgdJUlpYU09Z&uc=46",
+            raw: {},
+          },
+          linkPreview: {},
+          pageMetadata: {},
+          videoMetadata: {},
+        },
+        params: [
+          {
+            name: "url",
+            type: "string",
+            required: true,
+            description: "Snapchat Spotlight URL.",
+            placeholder:
+              "https://www.snapchat.com/@lilah4823/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY2pvZnd0ZXVmAZ8fgG8pAZ8ff-_IAAAAAQ",
+          },
+        ],
+      },
+      {
+        name: "Spotlight Comments by Link",
+        method: "GET",
+        description: "Get comments from a Snapchat Spotlight URL",
+        fullDescription:
+          "Fetches public comments from Snapchat's Spotlight comments API by URL. Returns the snap id, comments, a cursor for the next page, and hasMore. Pass the returned cursor back as the cursor param to load more comments.",
+        path: "/v1/snapchat/spotlight/comments",
+        sampleResponse: {
+          success: true,
+          credits_remaining: 49997863207,
+          snapId:
+            "W7_EDlXWTBiXAEEniNoMPwAAYY2pvZnd0ZXVmAZ8fgG8pAZ8ff-_IAAAAAQ",
+          comments: [
+            {
+              replyText:
+                "Guys who can't even read a paragraph are hilarious 😭 get yourself a better man",
+              replyPosterDisplayName: "🎸Callie✌️",
+              replyTimestampMs: "1782948905027",
+              threadedReplyCount: 152,
+              reactCounts: [
+                {
+                  reactTypeId: 1,
+                  reactCount: 829,
+                },
+              ],
+            },
+          ],
+          cursor:
+            "CpMCEpACQ3NjQkNnZ0tBbkp6RWdJSUJBb05DZ0owY3hJSENLZjA1TW55TXhLbkFXb1hjMzVrWld4MFlTMW1iM0pqWlMxdVlXMDFMWEJ5YjJSeWl3RUxFaEJUY0c5MGJHbG5hSFJTWlhCc2FXVnpJanRYTjE5RlJHeFlWMVJDYVZoQlJVVnVhVTV2VFZCM1FVRlpXVEp3ZGxwdVpEQmFXRlp0UVZvNFptZEhPSEJCV2pobVppMWZTVUZCUVVGQlVRd0xFaEJUY0c5MGJHbG5hSFJTWlhCc2FXVnpJaVJpWkRKaU1XSTNNeTAzWkRCa0xUUXlOV010T0dKbU1DMDBNVFU1T0RneU1XSTRNekVNR0FBZ0FRPT0SgwISgAJDcjBCQ2cwS0FuUnpFZ2NJNi1LODhmUXpFcWNCYWhkemZtUmxiSFJoTFdadmNtTmxMVzVoYlRVdGNISnZaSEtMQVFzU0VGTndiM1JzYVdkb2RGSmxjR3hwWlhNaU8xYzNYMFZFYkZoWFZFSnBXRUZGUlc1cFRtOU5VSGRCUVZsWk1uQjJXbTVrTUZwWVZtMUJXamhtWjBjNGNFRmFPR1ptTFY5SlFVRkJRVUZSREFzU0VGTndiM1JzYVdkb2RGSmxjR3hwWlhNaUpEYzFNbVZqWWpObUxUSmhZMkV0TkdVM1l5MDVaakF6TFdZNFpUVm1ZVEZrTmpVNVlnd1lBQ0FC",
+          hasMore: true,
+        },
+        params: [
+          {
+            name: "url",
+            type: "string",
+            required: true,
+            description: "Snapchat Spotlight URL.",
+            placeholder:
+              "https://www.snapchat.com/@lilah4823/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY2pvZnd0ZXVmAZ8fgG8pAZ8ff-_IAAAAAQ",
+          },
+          {
+            name: "cursor",
+            type: "string",
+            required: false,
+            description: "Pagination cursor from the previous response.",
+            placeholder:
+              "CpMCEpACQ3NjQkNnZ0tBbkp6RWdJSUJBb05DZ0owY3hJSENLZjA1TW55...",
+          },
+        ],
+      },
+    ],
+  },
+  {
+    id: "creator-tools",
+    name: "Creator Tools",
+    description: "Tools for finding and analyzing creator profiles",
+    endpoints: [
+      {
+        name: "Find Social Profiles",
+        method: "GET",
+        description:
+          "Enter a creator's handle from one social media platform and get all of their social profiles.",
+        fullDescription:
+          "Accepts a supported platform and creator handle, validates both using platform-specific rules, and constructs the canonical source profile URL internally. URLs are not accepted as handles. Supported platforms are Instagram, TikTok, YouTube, X/Twitter, and Facebook; X is accepted as an alias for Twitter. YouTube accepts handles and 24-character channel IDs. The endpoint returns social profiles explicitly linked from the source profile and expands recognized link-in-bio pages. It also re-scrapes up to three supported profiles explicitly linked by the source and follows up to three unique public website URLs declared by the source or those trusted profiles for one page, while preserving each declared path and query. Generic service-provider landing pages reached through parked or unconfigured branded-domain redirects are ignored so the provider's own footer links are not attributed to the creator. It also checks whether the same handle exists on the other supported platforms. All attempted same-handle URLs are returned in same_handle_candidate_urls even when they cannot be verified strongly enough for profiles. Same-handle accounts are included in profiles only when corroborated by a shared owner-controlled website or a reciprocal profile link; matching handles and display names alone are not identity proof. same_handle_match records supporting name evidence at 0.75 confidence, while shared_website and website_link use 0.9. A bounded Google search discovers alternate handles, but Google results are never returned without verification. At most two candidates per other supported platform, up to four total, are re-scraped through that platform's profile scraper. The endpoint may also follow up to two unique recognized link-in-bio URLs declared by the re-scraped Google candidates. The global two-page cap is applied after candidates whose returned handles do not match their Google URLs are rejected. Optional profile probes and page fetches make one attempt and receive the shared enrichment abort signal. A reciprocal source-profile link found there verifies the candidate, and the page's explicit cross-platform profiles can then expand the verified identity graph. Google URLs that re-scrape to the same returned platform handle are deduplicated. A different-handle candidate is accepted only when it links back to the source profile, or when its normalized display name matches and it declares the same owner-controlled public website; common multi-tenant profile and storefront hosts are excluded from shared-website identity evidence. Google discovery uses google_search_match at 0.6, exact names use display_name_match at 0.75, reciprocal links use 0.95, and cross-platform social links explicitly declared by a verified candidate use verified_profile_link at 0.95. Source-linked URLs and failures are returned in source_linked_profile_urls and failed_source_linked_profile_urls. Google candidate URLs, candidate-declared link-in-bio URLs, verified URLs, and failures are returned in google_candidate_urls, google_candidate_link_in_bio_urls, verified_google_candidate_urls, failed_google_candidate_urls, and failed_google_candidate_link_in_bio_urls. Results are deterministic and do not use AI. Mixed or unreachable enrichment results are reported through partial and the matching failure fields. If every declared link-in-bio page fails and no other enrichment finds a profile, the request returns an uncharged 503. A successful live lookup costs 10 credits.",
+        path: "/v1/find-social-profiles",
+        credits: 10,
+        params: [
+          {
+            name: "platform",
+            type: "select",
+            required: true,
+            description: "Source social platform",
+            options: [
+              "instagram",
+              "tiktok",
+              "youtube",
+              "x",
+              "twitter",
+              "facebook",
+            ],
+            placeholder: "instagram",
+          },
+          {
+            name: "handle",
+            type: "string",
+            required: true,
+            description:
+              "Creator handle without a profile URL. A leading @ is optional.",
+            placeholder: "creator",
+          },
+        ],
+        sampleResponse: {
+          source: {
+            platform: "instagram",
+            handle: "creator",
+            url: "https://www.instagram.com/creator",
+          },
+          profiles: [
+            {
+              platform: "instagram",
+              handle: "creator",
+              url: "https://www.instagram.com/creator",
+              confidence: 1,
+              evidence: [
+                "source_profile",
+                "link_in_bio",
+                "verified_profile_link",
+              ],
+            },
+            {
+              platform: "youtube",
+              handle: "creator",
+              url: "https://www.youtube.com/@creator",
+              confidence: 0.9,
+              evidence: [
+                "same_handle_match",
+                "shared_website",
+                "website_link",
+              ],
+            },
+            {
+              platform: "tiktok",
+              handle: "creator",
+              url: "https://www.tiktok.com/@creator",
+              confidence: 1,
+              evidence: ["link_in_bio"],
+            },
+            {
+              platform: "facebook",
+              handle: "creator-page",
+              url: "https://www.facebook.com/creator-page",
+              confidence: 0.95,
+              evidence: [
+                "google_search_match",
+                "display_name_match",
+                "reciprocal_profile_link",
+              ],
+            },
+            {
+              platform: "linkedin",
+              handle: "creator",
+              url: "https://www.linkedin.com/in/creator",
+              confidence: 0.95,
+              evidence: ["verified_profile_link"],
+            },
+          ],
+          link_in_bio_urls: ["https://linktr.ee/creator"],
+          expanded_website_urls: ["https://creator.com/"],
+          source_linked_profile_urls: ["https://x.com/creator"],
+          failed_source_linked_profile_urls: [],
+          same_handle_candidate_urls: [
+            "https://www.tiktok.com/@creator",
+            "https://www.youtube.com/@creator",
+          ],
+          partial: false,
+          failed_link_in_bio_urls: [],
+          failed_website_urls: [],
+          same_handle_search_partial: false,
+          google_search_used: true,
+          google_search_failed: false,
+          google_candidate_urls: [
+            "https://www.facebook.com/creator-page",
+          ],
+          google_candidate_link_in_bio_urls: [
+            "https://linktr.ee/creator",
+          ],
+          failed_google_candidate_link_in_bio_urls: [],
+          verified_google_candidate_urls: [
+            "https://www.facebook.com/creator-page",
+          ],
+          failed_google_candidate_urls: [],
+          google_verification_partial: false,
+        },
+      },
+      {
+        name: "Get Age and Gender",
+        method: "GET",
+        description:
+          "Get age and gender of creator. This uses AI to analyze the profile image. *The profile photo must have a clear face to get an accurate result.*",
+        fullDescription:
+          "Uses AI to analyze a creator's profile photo and estimate their age and gender. Returns ageRange with low and high bounds, gender, and a confidence score for the gender prediction. The profile photo must contain a clear, visible face for accurate results.",
+        path: "/v1/detect-age-gender",
+        sampleResponse: {
+          ageRange: { low: 23, high: 29 },
+          gender: "Male",
+          confidence: { gender: 82.51082611083984 },
+        },
+        params: [
+          {
+            name: "url",
+            type: "string",
+            required: true,
+            description: "URL to users social profile",
+            placeholder: "https://twitter.com/levelsio",
+          },
+        ],
+      },
     ],
   },
   {
@@ -32857,7 +33545,7 @@ export const apis = [
         method: "GET",
         description: "Linktree page",
         fullDescription:
-          "Scrapes a Linktree page by URL, extracting the creator's profile and all their links. Returns id, username, profilePictureUrl, description, verticals, timezone, and links — an array of link objects each with id, type, title, and url. Also includes detected social accounts (instagram, tiktok, spotify, youtube, soundcloud, apple_music) and email_address.",
+          "Scrapes a Linktree page by URL, extracting the creator's profile and all their links. Returns id, username, profilePictureUrl, description, verticals, timezone, and links — an array of link objects each with id, type, title, and url. Also includes detected social accounts (instagram, tiktok, spotify, youtube, soundcloud, apple_music) and email_address. Contact fields come from the submitted public Linktree page. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL.",
         path: "/v1/linktree",
         params: [
           {
@@ -33022,7 +33710,7 @@ export const apis = [
         method: "GET",
         description: "Pillar page",
         fullDescription:
-          "Scrapes a Pillar page by URL, extracting the creator's profile, social links, and products. Returns id, first_name, last_name, email, location, and social accounts (tiktok, spotify, twitter, youtube, facebook, linkedin, instagram, and more). Also includes links with click counts and products with title, price, description, and image.",
+          "Scrapes a Pillar page by URL, extracting the creator's profile, social links, and products. Returns id, first_name, last_name, email, location, and social accounts (tiktok, spotify, twitter, youtube, facebook, linkedin, instagram, and more). Also includes links with click counts and products with title, price, description, and image. Contact fields come from the submitted public Pillar page. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL.",
         path: "/v1/pillar",
         params: [
           {
@@ -33102,7 +33790,7 @@ export const apis = [
         method: "GET",
         description: "Linkbio (lnk.bio) page",
         fullDescription:
-          "Scrapes a Linkbio (lnk.bio) page by URL, extracting the creator's profile and all their links. Returns handle, id, social accounts (instagram, tiktok, youtube, twitter, whatsapp), email, website, and links — an array of link objects each with url and text.",
+          "Scrapes a Linkbio (lnk.bio) page by URL, extracting the creator's profile and all their links. Returns handle, id, social accounts (instagram, tiktok, youtube, twitter, whatsapp), email, website, and links — an array of link objects each with url and text. Contact fields come from the submitted public Linkbio page. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL.",
         path: "/v1/linkbio",
         params: [
           {
@@ -33189,7 +33877,7 @@ export const apis = [
         description:
           "Get products and other details from a creator's Amazon Shop page",
         fullDescription:
-          "Scrapes a creator's Amazon Shop page by URL, returning their storefront profile and product collections. Returns avatar, name, description, socials, and lists with title and itemCount. Also includes trendingPicks with price and discount, curations with title and postCount, and a pageToken for pagination.",
+          "Scrapes a creator's Amazon Shop page by URL, returning their storefront profile and product collections. Returns avatar, name, description, socials, and lists with title and itemCount. Also includes trendingPicks with price and discount, curations with title and postCount, and a pageToken. Pass that pageToken back with the same URL to retrieve the next page; video pages return videos with an id, title, thumbnail, and attached ASINs.",
         path: "/v1/amazon/shop",
         params: [
           {
@@ -33199,6 +33887,14 @@ export const apis = [
             description: "URL to Amazon Shop page",
             placeholder: "https://www.amazon.com/shop/sydneydelrey",
           },
+          {
+            name: "pageToken",
+            type: "string",
+            required: false,
+            description:
+              "Page token returned by a previous response for the same shop URL",
+            placeholder: "amzn1.vse.video...",
+          },
         ],
         sampleResponse: {
           success: true,
@@ -33315,36 +34011,6 @@ export const apis = [
       },
     ],
   },
-  {
-    id: "age-and-gender",
-    name: "Age and Gender",
-    description: "Get age and gender of creator",
-    endpoints: [
-      {
-        name: "Get Age and Gender",
-        method: "GET",
-        description:
-          "Get age and gender of creator. This uses AI to analyze the profile image. *The profile photo must have a clear face to get an accurate result.*",
-        fullDescription:
-          "Uses AI to analyze a creator's profile photo and estimate their age and gender. Returns ageRange with low and high bounds, gender, and a confidence score for the gender prediction. The profile photo must contain a clear, visible face for accurate results.",
-        path: "/v1/detect-age-gender",
-        sampleResponse: {
-          ageRange: { low: 23, high: 29 },
-          gender: "Male",
-          confidence: { gender: 82.51082611083984 },
-        },
-        params: [
-          {
-            name: "url",
-            type: "string",
-            required: true,
-            description: "URL to users social profile",
-            placeholder: "https://twitter.com/levelsio",
-          },
-        ],
-      },
-    ],
-  },
   {
     id: "scrape-creators",
     name: "Scrape Creators",
@@ -33502,7 +34168,7 @@ export const apis = [
         method: "GET",
         description: "Get Linkme profile info by URL",
         fullDescription:
-          "Retrieves a Linkme profile by URL, including identity, social links, and contact details. Returns profile with id, firstName, username, bio, profileVisitCount, profileImage, verifiedAccount, and isAmbassador flag. Also includes infoLinks (email addresses) and webLinks, an array of categorized social platform links (Spotify, Instagram, YouTube, Twitter, Facebook, and more) each with linkValue and faceValue.",
+          "Retrieves a Linkme profile by URL, including identity, social links, and contact details. Returns profile with id, firstName, username, bio, profileVisitCount, profileImage, verifiedAccount, and isAmbassador flag. Also includes infoLinks (email addresses) and webLinks, an array of categorized social platform links (Spotify, Instagram, YouTube, Twitter, Facebook, and more) each with linkValue and faceValue. Contact fields come from the submitted public Linkme profile. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL.",
         path: "/v1/linkme",
         params: [
           {
@@ -33879,3 +34545,114 @@ export const apis = [
     ],
   },
 ];
+
+// mirrors CACHEABLE_ROUTES in the api's responseCache.js — keep in sync.
+const CACHEABLE_PATHS = new Set([
+  "/v2/instagram/media/transcript",
+  "/v1/instagram/profile",
+  "/v1/instagram/basic-profile",
+  "/v1/instagram/post",
+  "/v2/instagram/post",
+  "/v3/instagram/post",
+  "/v1/tiktok/profile",
+  "/v2/tiktok/video",
+  "/v1/facebook/adLibrary/ad",
+  "/v1/facebook/adLibrary/ad/transcript",
+  "/v1/facebook/post",
+  "/v1/facebook/post/transcript",
+  "/v1/facebook/profile",
+  "/v1/youtube/channel",
+  "/v1/youtube/video",
+  "/v1/youtube/video/transcript",
+  "/v1/google/ad",
+  "/v1/find-social-profiles",
+  "/v1/threads/post",
+  "/v1/threads/profile",
+  "/v1/twitter/profile",
+  "/v1/twitter/tweet",
+  "/v1/twitter/tweet/transcript",
+  "/v1/pinterest/pin",
+  "/v1/komi",
+  "/v1/linkbio",
+  "/v1/linkme",
+  "/v1/linktree",
+  "/v1/pillar",
+  "/v1/twitch/clip",
+  "/v1/twitch/profile",
+  "/v1/reddit/subreddit",
+  "/v1/reddit/subreddit/details",
+  "/v1/reddit/ad",
+  "/v1/reddit/post/transcript",
+  "/v1/telegram/channel",
+  "/v1/telegram/channel/posts",
+  "/v1/telegram/post",
+]);
+
+const CACHE_MAX_AGE_PARAM = {
+  name: "cache_max_age",
+  type: "select",
+  required: false,
+  options: ["1d", "3d", "7d", "14d", "30d"],
+  placeholder: "7d",
+};
+
+// envelope fields the api adds to every response body.
+const SAMPLE_CREDITS_REMAINING = 1000000;
+const SAMPLE_CACHED_AT = "2026-07-20T14:32:11.000Z";
+
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+// prepends success/credits_remaining/credits_charged to a 200 sample.
+// values already present in the sample win; arrays are left untouched.
+const withEnvelope = (sample, creditsCharged) =>
+  isPlainObject(sample)
+    ? {
+        success: true,
+        credits_remaining: SAMPLE_CREDITS_REMAINING,
+        credits_charged: creditsCharged,
+        ...sample,
+      }
+    : sample;
+
+// applied here (instead of per endpoint) so the docs, openapi spec, and
+// synced copies all pick everything up from one place.
+for (const api of apis) {
+  for (const endpoint of api.endpoints) {
+    const creditsCharged =
+      typeof endpoint.credits === "number" ? endpoint.credits : 1;
+
+    endpoint.sampleResponse = withEnvelope(endpoint.sampleResponse, creditsCharged);
+    for (const variant of [
+      "trimmedResponse",
+      "privateResponse",
+      "ageRestrictedResponse",
+      "gatedProfileResponse",
+    ]) {
+      if (endpoint[variant]) {
+        endpoint[variant] = withEnvelope(endpoint[variant], creditsCharged);
+      }
+    }
+
+    if (CACHEABLE_PATHS.has(endpoint.path)) {
+      const creditLabel = `${creditsCharged} ${creditsCharged === 1 ? "credit" : "credits"}`;
+      endpoint.params = [
+        ...(endpoint.params || []),
+        {
+          ...CACHE_MAX_AGE_PARAM,
+          description: `If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (${creditLabel}). [See the Caching page for details.](https://docs.scrapecreators.com/caching)`,
+        },
+      ];
+      // "200 (cached)" tab: same data, free, plus cached markers at the end
+      // (mirrors where the api appends them).
+      if (isPlainObject(endpoint.sampleResponse)) {
+        endpoint.cachedResponse = {
+          ...endpoint.sampleResponse,
+          credits_charged: 0,
+          cached: true,
+          cached_at: SAMPLE_CACHED_AT,
+        };
+      }
+    }
+  }
+}