# Royal Road Rising Stars History

A historical analytics platform tracking Royal Road's "Rising Stars" fiction rankings since September 2023. Captures snapshots every 30 minutes of the main list plus 16 genre lists and 63 tag lists.

## Data Coverage

- 19,000+ snapshots from September 2023 to present
- 1,700+ tracked fictions with complete ranking histories
- 980,000+ individual ranking entries
- Notable data gap: May 2024 – November 2024
- Snapshot frequency: twice per hour (:10 and :40)

## What You Can Do

- Get current Rising Stars top 50 with rank and follower deltas vs previous snapshot and 24h ago
- Retrieve rankings at any historical point since September 2023 by snapshot ID or timestamp
- Compare any two snapshots to see new entries, exits, and rank movement
- Get complete ranking history for any of the 1,478 tracked fictions
- Check which of 79 genre/tag Rising Stars lists a fiction currently appears on
- Analyze publishing cohorts (fictions published within ±15 days of a reference date)
- Calculate churn rate (new entry rate) over any time window
- Download complete hourly stats per fiction as CSV

## Rate Limits

- Standard endpoints: 100 requests/minute
- Strict endpoints: 10 requests/minute
- Exceeding limits returns HTTP 429 Too Many Requests

## API Base URL

https://rst.doomlabs.net/api

## Endpoints

### Current Rankings
GET /api/snapshots/latest
Returns the current top 50 with rank_delta, followers_delta, rank_24h_delta, followers_24h_delta.

### Rankings at a Specific Time
GET /api/snapshots/closest?time=YYYY-MM-DD+HH:MM:SS
GET /api/snapshots/closest?time=1h (or 30m, 2d, 1w, 1mo, 1y)
Returns the snapshot closest to the requested timestamp with full rankings, deltas, tags, and 24h comparisons — same fields as /latest.

### List Snapshots
GET /api/snapshots?limit=100&valid_only=true&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
Returns snapshot metadata for building a timeline or selector.

### Snapshot by ID
GET /api/snapshots/{id}
Returns a specific snapshot with full rankings, deltas, tags, and 24h comparisons — same fields as /latest.

### Compare Two Snapshots
GET /api/snapshots/compare?snapshot1={id}&snapshot2={id}
Returns new entries, dropped entries, and the top 10 movers in each direction.

### Time Series (for charting)
GET /api/snapshots/timeseries?bucket=daily&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
Returns one snapshot per hour or per day for use in time-series charts.

### Fiction Ranking History
GET /api/fictions/{fiction_id}/history
Returns complete ranking history for a fiction with stats: best_rank, worst_rank, trend (improving/declining/stable).

### Fiction Stats CSV
GET /api/fictions/{fiction_id}/full-stats
Downloads a CSV of hourly stats: timestamp, views, followers, favorites, rs_pos.

### Genre/Tag Membership Check
GET /api/check-rising-stars?fictionId={id}
Returns which of the 79 Rising Stars lists (main + 16 genres + 63 tags) a fiction currently appears on, with position.

### Churn Rate
GET /api/analytics/churn?days=30&reference_date=ISO8601
Returns daily churn rate history. Churn = percentage of new entries per snapshot cycle.

### Hall of Fame
GET /api/hall-of-fame?window=YYYY-QX&limit=50
Returns top 50 Legends (longest duration on Rising Stars) and top 50 Titans (peak followers) for a calendar quarter. Omit window to get the most recent quarter. Response includes available_windows listing all valid quarter IDs.

### Publishing Cohort Analysis
GET /api/cohorts?fictionId=138753
GET /api/cohorts?date=2024-03-15
Returns all fictions published within ±15 days of the reference date with peak rank, max followers, and first seen on RS. Provide either fictionId (uses that fiction's publish date) or date (YYYY-MM-DD).

### Health
GET /api/health
Returns system status, latest snapshot age, database connectivity, and memory usage.

## Input Formats

- fiction_id / fictionId: Royal Road external fiction ID (integer, e.g. 138753)
- Timestamps for /closest: ISO 8601 (e.g. "2024-06-15T14:30:00Z") or relative (e.g. "1h", "30m", "2d", "1w", "1mo", "1y")
- Dates: YYYY-MM-DD (e.g. "2024-06-15")
- Snapshot IDs: positive integers

## Pages (human-readable UI)

- / — Homepage
- /rising-stars?snapshot={id}&time={relative_or_absolute} — Current/historical leaderboard
- /fictions — Browse all 1,700+ tracked fictions
- /fictions/{fiction_id} — Fiction detail with ranking charts
- /hall-of-fame?window=YYYY-QX — Quarterly top fictions by duration and peak followers
- /cohorts?mode=fiction&fiction={name_or_id} — Publishing cohort analysis
- /rising-stars-checker — Check which genre lists a fiction is on

## Full API Reference

https://rst.doomlabs.net/openapi.json

## Agent Discovery

- A2A Agent Card: https://rst.doomlabs.net/.well-known/agent-card.json
- OpenAPI 3.1 Spec: https://rst.doomlabs.net/openapi.json
- This file: https://rst.doomlabs.net/llms.txt