Substack by Category API for live newsletter ranks

The Substack by Category API on Trends MCP is get_top_trends with type Substack by Category. From the August 30, 2026 scan, an HTTP 400 unknown-category error listed 15 valid names. llms.txt the same day listed 31, including Comics, Parenting, and Science, all of which returned that 400. Omit category and the mixed board stamped 2026-08-30T06:01:57 UTC with 13 rank-1 rows, one per in-sync category. Climate & Environment and Faith & Spirituality sit on the 15-name list yet used older stamps (00:01 and 04:01) and never appeared in that mix. Pass category Technology for a 1 through 100 list that closed at offset 100. Free tier access is 100 requests per month.

HTTP 400 lists 15 names; llms.txt lists 31

The live category contract is the HTTP 400 payload, not the 31-name table on llms.txt. A probe of NotARealCategory returned error invalid_request with message prefix Unknown category 'NotARealCategory'. Valid categories: followed by exactly 15 names: Art & Illustration, Business, Climate & Environment, Culture, Faith & Spirituality, Fashion & Beauty, Finance, Food & Drink, Health Politics, Music, News, Sports, Technology, U.S. Politics, World Politics.

llms.txt on 2026-08-30 still printed 31 Substack by Category names. The 16 extras all returned that same 400 on this pull: Comics, Crypto, Design, Education, Fiction, Film & TV, Health & Wellness, History, Home & Garden, Humor, International, Literature, Parenting, Philosophy, Science, Travel. Parenting is the expensive miss. Overall Substack rank 7 on this stamp was Your Brain On Mom, and there is no filtered Parenting board to join it to.

Category strings are display names, not Substack numeric IDs. technology resolved to Technology and returned the same top 5 as the canonical spelling, led by SemiAnalysis. Food and Drink (the word "and") returned 400; the working string is Food & Drink. Dropping the periods from U.S. Politics returned 400. Copy from the 400 list. Guessing from a Substack leaderboard URL wastes a request. Substack's own public category endpoint uses numeric IDs and a fixed page of 25; Trends MCP uses these display names with limit up to 200 and offset. Those are different contracts.

The named-board pattern also appears on Google Trends by Category and TikTok Trending Hashtags by Category. Those feeds publish longer valid-name lists. This one does not.

Unfiltered rows mix 13 clocks, not 15 captains

Omit category and the rank field is not a global 1-N list. On the 2026-08-30T06:01:57 UTC stamp, limit 50 at offset 0 returned 13 rank-1 rows, then 13 rank-2 rows, then 13 rank-3 rows, then rank-4 rows. Each rank band reused the same 13 in-sync names: Sports, Food & Drink, Health Politics, U.S. Politics, Culture, Technology, Fashion & Beauty, World Politics, Art & Illustration, Music, News, Business, Finance.

Climate & Environment stamped 2026-08-30T00:01:36 UTC, six hours earlier. Faith & Spirituality stamped 2026-08-30T04:01:38 UTC, two hours earlier. Neither captain appeared in the 06:01 mix. The unfiltered feed is the set of boards that share one as_of_ts, grouped by rank. It is not one captain per official name. That differs from Amazon Best Sellers by Category, where an unfiltered page is rank-1 captains across departments on a single stamp.

Default limit 25 therefore stops during the rank-2 band. Offset 50 on this stamp was already inside rank 4 and rank 5. Offset 100 was inside rank 8 through rank 12. If the 13 in-sync boards each hold 100 titles, the mixed feed is 1,300 rows. Paginate it, or pass category and skip the mix.

Rank-1 captains on the 06:01 stamp included Inside Wolves with Liam Keen and Nathan Judah (Sports), beyond beurre blanc. (Food & Drink), Unreported Truths (Health Politics), The Bulwark (U.S. Politics), Blocked and Reported (Culture), SemiAnalysis (Technology), So Many Thoughts (Fashion & Beauty), The Long Game with Jake Sullivan & Jon Finer (World Politics), The Needlepoint Finishing Club (Art & Illustration), Unhappy Place (Music), The Parnas Perspective (News), Friday Forward (Business), and Citrini Research (Finance).

Technology closes at 100; Climate stops at 25

Pass an official name and the rank field becomes a true 1-N list. Technology on the 06:01 stamp returned 50 rows at offset 0, 50 rows at offset 50 (ranks 51 through 100), then count 0 at offset 100. Sports matched that close: 50 plus 50, then count 0 at offset 100. News matched it too. Default limit 25 is 25 percent of those boards.

Climate & Environment, on the older 00:01 stamp, returned count 25 at limit 50 and count 0 at offset 50. Faith & Spirituality, on the 04:01 stamp, also returned 25 titles and then an empty second page. Official name does not imply a 100-row board. Quote as_of_ts plus the empty offset page.

Technology rank 1 was SemiAnalysis. Rank 2 was Thinking Freely with Nita Farahany. Rank 3 was Computer, Enhance!. Rank 4 was Pirate Wires. Rank 5 was Marcus on AI. Rank 7 was Mo Bitar, who also sat at overall Substack rank 29. Rank 11 was Research toolbox, overall rank 34. Rank 33 was Women + AI, overall rank 55. Several Technology titles leak onto the sibling Substack overall board. Most of the 100 do not.

Sports rank 1 was Inside Wolves with Liam Keen and Nathan Judah, matching overall Substack rank 1. Rank 2 was InsideNUFC, matching overall rank 2. Rank 8 was Bernie Miklasz, overall rank 12. Rank 18 was Matt Calkins, overall rank 20. Rank 36 was Baltimore Film Breakdown, matching overall rank 36. Sports names occupy the head of the overall board. Technology names mostly do not.

