BotBlock API

A single POST to send your bot's guild count

curl -X POST https://botblock.org/api/count \ -H 'Content-Type: text/json' \ --data-raw ' { "server_count": 10000, "bot_id": "123456789123456789", "discordbotlist.com": "abcDEFghi.JKLmnoPQR.stuVWXyz1", "discord.bots.gg": "abcDEFghi.JKLmnoPQR.stuVWXyz1" }'

Update guild count

POST /api/count

The POST /api/count endpoint of the BotBlock API is the core endpoint that bots and libraries integrate with, allowing a bot to make a single POST call to send their guild count to all supported lists, based on the API keys passed for lists.

Note: This ratelimit has a 1 / 120s ratelimit for successful requests. Requests that return a 400 or 429 status code are not ratelimited.

Request body (required)

application/json

Schema

object
server_count integer

The server/guild count for the bot.

Note: Value is required but will not be sent to a list if ‘shards’ is provided and the list accepts a ‘shards’ value.

bot_id string<snowflake>

The ID of the bot.

shard_id integer

Nullable: true

The shard ID for the current count being posted.

Note: This information is only sent to bot lists that support it.

shard_count integer

Nullable: true

The total number of shards for the bot.

Note: This information is only sent to bot lists that support it.

shards array

Nullable: true

The server/guild count for each shard.

Note: This information is only sent to bot lists that support it.

[*] integer
<*> string

Provide keys for each list ID to post to, with the value being the API key for the list.

Examples

{ "server_count": 10000, "bot_id": "123456789123456789", "thelist.org": "abcDEFghi.JKLmnoPQR.stuVWXyz1", "listofbots.com": "abcDEFghi.JKLmnoPQR.stuVWXyz1", "otherlist.xyz": "abcDEFghi.JKLmnoPQR.stuVWXyz1" }

Responses

200

Guild count forwarded to provided lists.

application/json

Schema
object
success object

Properties for each list that returned a successful response.

<*> array

Min items: 3

Max items: 3

[*]

Integer response status code from list, followed by string response from list, followed by JSON stringified data sent to list.

One of:

- string
- integer
failure object

Properties for each list that returned a failure response.

<*> array

Min items: 3

Max items: 3

[*]

Integer response status code from list, followed by string response from list, followed by JSON stringified data sent to list.

One of:

- string
- integer
Examples
{ "success": { "thelist.org": [ 200, "{\"message\":\"OK\"}", "{\"server_count\":10000}" ], "listofbots.com": [ 200, "", "{\"count\":10000}" ] }, "failure": { "otherlist.xyz": [ 404, "Bot not found", "{\"guilds\":10000}" ] } }

400

Request validation failed.

application/json

Schema
object
error boolean

[ true ]

status integer

[ 400 ]

message string

An error message explaining why request validation failed.

Examples
{ "error": true, "status": 400, "message": "'bot_id' must be a snowflake" }

429

Request ratelimited.

application/json

Schema
object
error boolean

[ true ]

status integer

[ 429 ]

retry_after integer

How many seconds until the API can be used again.

ratelimit_reset integer

The unix timestamp when the API can be used again.

ratelimit_method string

Ratelimit scope - the HTTP method.

ratelimit_route string

Ratelimit scope - the API route.

ratelimit_ip string

Ratelimit scope - the requesting IP address.

ratelimit_bot_id string

Ratelimit scope - the provided bot ID.

Examples
{ "error": true, "status": 429, "retry_after": 80, "ratelimit_reset": 1609459320, "ratelimit_method": "GET", "ratelimit_route": "/api/path/name", "ratelimit_ip": "12.45.67.89", "ratelimit_bot_id": "123456789123456789" }
Headers
Retry-After integer

How many seconds until the API can be used again.

X-Rate-Limit-Reset integer

The unix timestamp when the API can be used again.

X-Rate-Limit-Method string

Ratelimit scope - the HTTP method.

X-Rate-Limit-Route string

Ratelimit scope - the API route.

X-Rate-Limit-IP string

Ratelimit scope - the requesting IP address.

X-Rate-Limit-Bot-ID string

Ratelimit scope - the provided bot ID.

API Libraries

Interact with the BotBlock API through libraries built for Discord bots.

Save time and get started with the BotBlock API faster by using one of our pre-built libraries, designed with Discord bots in mind.

Explore libraries

Get bot information

GET /api/bots/{id}

