Core Concepts
Posting stats
postStats, postStatsTo, postViaBotBlock and auto posting.
// every list you have a token for
const report = await lists.postStats({ serverCount: 120 });
report.posted; // 4
report.failed; // 0
report.skipped; // lists without tokens
// shard aware posting
await lists.postStats({
serverCount: client.guilds.cache.size,
shardCount: client.shard?.count,
shards: await client.shard?.fetchClientValues('guilds.cache.size') as number[],
});
// only some lists, or skip some
await lists.postStats({ serverCount: 120 }, { only: ['top.gg', 'botlist.me'] });
await lists.postStats({ serverCount: 120 }, { skip: ['bots.ondiscord.xyz'] });
// one specific list
await lists.postStatsTo('radarcord', { serverCount: 120 });
// one request, botblock fans out to every list for you
await lists.postViaBotBlock({ serverCount: 120 });Wire format mapping
Every list names the server count differently. The registry stores the exact field per list and builds the correct body automatically:
| List | Body field | Auth header |
|---|---|---|
top.gg | server_count | Authorization |
discord.bots.gg | guildCount | Authorization |
discordbotlist.com | guilds | Authorization |
botlist.me | server_count | authorization |
disforge.com | servers | Authorization |
discordlist.gg | count | Authorization |
discord.rovelstars.com | count | authorization |
auto posting on an interval
lists.startAutoPost(30 * 60 * 1000); // every 30 minutes, minimum 60s
lists.stopAutoPost();NoteBotBlock allows one successful request per 120 seconds. postViaBotBlock never retries inside that window; the SDK reports the 429 with retryAfter instead.