We grade every House, Senate, and gubernatorial prediction market on Kalshi -- daily, A through F -- on volume, spread, and open interest. If you want to know what that means and why, read Your Local Market.
This post is about the API. All of that data is now available as a free, public JSON endpoint. No API key. No authentication. No rate limit (be reasonable). Just fetch and go.
Try it now -- scroll down to the interactive terminal at the bottom of this page and click any of the suggestion buttons, or type your own curl command. It runs live against our API, right in your browser.
Base URL
https://theheatsheet.com/api/grades
Get latest grades
curl https://theheatsheet.com/api/grades
Returns all graded races for the most recent date, sorted by liquidity score.
Filter by chamber
curl "https://theheatsheet.com/api/grades?chamber=senate"
Options: senate, house, governor.
Filter by state
curl "https://theheatsheet.com/api/grades?state=IA"
Uses two-letter state abbreviations.
Filter by grade
curl "https://theheatsheet.com/api/grades?grade=A"
Options: A, B, C, D, F.
Filter by minimum liquidity
curl "https://theheatsheet.com/api/grades?min_liquidity=0.7"
Only returns races with a composite liquidity score at or above the threshold (0 to 1).
Look up a single race
curl "https://theheatsheet.com/api/grades?race=S2026IA02"
Race IDs follow the format: {chamber prefix}{year}{state}{district}. Senate is S, House is H, Governor is G.
Historical data
curl "https://theheatsheet.com/api/grades?date=2026-02-27"
Pull grades from a specific date. Use ?dates to list all available dates:
curl "https://theheatsheet.com/api/grades?dates"
Pretty-print for the terminal
Add format=table to any request and get a formatted ASCII table instead of JSON -- with box-drawing, liquidity bars, and percentile ranks:
curl "https://theheatsheet.com/api/grades?chamber=senate&format=table"
Works with every filter. Single race lookups get a detailed card:
curl "https://theheatsheet.com/api/grades?race=S2026IA02&format=table"
Combine filters
Filters stack. Get all A-graded Senate races as a table:
curl "https://theheatsheet.com/api/grades?chamber=senate&grade=A&format=table"
Response format
JSON (default)
{
"date": "2026-02-28",
"total": 34,
"races": [
{
"race_id": "S2026IA02",
"event_ticker": "SENATEIA-26",
"kalshi_url": "https://kalshi.com/markets/senateia/...",
"chamber": "Senate",
"state": "IA",
"state_name": "Iowa",
"label": "Iowa",
"grade": "A",
"liquidity_score": 0.818,
"volume_pct": 0.817,
"spread_pct": 0.803,
"oi_pct": 0.852
}
]
}
Fields:
- race_id -- Unique identifier (
S2026IA02= Senate, 2026, Iowa, seat 02) - grade -- Letter grade A through F based on composite liquidity
- liquidity_score -- Raw composite score from 0 to 1
- volume_pct -- Volume percentile rank within race type
- spread_pct -- Inverse spread percentile (higher = tighter spread)
- oi_pct -- Open interest percentile
- kalshi_url -- Direct link to the market on Kalshi
Try it live
The interactive terminal below runs against our real API. Click a suggestion or type your own curl command.
Use cases
We built this because we wanted it ourselves. If you're a journalist fact-checking a prediction market citation, a campaign tracking market sentiment across competitive races, a researcher studying market quality, or just someone who wants to filter out the noise -- this is for you.
The data updates daily. This is not a forecast. We are grading the thermometer, not predicting the weather.