mlh.io 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.
curl -X GET 'https://api.parse.bot/scraper/3567c07e-65ee-4aae-8ecb-8871a1b44e80/get_events_by_season?year=2026' \ -H 'X-API-Key: $PARSE_API_KEY'
Get all hackathon events (upcoming and past) for a specific MLH season year. Returns the full list of events for that season.
| 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 id, name, slug, status, starts_at, ends_at, date_range, location, city, state, country, format_type, region, website_url, logo_url, background_url, underserved_types, url"
},
"sample": {
"data": {
"year": 2026,
"events": [
{
"id": "019c6b2f-e735-d114-2328-fef1b1d131f1",
"url": "https://mlh.io/events/global-hack-week-genai-25/prizes",
"city": null,
"name": "Global Hack Week: GenAI",
"slug": "global-hack-week-genai-25",
"state": null,
"region": null,
"status": "pending",
"country": null,
"ends_at": "2026-05-14T17:00:00Z",
"location": "Everywhere, Worldwide",
"logo_url": "https://mlhusercontent.com/logos/events/019c6b2f-e735-d114-2328-fef1b1d131f1/global-hack-week-genai-25_b5f87080a2f2_small.jpg",
"starts_at": "2026-05-08T16:00:00Z",
"date_range": "MAY 08 - 14",
"format_type": "digital",
"website_url": "https://events.mlh.io/events/13816-global-hack-week-genai",
"background_url": "https://mlhusercontent.com/backgrounds/events/019c6b2f-e735-d114-2328-fef1b1d131f1/global-hack-week-genai-25_8e1da92058b9_medium.png",
"underserved_types": []
}
]
},
"status": "success"
}
}About the mlh.io 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.
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.
- 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 | 250 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.