MLH APImlh.io ↗
Access MLH hackathon event data by season, region, country, and date range. Filter for upcoming, past, or diversity-focused events via 8 structured endpoints.
What is the MLH API?
The MLH API exposes 8 endpoints covering Major League Hacking event listings, including season-level queries, regional and country filters, and a diversity-focused filter. get_events_by_season returns the full roster of events for any season from 2020 onward, with each event object carrying fields like starts_at, ends_at, location, format_type, country, and underserved_types. Endpoints default to the current season year when no year parameter is supplied.
curl -X GET 'https://api.parse.bot/scraper/3567c07e-65ee-4aae-8ecb-8871a1b44e80/get_events_by_season?year=2025' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace mlh-io-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: MLH Hackathon Events SDK — bounded, re-runnable."""
from parse_apis.mlh_hackathon_events_api import MLH, Region, NotFoundError
mlh = MLH()
# List all available seasons.
for season in mlh.seasons.list(limit=5):
print(season.year, season.url)
# Construct a season and list all its events (capped).
season = mlh.season(2025)
for event in season.all_events(limit=5):
print(event.name, event.starts_at, event.location)
# Filter by region using the enum.
for event in season.by_region(region=Region.NORTH_AMERICA, limit=3):
print(event.name, event.city, event.country)
# Get diversity-focused events for 2025.
for event in season.diversity_focused(limit=3):
print(event.name, event.underserved_types)
# Fetch a season via the collection accessor and drill into upcoming.
try:
s = mlh.seasons.get(year=2026)
first_upcoming = s.upcoming(limit=1).first()
if first_upcoming:
print(first_upcoming.name, first_upcoming.website_url)
except NotFoundError as exc:
print(f"Season not found: {exc}")
print("exercised: seasons.list / season.all_events / by_region / diversity_focused / seasons.get / upcoming")
Get all hackathon events (upcoming and past) for a specific MLH season year. Returns the full list of events for that season. Each season spans an academic year (e.g. 2025 covers roughly Aug 2024–Jun 2025). Paginates as a single page.
| Param | Type | Description |
|---|---|---|
| year | integer | MLH season year (e.g. 2025, 2026). Defaults to current year. |
{
"type": "object",
"fields": {
"year": "integer — the season year queried",
"events": "array of Event objects with full hackathon details"
},
"sample": {
"data": {
"year": 2025,
"events": [
{
"id": "0192491f-4c83-3e59-ca3a-fa764277666b",
"url": "https://mlh.io/events/gdg-solution-hacks/prizes",
"city": "Toronto",
"name": "GDG Solution Hacks",
"slug": "gdg-solution-hacks",
"state": "Canada",
"region": "AMER",
"status": "ended",
"country": "CA",
"ends_at": "2025-06-29T19:00:00Z",
"location": "Toronto, Canada",
"logo_url": "https://mlhusercontent.com/logos/events/0192491f-4c83-3e59-ca3a-fa764277666b/gdg-solution-hacks_small.png",
"starts_at": "2025-06-27T21:00:00Z",
"date_range": "JUN 27 - 29",
"format_type": "physical",
"website_url": "https://thesolutionhacks.site/",
"background_url": "https://mlhusercontent.com/backgrounds/events/0192491f-4c83-3e59-ca3a-fa764277666b/gdg-solution-hacks_medium.png",
"underserved_types": []
}
]
},
"status": "success"
}
}About the MLH API
Event Data Coverage
Each event object returned across all endpoints includes fields such as id, name, slug, status, starts_at, ends_at, date_range, location, city, state, country, format_type, and underserved_types. The format_type field indicates whether an event is in-person, virtual, or hybrid. The underserved_types array is what get_diversity_focused_events uses as its filter criterion — any event with a non-empty array there is included.
Season and Time Filtering
get_events_by_season accepts a year integer (e.g., 2025 or 2026) and returns all events — upcoming and past — for that MLH season. get_upcoming_events and get_past_events split that same pool by whether an event has ended. get_events_this_month narrows results to events starting in the current UTC calendar month, returning the month integer alongside matched events. get_season_list probes years from 2020 to the next calendar year and returns an array of objects with year and url, letting you discover which seasons have active data before querying them.
Geographic Filtering
get_events_by_region accepts either full region names (North America, Europe, Asia Pacific) or shorthand codes (AMER, EU, APAC). get_events_in_date_range accepts start_date and end_date in YYYY-MM-DD format and an optional two-letter country code (e.g., US, IN, CA). Events are included when their time span overlaps the specified range, not just when they start within it. Both the start and end ISO datetimes of the resolved range are echoed back in the response.
Limitations and Scope
The season year parameter controls which season's pool is searched, but get_events_this_month always applies the current UTC month as its time filter regardless of the year passed. Season data is available from 2020 onward; querying years outside that window may return empty results. No endpoint currently returns event-level details such as registration links, participant counts, prize descriptions, or sponsor data.
The MLH API is a managed, monitored endpoint for mlh.io — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when mlh.io changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official mlh.io API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a hackathon calendar app that lists upcoming MLH events filtered by region using
get_events_by_region - Alert students to hackathons starting in their country in the next 7 days using
get_events_in_date_rangewith a country code - Identify diversity-focused hackathons for outreach programs using
get_diversity_focused_eventsand theunderserved_typesfield - Track which MLH seasons have published event pages using
get_season_listbefore querying historical data - Display this month's hackathon schedule on a university tech club site using
get_events_this_month - Analyze the ratio of virtual to in-person events across a season using the
format_typefield fromget_events_by_season - Compare past versus upcoming event counts for a given season year using
get_past_eventsandget_upcoming_events
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does MLH have an official developer API?+
What does `get_events_in_date_range` return, and how does the overlap logic work?+
get_events_in_date_range returns all events whose time span overlaps the specified window — meaning an event that starts before start_date but ends within the range will still be included. The response echoes back the resolved start and end ISO datetimes, the country filter applied (or null if omitted), and the matched events array. The default range is today through 7 days later if no dates are provided.How does the `year` parameter interact with `get_events_this_month`?+
year parameter in get_events_this_month determines which MLH season pool is searched, but the month filter is always fixed to the current UTC calendar month. Passing a past year will search that season's events but still filter by the current month, which may return few or no results if that season has ended.