Update Bot Stats

Update your bot’s server count and command count on discord.place.

Keep your bot’s listing accurate by periodically pushing your current server and command counts. At least one field must be provided per request.

Endpoint

PATCH /bots/{id}/stats

Authentication: Required — pass your API key in the Authorization header.
See Authentication for details.

Path Parameters

id · string · required

The Discord snowflake ID of your bot (a 17–20 digit numeric string).

Example: 123456789012345678

Request Body

At least one of the following fields must be present.

server_count · integer

The number of servers your bot is currently in. Must be between 0 and 10,000,000.

The value you provide cannot differ from your bot’s actual server count by more than the configured maximum difference (at minimum 50, or 10% of the actual count — whichever is larger). Exceeding this threshold returns a 400 error.

Example: 1500

command_count · integer

The number of slash/prefix commands your bot exposes. Must be between 0 and 1,000.

Example: 100

Code Examples

curl

curl -X PATCH https://api.discord.place/bots/123456789012345678/stats \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_count": 1500, "command_count": 100}'

const response = await fetch('https://api.discord.place/bots/123456789012345678/stats', {
  method: 'PATCH',
  headers: {
    'Authorization': process.env.DISCORD_PLACE_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    server_count: client.guilds.cache.size,
    command_count: client.commands.size
  })
});

const data = await response.json();
if (!data.success) {
  console.error(`Failed to update stats: ${data.error}`);
}

Responses

200 — Success

success · boolean

Always true on a successful update.

{ "success": true }

Error Responses

Show 400 Bad Request

Returned when the request body is invalid.

Missing fields

{
  "success": false,
  "error": "One of the following fields is required: command_count, server_count.",
  "status": 400
}

Invalid server count

{
  "success": false,
  "error": "Server count must be between 0 and 10 Million.",
  "status": 400
}

Invalid command count

{
  "success": false,
  "error": "Commands count must be between 0 and 1,000.",
  "status": 400
}

Server count too far off

{
  "success": false,
  "error": "The server count provided (99999) is too far off from the actual server count. It cannot differ by more than 50 from the actual server count, which is 1500.",
  "status": 400
}

Show 401 Unauthorized

Missing key

{
  "success": false,
  "error": "Authorization header is required.",
  "status": 401
}

Invalid key

{
  "success": false,
  "error": "Invalid API key.",
  "status": 401
}

Show 404 Not Found

{
  "success": false,
  "error": "Bot not found.",
  "status": 404
}

Show 429 Too Many Requests

This endpoint allows 2 requests per 120 minutes. See Rate Limits.

{
  "success": false,
  "error": "Too many requests, please try again later.",
  "status": 429
}

Show 500 Internal Server Error

Returned when the server cannot fetch your bot’s actual guild count to validate server_count.

{
  "success": false,
  "error": "Could not fetch server count.",
  "status": 500
}

Tips

Call this endpoint on a scheduled interval (e.g., every hour) rather than reacting to every guild join/leave event. The rate limit is 2 requests per 120 minutes, so a once-per-hour schedule leaves headroom for retries.