Fetch aggregated information about a Discord bot based on data returned by bot lists that BotBlock tracks that support getting bot information.

Note: This ratelimit has a 1 / 30s ratelimit for successful requests. Requests that return a 400 or 429 status code are not ratelimited.

Path Parameters

id string<snowflake>

Discord bot ID to fetch

Responses

200

Guild count forwarded to provided lists.

application/json

Schema
object
id string<snowflake>

The ID of the bot being fetched.

username string

The username of the bot fetched.

Note: Based on the most common value returned from list data, defaults to Unknown.

discriminator string

The discriminator of the bot fetched.

Note: Based on the most common value returned from list data, defaults to 0000.

owners array

The IDs of all known owners of the bot.

[*] string<snowflake>
server_count integer

The server/guild count for the bot.

Note: Based on the maximum value returned from list data, defaults to 0.

invite string

The invite URL for the bot (Discord or custom), if known.

Note: Based on the most common value returned from list data, defaults to an empty string.

prefix string

The command prefix for the bot, if known.

Note: Based on the most common value returned from list data, defaults to an empty string.

website string

The website link for the bot, if known.

Note: Based on the most common value returned from list data, defaults to an empty string.

github string

The open-source GitHub URL for the bot, if known.

Note: Based on the most common value returned from list data, defaults to an empty string.

support string

The support link for the bot (Discord or custom), if known.

Note: Based on the most common value returned from list data, defaults to an empty string.

library string

The library/language the bot was developed in, if known.

Note: Based on the most common value returned from list data, defaults to an empty string.

list_data object

Response from each BotBlock-tracked list that has a endpoint for fetching bot information.

<*> array

Min items: 2

Max items: 2

[*]

Data response from the list (parsed JSON, or raw text respose), followed by the integer response status code.

One of:

- Any

Can be any JSON-able value - string, number, boolean, array or object.

- integer
Examples
{ "id": "123456789123456789", "username": "My Bot", "discriminator": "1234", "owners": [ "123456789123456789" ], "server_count": 10000, "invite": "https://discord.com/oauth2/authorize?client_id=123456789123456789&scope=bot", "prefix": "!", "website": "https://my-bot.com/", "github": "https://github.com/hello/my-bot", "support": "https://discord.gg/discord-developers", "library": "discord.js", "list_data": { "thelist.org": [ { "bot_id": "123456789123456789", "...": "..." }, 200 ], "listofbots.com": [ { "bot": { "id": "123456789123456789", "guilds": 10000, "...": "..." } }, 200 ], "otherlist.xyz": [ "Bot not found", 404 ] } }

400

Request validation failed.

application/json

Schema
object
error boolean

[ true ]

status integer

[ 400 ]

message string

An error message explaining why request validation failed.

Examples
{ "error": true, "status": 400, "message": "'id' must be a snowflake" }

429

Request ratelimited.

application/json

Schema
object
error boolean

[ true ]

status integer

[ 429 ]

retry_after integer

How many seconds until the API can be used again.

ratelimit_reset integer

The unix timestamp when the API can be used again.

ratelimit_method string

Ratelimit scope - the HTTP method.

ratelimit_route string

Ratelimit scope - the API route.

ratelimit_ip string

Ratelimit scope - the requesting IP address.

ratelimit_bot_id string

Ratelimit scope - the provided bot ID.

Examples
{ "error": true, "status": 429, "retry_after": 80, "ratelimit_reset": 1609459320, "ratelimit_method": "GET", "ratelimit_route": "/api/path/name", "ratelimit_ip": "12.45.67.89", "ratelimit_bot_id": "123456789123456789" }
Headers
Retry-After integer

How many seconds until the API can be used again.

X-Rate-Limit-Reset integer

The unix timestamp when the API can be used again.

X-Rate-Limit-Method string

Ratelimit scope - the HTTP method.

X-Rate-Limit-Route string

Ratelimit scope - the API route.

X-Rate-Limit-IP string

Ratelimit scope - the requesting IP address.

X-Rate-Limit-Bot-ID string

Ratelimit scope - the provided bot ID.

Get all known bot lists

GET /api/lists

Fetch information about all bot lists that BotBlock tracks, including core information as well as API details and known features.

Query Parameters

filter boolean

Set to true to only return API information for each lists. Lists with no API data will be excluded from the response.

Responses

200

Lists tracked by BotBlock.

application/json

Schema
object

Properties for each list.

<*> object
id string