Faith rank 24 was Worship Design Studio, which also sat at overall rank 42 on the later 06:01 overall stamp. Climate rank 6 was Kirsten Bradley, overall rank 45. Cross-stamp title matches still happen. Join by exact title, not by assuming one clock.

window 3d filled; 1d and 7d turned over

sort rank_change on this feed is not a daily climber board by default. Technology window 3d stamped the same 06:01 as_of_ts against baseline 2026-08-27T02:01:32 UTC and returned count 14. The largest climb in that page was LearnAIWithMe at rank 8, previous rank 80, rank_change 72. Nimble AF* Bytes sat at rank 24, previous 78, rank_change 54. Newcomer sat at rank 22, previous 58, rank_change 36. SemiAnalysis, the current rank 1, only climbed 2 places (previous rank 3). Level Up with AI sat at rank 89, previous 91, rank_change 2. Default sort rank at limit 25 never prints rank 89.

Sports window 3d, same baseline, returned count 18. Data Dribble sat at rank 13, previous 61, rank_change 48. Small Craft Advisor sat at rank 54, previous 99, rank_change 45. The Scoring Letter sat at rank 61, previous 68. College Hockey Insider by Mike McMahon sat at rank 77, previous 83. Several 3d climbers live past the first 25 current-rank rows. Offset details for feeds that page past 25 live on get_top_trends offset and limit.

Technology window 1d set baseline 2026-08-29T08:01:29 UTC and returned count 0: the board turned over completely versus that baseline, so no rank change could be computed. Sports 1d returned the same complete-turnover note. Technology window 7d set baseline 2026-08-25T20:01:41 UTC and also returned count 0 with complete turnover. Those windows had a baseline_ts. They still produced no climber rows.

Default window (30d) on Technology set baseline_ts to null and noted no baseline within 10 days of 2026-07-31. Window 14d noted no baseline within 5 days of 2026-08-16. Climate & Environment window 3d, on its older 00:01 stamp against baseline 2026-08-27T00:01:30 UTC, returned count 0 with complete turnover even though Technology 3d filled. Do not copy a working window from one official name to another.

Rows under sort=rank_change are objects with rank, keyword, prev_rank, rank_change, and category_path. Default sort rank rows are [rank, title, category] arrays. Parse them as different shapes.

Exact type string, then a filtered call

MCP and REST both use type Substack by Category. REST body for captains that share one clock:

{"mode": "get_top_trends", "type": "Substack by Category", "limit": 25}

Filtered 1-N list:

{"mode": "get_top_trends", "type": "Substack by Category", "category": "Technology", "limit": 50, "offset": 0}

Climbers on the window that filled in this pull:

{"mode": "get_top_trends", "type": "Substack by Category", "category": "Technology", "sort": "rank_change", "window": "3d", "limit": 25}

google search follow-up on a captain (261 weekly points, recent_date 2026-08-29 in this run):

{"mode": "get_growth", "source": "google search", "keyword": "SemiAnalysis", "percent_growth": ["7D", "30D", "3M", "12M"]}

Each of those calls counts as one request. get_growth still counts as one request when percent_growth holds several presets. The overall Substack type string is Substack, without "by Category". Do not "correct" the filtered type down to that overall board.

Overall rank 3 sat outside every captain row

Overall Substack, same 06:01 stamp, returned 50 titles at offset 0 and 47 titles at offset 50 (ranks 51 through 97), then count 0 at offset 97, for a closed board of 97. Rank 1 was Inside Wolves with Liam Keen and Nathan Judah. Rank 2 was InsideNUFC. Rank 3 was Spencer Pratt. Rank 5 was Callie Coles. Rank 7 was Your Brain On Mom. Spencer Pratt and Callie Coles were absent from the 13 rank-1 captains. Your Brain On Mom has no Parenting board to land on.

google search for Spencer Pratt sat at 2.0 on 2026-08-29, up 100.0% over 7 days from 1.0, and down 94.12% over 3 months from 34.0 (261 weekly points). Overall rank 3 did not imply a large search index.

SemiAnalysis, Technology rank 1 and absent from overall 97, sat at google search 16.0 on 2026-08-29, down 5.88% over 7 days from 17.0, down 44.83% over 30 days from 29.0, down 48.39% over 3 months from 31.0, and down 11.11% over 12 months from 18.0. Pirate Wires, Technology rank 4, sat at 10.0, down 41.18% over 7 days from 17.0. The 30-day Pirate Wires window compared 10.0 against baseline_value 0.0; the printed percent is unusable. Report the two values.

The Bulwark, U.S. Politics rank 1, sat at 48.0, up 4.35% over 7 days from 46.0, down 4.0% over 30 days from 50.0, and down 22.58% over 3 months from 62.0. Unreported Truths, Health Politics rank 1, sat at 4.0 against baseline 0.0 on 7D, 30D, and 3M, with data_quality low (over 90% zeros). Quote 4.0 versus 0.0. Do not publish the 999999.0 percent.

LearnAIWithMe, the Technology 3d top climber, sat at google search 0.0 across 7D, 30D, and 3M, also data_quality low. A 72-place climb on the live board can still have an empty search series.

google search for the string Inside Wolves sat at 55.0 on 2026-08-29, up 3.77% over 7 days from 53.0, and down 40.22% over 30 days from 92.0. That keyword is also a football-club nickname. Treat it as the string sent to get_growth, not as proof of newsletter demand.

The free plan includes 100 requests per month with no credit card. Starter is $19 per month for 1,000 requests. Pro is $49 for 5,000. Business is $199 for 25,000. Annual billing saves 20% on the paid plans. Check current pricing before locking a production budget.