Bot Statistics

If you're a bot owner, you might want to POST some stats to here. Here are few reasons why:

  • Based on the optional statistics you post, we might use that in the future promote your bot to more users
  • GuildsCountMasterRaceā„¢
  • Stats are fun!

To get started, you first need a bot token. Go to your bot's page, and click 'Generate Token', this will create a 64 bytes token. This token has few characteristics:

  • It doesn't expire just because the clock is moving
  • You can only have one token for a given bot
  • Once you navigate away off the page the token disappears forever. So save it somewhere safe
  • You can invalidate the token by generating a new token

Once you have the token, you can authenticate your request by adding Authorization: Bot <token> to your request.

Soooo once you get authentication done right, you can POST to /api/bots/:bot_id/stats the following:

  • shard_id - Zero-indexed shard ID. OPTIONAL!!! (stop telling me 'I don't use sharding')
  • guilds - Number of guilds (int)
  • users - Number of users (int)
  • voice_connections - Number of voice connections (int)

All these fields are optional. You can just POST nothing to the end-point, that would probably reset the stats for shard 0 or whatever

The server will respond with status code 204 and will combine stats interally for each shard.

You should know that if you provide inconsistent data, stats may not show up at all. For example if you provide guilds for shard 5 and not for shard 4, the guilds count won't show up at all. You must provide consistent data in order for stats to show up. If you don't use sharding ignore this.

In case you mess things up, we provided implemented a DELETE operation on the same end-point URL for wiping out all the stats for all shards for that bot.


You can embed a nice widget to your website by appending /widget to your bot URL to get an SVG, something like this:

<a href="">
		alt="Lithium stats on Discord Bot List">

...which looks like this:

Lithium stats on Discord Bot List

Bot verification

If you want your bot to have a fancy golden star that assures the user the bot is not spam, then contact us thru Discord.

Upvote Webhooks

Upvote webhooks are webhooks that are fired whenever a user upvotes your bot. Configuring it requires:

  • A webhook URL. A URL that we will POST to.
  • A webhook secret. Used to verify the webhook at your end.
Whenever the webhook is triggered, it will POST to the specified URL a user object. It will also include a custom X-DBL-Signature HTTP header. The header will contain two fields:
  • The first field is the secret that you provided when setting up the webhook
  • The second one is the number of milliseconds since epoch
To verify webhook, first check the secret. If it's correct, check the provided timestamp, if it's within something like 2 minutes, accept it, otherwise, reject it.
The timestamp verification is important in order to prevent replay attacks.