The ID of the list on BotBlock.

added integer

The unix timestamp for when the list was added to BotBlock.

name string

The displayed name of the list.

url string<uri>

The main URL to access the bot list.

icon string<uri>

A URL for an icon for the list.

language string

The languages the list has support for.

display integer

[ 0, 1 ]

A flag for if the list is displayed on BotBlock, with 0 = hidden, 1 = displayed.

defunct integer

[ 0, 1 ]

A flag for if the list is known to be defunct, with 0 = active, 1 = defunct.

discord_only integer

[ 0, 1 ]

A flag for if the list holds Discord bots only, with 0 = includes non-Discord, 1 = Discord-only.

description string

The displayed description of the list.

api_docs string<uri>

Nullable: true

The URL to the API docs for the list, if known.

api_post string<uri>

Nullable: true

The endpoint URL for posting a bot’s guild count to the list, if known, with :id as placeholder for bot Id.

api_post_method string

Nullable: true

The HTTP method to use for submitting a bot’s guild count to the list via api_post. Defaults to POST if null.

api_field string

Nullable: true

The field name for guild count when posting a bot’s guild count to the list, if known.

api_shard_id string

Nullable: true

The field name for shard Id when posting a bot’s guild count to the list, if known.

api_shard_count string

Nullable: true

The field name for shard count when posting a bot’s guild count to the list, if known.

api_shards string

Nullable: true

The field name for shards when posting a bot’s guild count to the list, if known.

api_get string<uri>

Nullable: true

The endpoint URL for getting a bot from the list, if known, with :id as placeholder for bot Id.

api_all string<uri>

Nullable: true

The endpoint URL for getting all bots from the list, if known.

view_bot string<uri>

Nullable: true

The URL to the view a bot on the list, if known, with :id as placeholder for bot Id.

bot_widget string<uri>

Nullable: true

The URL to get a bot widget from the list, if known, with :id as placeholder for bot Id.

content string

Nullable: true

The displayed notice content for the list, if any.

owners string

Nullable: true

Names of the list owners, if known.

discord string<uri>

Nullable: true

The URL invite for the list’s Discord server, if known.

features array

A list of features that the list has

[*]

All of:

- object
name string

The displayed name of the feature.

id string

The sluggified name of the feature.

display integer

A value used to rank features. Sorted in descending order.

type integer

[ 0, 1, 2 ]

The type the feature is, with 0 = positive, 1 = neutral, 2 = negative.

description string

The displayed description of the feature.

- object
value integer

[ 0, 1 ]

A flag for if the list is known to have this feature or not, with 0 = does not have feature, 1 = has feature.

Examples
{ "thelist.org": { "id": "thelist.org", "added": 1609459200, "name": "The List", "url": "https://thelist.org/", "icon": "https://thelist.org/favicon.png", "language": "English", "display": 1, "defunct": 0, "discord_only": 1, "description": "The List", "api_docs": "https://thelist.org/api/docs", "api_post": "https://thelist.org/api/bot/:id", "api_post_method": null, "api_field": "server_count", "api_shard_id": "shard_id", "api_shard_count": "shard_count", "api_shards": null, "api_get": "https://thelist.org/api/bot/:id", "api_all": null, "view_bot": "https://thelist.org/bot/:id", "bot_widget": "https://thelist.org/bot/:id/widget", "content": null, "owners": "123456789123456789", "discord": "https://discord.gg/discord-developers", "features": [ { "name": "Guild count API", "id": "guild-count-api", "display": 5, "type": 0, "description": "Has an API endpoint for guild count", "value": 1 } ] }, "listofbots.com": { "id": "listofbots.com", "added": 1609459200, "name": "List of Bots", "url": "https://listofbots.com/", "icon": "https://listofbots.com/assets/icon.png", "language": "English", "display": 1, "defunct": 0, "discord_only": 0, "description": "List of Bots for chat platforms", "api_docs": null, "api_post": null, "api_field": null, "api_shard_id": null, "api_shard_count": null, "api_shards": null, "api_get": null, "api_all": null, "view_bot": "https://listofbots.com/bots/:id", "bot_widget": null, "content": null, "owners": "123456789123456789", "discord": "https://discord.gg/discord-developers", "features": [ { "name": "Guild count API", "id": "guild-count-api", "display": 5, "type": 0, "description": "Has an API endpoint for guild count", "value": 0 } ] } }

Get a specific bot list

GET /api/lists/{id}

