Guild Count

Report your bot's current guild (server) count to track growth over time. Unlike commands and user events, guild count is sent immediately rather than batched.

Basic Usage

JavaScript / TypeScript

Report guild count

typescript

await cordia.postGuildCount(client.guilds.cache.size);

Python

Report guild count

python

await cordia_client.post_guild_count(len(bot.guilds))

When to Report

You should report your guild count at key moments:

Discord.js

Recommended integration

typescript

// 1. On bot ready
client.on('ready', async () => {
  await cordia.postGuildCount(client.guilds.cache.size);
});

// 2. When bot joins a server
client.on('guildCreate', async () => {
  await cordia.postGuildCount(client.guilds.cache.size);
});

// 3. When bot leaves a server
client.on('guildDelete', async () => {
  await cordia.postGuildCount(client.guilds.cache.size);
});

// 4. Periodically (every 5 minutes)
setInterval(async () => {
  await cordia.postGuildCount(client.guilds.cache.size);
}, 5 * 60 * 1000);

Discord.py

Recommended integration

python

# 1. On bot ready
@bot.event
async def on_ready():
    await cordia_client.post_guild_count(len(bot.guilds))

# 2. When bot joins a server
@bot.event
async def on_guild_join(guild):
    await cordia_client.post_guild_count(len(bot.guilds))

# 3. When bot leaves a server
@bot.event
async def on_guild_remove(guild):
    await cordia_client.post_guild_count(len(bot.guilds))

ℹ️Async Method

postGuildCount() / post_guild_count() is an async method that sends the data immediately. You should await it to wait for confirmation.

API Details

Parameter	Type	Description
`count`	`number / int`	Current number of guilds (must be >= 0)

What's sent to the API

POST /api/v1/guild-count

json

{
  "botId": "your-bot-id",
  "count": 150,
  "timestamp": "2026-04-06T12:00:00.000Z",
  "shardId": 0,
  "totalShards": 4
}

💡Sharded Bots

SDK v1.1.5+ auto-detects shard metadata and reports per-shard counts. Cordia aggregates the latest value from each shard to produce stable totals.

Sharded bot example (JS)

typescript

// For sharded bots using ShardingManager
const results = await client.shard?.fetchClientValues('guilds.cache.size');
const totalGuilds = results?.reduce((a, b) => a + b, 0) ?? 0;

await cordia.postGuildCount(totalGuilds);

Users

Heartbeat & Uptime