From HaloRuns Wiki
Jump to: navigation, search

The HaloRuns API is entirely contained in the subdirectory /api/. There are some conventions that multiple API calls follow.

Level IDs

Each level on HaloRuns can be referred to by a 4-character string of numerals. This string is produced by concatenating the number of the game that the level occurs in with the level's number within that game. For example, Tip of the Spear in Halo: Reach's ID is 0504.

Game Numbers

Game Number
Halo: Combat Evolved 01
Halo 2 02
Halo 3 03
Halo 3: ODST 04
Halo: Reach 05
Halo 4 06
Halo 2 MCC 07
Halo 5 08

Level Numbers

Halo: Combat Evolved

Level Number
Pillar of Autumn 01
Halo 02
Truth and Reconciliation 03
The Silent Cartographer 04
Assault on the Control Room 05
343 Guilty Spark 06
The Library 07
Two Betrayals 08
Keyes 09
The Maw 10

Halo 2

Level Number
Cairo Station 01
Outskirts 02
Metropolis 03
The Arbiter 04
Oracle 05
Delta Halo 06
Regret 07
Sacred Icon 08
Quarantine Zone 09
Gravemind 10
Uprising 11
High Charity 12
The Great Journey 13

Halo 3

Level Number
Sierra 117 01
Crows Nest 02
Tsavo Highway 03
The Storm 04
Floodgate 05
The Ark 06
The Covenant 07
Cortana 08
Halo 09

Halo 3: ODST

Level Number
Prepare to Drop 01
Tayari Plaza 02
Uplift Reserve 03
Kizingo Blvd. 04
ONI Alpha Site 05
Kilowani Station 07
Data Hive 08
Coastal Highway 09

Halo: Reach

Level Number
Winter Contingency 01
ONI: Sword Base 02
Nightfall 03
Tip of the Spear 04
Long Night of Solace 05
Exodus 06
New Alexandria 07
The Package 08
The Pillar of Autumn 09

Halo 4

Level Number
Dawn 01
Requiem 02
Forerunner 03
Infinity 04
Reclaimer 05
Shutdown 06
Composer 07
Midnight 08

Halo 5

Level Number
Osiris 01
Blue Team 02
Glassed 03
Unconfirmed 04
Evacuation 05
Reunion 06
Swords of Sanghelios 07
Enemy Lines 08
Battle of Sunaion 09
Genesis 10
The Breaking 11
Guardians 12

API Calls

Global Modifiers


Specifies how the API call's response will be formatted.


JSON format. Example: https://haloruns.com/api/request?query=recentRuns&format=json


JSON format, where each item in the object is a pretty printed string. Example: https://haloruns.com/api/request?query=recentRecords&format=prettyjson


Only display information associated with runners from the country specified by an ISO 3166 country code.

Example: https://haloruns.com/api/request?query=country&country=mx

Recent Runs

GET /api/request?query=recentRuns[&limit=N]

Returns a list of the most recent verified runs submitted to the site. If GET[limit] isn't specified as a number below 50, the 50 latest runs are returned.


GET /api/request?query=records&level=levelID[&isCoop=0&difficulty=0]

Returns the current records for the level specified by GET[level]. If GET[isCoop] isn't specified, both solo and co-op records are returned. If GET[difficulty] isn't specified, both easy and legendary records are returned. If neither is specified, all 4 records for the level are shown in the following order: Solo Easy, Solo Legendary, Co-op Easy, Co-op Legendary.

Recent Records

GET /api/request?query=recentRecords[&limit=N]

Returns a list of the most recent verified world records submitted to the site. If GET[limit] isn't specified as a number below 50, the 50 latest records are returned.


If GET[format] isn't specified, then a comma-separated list of pretty-printed run descriptions is returned.


GET /api/request?query=streams

Returns a list of the current streams being displayed on the HaloRuns homepage. This list is updated every 5 minutes.


If GET[format] isn't specified, then a comma-separated list of HaloRuns usernames is displayed.


GET /api/request?query=user[&user=username]

Grabs the username, total points, and describes the most recent run submitted by the user specified by GET[user].

Record Vods

GET /api/request?query=wrVods&level=levelID[&difficulty=0&isCoop=0]

Returns a link to the vod of the world record for the level specified by GET[level]. If GET[difficulty] isn't specified, the Easy record is fetched. If GET[isCoop] isn't specified, the Solo record is fetched.

Record Holders

GET /api/request?query=wrHolders

Returns a list of every user on HaloRuns who has ever held a world record at any point.