Fetch information about a given bot lists that BotBlock tracks, including core information as well as API details and known features.

Path Parameters

id string

ID of the list on BotBlock to fetch.

Responses

200

Requested list on BotBlock.

application/json

Schema
object
id string

The ID of the list on BotBlock.

added integer

The unix timestamp for when the list was added to BotBlock.

name string

The displayed name of the list.

url string<uri>

The main URL to access the bot list.

icon string<uri>

A URL for an icon for the list.

language string

The languages the list has support for.

display integer

[ 0, 1 ]

A flag for if the list is displayed on BotBlock, with 0 = hidden, 1 = displayed.

defunct integer

[ 0, 1 ]

A flag for if the list is known to be defunct, with 0 = active, 1 = defunct.

discord_only integer

[ 0, 1 ]

A flag for if the list holds Discord bots only, with 0 = includes non-Discord, 1 = Discord-only.

description string

The displayed description of the list.

api_docs string<uri>

Nullable: true

The URL to the API docs for the list, if known.

api_post string<uri>

Nullable: true

The endpoint URL for posting a bot’s guild count to the list, if known, with :id as placeholder for bot Id.

api_post_method string

Nullable: true

The HTTP method to use for submitting a bot’s guild count to the list via api_post. Defaults to POST if null.

api_field string

Nullable: true

The field name for guild count when posting a bot’s guild count to the list, if known.

api_shard_id string

Nullable: true

The field name for shard Id when posting a bot’s guild count to the list, if known.

api_shard_count string

Nullable: true

The field name for shard count when posting a bot’s guild count to the list, if known.

api_shards string

Nullable: true

The field name for shards when posting a bot’s guild count to the list, if known.

api_get string<uri>

Nullable: true

The endpoint URL for getting a bot from the list, if known, with :id as placeholder for bot Id.

api_all string<uri>

Nullable: true

The endpoint URL for getting all bots from the list, if known.

view_bot string<uri>

Nullable: true

The URL to the view a bot on the list, if known, with :id as placeholder for bot Id.

bot_widget string<uri>

Nullable: true

The URL to get a bot widget from the list, if known, with :id as placeholder for bot Id.

content string

Nullable: true

The displayed notice content for the list, if any.

owners string

Nullable: true

Names of the list owners, if known.

discord string<uri>

Nullable: true

The URL invite for the list’s Discord server, if known.

features array

A list of features that the list has

[*]

All of:

- object
name string

The displayed name of the feature.

id string

The sluggified name of the feature.

display integer

A value used to rank features. Sorted in descending order.

type integer

[ 0, 1, 2 ]

The type the feature is, with 0 = positive, 1 = neutral, 2 = negative.

description string

The displayed description of the feature.

- object
value integer

[ 0, 1 ]

A flag for if the list is known to have this feature or not, with 0 = does not have feature, 1 = has feature.

Examples
{ "id": "thelist.org", "added": 1609459200, "name": "The List", "url": "https://thelist.org/", "icon": "https://thelist.org/favicon.png", "language": "English", "display": 1, "defunct": 0, "discord_only": 1, "description": "The List", "api_docs": "https://thelist.org/api/docs", "api_post": "https://thelist.org/api/bot/:id", "api_post_method": null, "api_field": "server_count", "api_shard_id": "shard_id", "api_shard_count": "shard_count", "api_shards": null, "api_get": "https://thelist.org/api/bot/:id", "api_all": null, "view_bot": "https://thelist.org/bot/:id", "bot_widget": "https://thelist.org/bot/:id/widget", "content": null, "owners": "123456789123456789", "discord": "https://discord.gg/discord-developers", "features": [ { "name": "Guild count API", "id": "guild-count-api", "display": 5, "type": 0, "description": "Has an API endpoint for guild count", "value": 1 } ] }

404

Requested list not found.

application/json

Schema
object
error boolean

[ true ]

status integer

[ 404 ]

message string

An error message explaining the list wasn’t found.

Examples
{ "error": true, "status": 404, "message": "List not found" }

Get legacy list IDs

GET /api/legacy-ids

Fetch the map of legacy bot list IDs to the current list IDs.

Responses

200

Map of old IDs to new IDs.

application/json

Schema
object

Object mapping legacy IDs as keys to current list IDs as values.

<*> string
Examples
{ "oldlist.com": "thelist.org", "botlist.xyz": "botlist.com" }

© 2025 BotBlock