Skip to main content
The bot endpoints let you search the Top.gg bot directory, retrieve details for a specific bot, check vote history, and post server count statistics. All bot endpoints require a valid Top.gg token and are subject to a rate limit of 60 requests per minute.
Bot endpoints have stricter rate limits than other v0 endpoints. Stay within 60 requests per minute to avoid 429 Too Many Requests errors.

​
GET /bots

Searches the Top.gg bot directory with optional filtering, sorting, and pagination. 
curl "https://top.gg/api/bots?limit=10&sort=-points" \
  -H "Authorization: your-topgg-token-here"

​
Query parameters

​
limit
number
default:"50"
Number of bots to return. Maximum 500.
​
offset
number
default:"0"
Number of bots to skip before returning results. Use with limit for pagination.
​
sort
string
Field to sort results by. Prefix with - to sort in descending order (e.g., -points).
​
fields
string
Comma-separated list of Bot fields to include in the response. Defaults to all fields.

​
Response fields

​
results
object[]
required
Array of Bot objects matching the query.
​
limit
number
required
The limit value used for this request.
​
offset
number
required
The offset value used for this request.
​
count
number
required
Number of results returned in this response.
​
total
number
required
Total number of bots matching the search query.

​
GET /bots/:bot_id

Returns a single Bot object by its Discord application ID. Returns 404 Not Found if no bot with that ID is listed on Top.gg. 
curl https://top.gg/api/bots/264811613708746752 \
  -H "Authorization: your-topgg-token-here"
See the Bot structure section below for the full list of fields.

​
GET /bots/:bot_id/votes

Returns the last 1000 unique voters for the specified bot. Each entry includes the voter’s username, Discord user ID, and avatar hash. 
curl https://top.gg/api/bots/264811613708746752/votes \
  -H "Authorization: your-topgg-token-here"

​
Response

Returns an array of voter objects:
​
username
string
required
The voter’s Discord username.
​
id
string
required
The voter’s Discord Snowflake ID.
​
avatar
string
required
The voter’s Discord avatar hash.
This endpoint returns only the last 1,000 unique voters and does not include double votes or weekend bonus votes. If your bot receives more than 1,000 votes per month, you must use webhooks and maintain your own vote cache instead of relying on this endpoint.

​
GET /bots/:bot_id/stats

Returns server and shard statistics for the specified bot. 
curl https://top.gg/api/bots/264811613708746752/stats \
  -H "Authorization: your-topgg-token-here"

​
Response fields

​
server_count
number
Total number of servers the bot is in. May be absent if not posted.
​
shards
number[]
required
Array of server counts per shard.
​
shard_count
number
Total number of shards. May be absent if not posted.

​
GET /bots/:bot_id/check

Checks whether a specific user has an active vote for the bot. Safe to call even if your bot has more than 1,000 monthly votes. 
curl "https://top.gg/api/bots/264811613708746752/check?userId=129908908096487424" \
  -H "Authorization: your-topgg-token-here"

​
Query parameters

​
userId
string
required
The Discord Snowflake ID of the user to check.

​
Response

{ "voted": 1 }
A voted value of 1 means the user has voted in the past 12 hours. A value of 0 means they have not.

​
POST /bots/:bot_id/stats

Posts updated server count statistics for the specified bot. Call this endpoint whenever your bot’s server count changes, for example when it joins or leaves a guild. 
curl -X POST https://top.gg/api/bots/264811613708746752/stats \
  -H "Authorization: your-topgg-token-here" \
  -H "Content-Type: application/json" \
  -d '{ "server_count": 2 }'

​
Request body

​
server_count
number | number[]
required
The number of servers your bot is in. Pass an array to post per-shard counts (equivalent to using the shards field).
​
shards
number[]
An array of server counts, one entry per shard.
​
shard_id
number
The zero-indexed ID of the shard posting stats. Used when posting per-shard updates.
​
shard_count
number
The total number of shards your bot is running.

​
Response

Returns 200 OK with an empty body on success.

​
Bot structure

Every bot endpoint that returns a Bot object uses the following structure:
FieldTypeDescription
idstringDiscord application Snowflake ID
usernamestringBot username
discriminatorstringBot discriminator
avatarstring?Avatar hash (null if no custom avatar)
defAvatarstring?Default CDN avatar hash
libstringLibrary the bot is built with
prefixstringBot command prefix
shortdescstringShort description shown on listings
longdescstring?Full description (may contain Markdown or HTML)
tagsstring[]List of category tags
websitestring?Bot’s website URL
supportstring?Support server invite code
githubstring?GitHub repository URL
ownersstring[]Snowflake IDs of the bot’s owners
guildsstring[]Snowflake IDs of featured guilds
invitestring?Custom invite URL
datestringISO 8601 date the bot was added to Top.gg
server_countnumber?Current server count (if posted)
shard_countnumber?Current shard count (if posted)
certifiedBotbooleanWhether the bot is Top.gg certified
vanitystring?Vanity URL slug
pointsnumberAll-time vote count
monthlyPointsnumberVote count for the current month
donatebotguildidstringGuild ID for Donatebot integration (empty if unused)

​
Example bot object

{
  "id": "264811613708746752",
  "username": "Luca",
  "discriminator": "1375",
  "avatar": "7edcc4c6fbb0b23762455ca139f0e1c9",
  "defAvatar": "6debd47ed13483642cf09e832ed0bc1b",
  "prefix": "- or @Luca#1375",
  "shortdesc": "Luca is a bot for managing and informing members of the server",
  "longdesc": "Luca only works in the Discord Bot List server.",
  "tags": ["Moderation", "Role Management", "Logging"],
  "owners": ["129908908096487424"],
  "guilds": ["417723229721853963", "264445053596991498"],
  "date": "2017-04-26T18:08:17.125Z",
  "server_count": 2,
  "shard_count": 1,
  "certifiedBot": false,
  "points": 397,
  "monthlyPoints": 19,
  "donatebotguildid": ""
}