Omniplex Docs

Posting Bot Stats

Keeping your bot's server count and presence up to date.

Your bot should periodically post its stats so its server count, shard count, and presence stay accurate on its listing.

Endpoint

POST /bots/stats

Send an API token for your bot in Authorization, as <token> or Bot <token>. Create one under API sessions in the bot's dashboard (see Authentication). There's no rate limit on this endpoint, so post as often as makes sense for your bot: on every READY or shard reconnect, and periodically after that. Every 15 to 30 minutes is plenty.

Server listings normally don't need to post anything, because Omniplex keeps their member counts up to date itself. See Posting Server Stats if you'd rather report them.

Body

Every field is optional. Only send what you actually have, omitted fields keep whatever value was last posted rather than being reset to zero.

{
  "servers": 1234,
  "shards": 4,
  "users": 56789,
  "shard_list": [0, 1, 2, 3],
  "status": "online"
}
FieldTypeNotes
serversnumberServer count.
shardsnumberShard count.
usersnumberUser count. Not currently shown on the site.
shard_listnumber[]The shard IDs this process handles.
statusstringOne of online, idle, dnd, offline. See below.

Self-reported presence

Most bots don't share a guild with Omniplex's own Discord client, so there's usually no real gateway presence to read for your bot. status lets you report it yourself instead, post it periodically to keep it fresh, it otherwise keeps showing the last value you sent. Post offline when your bot shuts down cleanly.

If you never send status at all, but you do post stats regularly with a nonzero servers count, your bot is still shown as online rather than falling back to an (almost always stale) gateway-derived status, a recent stats post is treated as evidence the bot is actually running.

A status you post is the most reliable signal for your bot's status and uptime, especially for bots that use HTTP interactions and have no presence on Discord.

Using an SDK

Every SDK can post stats once, or keep posting them on an interval (30 minutes by default, at least a minute) while your bot runs:

import { Omniplex } from "@omniplex/sdk";

const omniplex = new Omniplex({ token: process.env.OMNIPLEX_TOKEN });

omniplex.autoPostBotStats(() => ({
  servers: client.guilds.cache.size,
  shards: client.shard?.count ?? 1,
}));

On this page