Bot Statistics

Your bot reports its own numbers, and your listing displays them: “12,482 servers” next to your bot's name, with a last-updated timestamp. Reporting requires a token with the stats:write scope.

Endpoint

POST/bots/:id/stats

:id is your bot's Discord ID, and it must be the bot the token was created for. A token can never report statistics for another listing.

Field	Type	Required	Description
serverCount	integer	yes	How many guilds the bot is in. 0 to 10,000,000.
shardCount	integer	no	Gateway shards, if you shard. 0 to 10,000.

A successful report answers 200 with what was stored:

{
  "serverCount": 12482,
  "shardCount": 12,
  "updatedAt": "2026-08-24T12:00:00.000Z"
}

Each report is a complete snapshot

Every request represents your bot's complete current statistics. Omitting shardCount means “the bot currently has no shard count to report” and clears any previously stored value. It does not mean “keep the previous one”. Always send every value you want shown.

How often to report

Discordium enforces exactly one rule: at most 1 report per minute per bot (a faster report answers 429 and changes nothing). Beyond that, the cadence is yours: on startup and then every 30 minutes is a recommendation, not a requirement. Reporting much more often gains nothing; reporting much less often makes your listing's “last updated” look stale.

Example: periodic reporting

// Report on startup, then every 30 minutes (discord.js).
const INTERVAL = 30 * 60 * 1000;

async function reportStats(client) {
    const res = await fetch("https://api.discordium.org/api/v1/bots/YOUR_BOT_ID/stats", {
        method: "POST",
        headers: {
            Authorization: `Bearer ${process.env.DISCORDIUM_API_TOKEN}`,
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            serverCount: client.guilds.cache.size,
            shardCount: client.ws.shards.size, // leave out if you don't shard
        }),
    });
    if (!res.ok) console.warn("Discordium stats report failed:", res.status);
}

client.once("ready", () => {
    reportStats(client);
    setInterval(() => reportStats(client), INTERVAL);
});

Replace YOUR_BOT_ID with your bot's Discord ID (the Integrations tab shows a snippet with it already filled in).

Errors

Status	Type	Required	Description
400	-	-	A value is outside its range, not an integer, or serverCount is missing.
401	-	-	Missing or invalid token, or the token lacks `stats:write`.
403	-	-	The token belongs to a different bot than the :id in the URL.
404	-	-	No bot with this ID.
429	-	-	More than one report within a minute. The response says when to retry.

See also the API Reference for the full request/response shapes.