Kongregate Developers

Stats & High Scores

Any event in your game can be submitted to Kongregate. Then we can use those to make badges, and display leaderboards.

All statistics must be non-negative integers. So, 0, 42, and 613341 are all fine, but -5 and 1.542 won't work. If you have a carefully timed game that records milliseconds, you'll want to multiply the time by 1000 when submitting to our server. So 1.542 seconds would need to be submitted as 1542 milliseconds. For all you idle games out there, our max value is MAXINT (2,147,483,647), so you may need to take a log of your scores.

Statistics should generally be submitted to the system at the time that they change (like leveling up) or a fairly frequent checkpoints (level/battle completed). Additionally, major stats should be submitted once on each session start. This way if there is an error or glitch during something like a level up a player can refresh the page to force the stat to resubmit.

You can view a flowchart visualizing the statistics submission process here.


In most cases, the best choices for stats to submit are progress-based stats. Things like player level, quests completed, towns captured, matches won, high score on a level, units collected, fastest time on a track, etc. that increase as the player continues in the game. Submit these as numerical stats (i.e. send us the level, not just a "1" when the player hits level 20) and we'll have the most flexibility when working to design badges for your game.

Initialized Statistic

For social/MMO games we recommend submitting a stat to us called "initialized" or "loaded" that sends a "1" each time the game loads successfully. This must be done early, generally at the title screen or no later than character selection/creation (if that happens first thing) - it cannot be post-tutorial or after the first level. We can use this stat to ensure that ratings for the game are by people who meet the game's minimum system requirements. It generally is not as important for Flash games, but if you use an unusual plugin/technology like Unity3D, Java, or HTML5, or are Windows-only, this will help give you a more accurate rating and is strongly recommended. Let us know if you have set up a statistic like this so we can set it up as a filter. This service is currently only available for virtual-goods-enabled games.

Also, as this may modify the game's rating, any games using this service will be excluded from weekly and monthly contests.

Creating your statistics

After you come up with your list of statistics, you need to set them up on the server. This can be done by adding /statistics onto the URL for your game in your browser window. For example: http://www.kongregate.com/games/BenV/my-game/statistics This will take you to the statistics editor page, which can only be viewed by the owner of a game. Note: You can also view the statistics editor on the edit game page.

Give each statistic a name, description, and choose it’s type. You can also select statistics you wish to show up in the leaderboards by checking the "Display in Leaderboards" option.

Once you have created all your statistics on the server, it is time to integrate the API into your game.

Submitting statistics

You can use either the Client or Server API to submit statistics to the server:

Retrieving statistics

Testing statistic submissions

You can see statistic submissions go through in a Javascript console (Chrome, Firebug, etc.) if you add ?debug_level=4 to the game's URL. The exact syntax changes depending on whether you're using client or server stats, but you should see them submit either way.

Getting the most out of the API

If you would like your game to get badges or be part of a challenge, make sure to read these statistics integration tips written by Greg, lead creator of badges/challenges.

next next