Client reference

class topstats.client.Client(token: str, *, session: ClientSession | None = None)

Interact with the API’s endpoints.

Parameters:
Raises:

  • TypeError – The specified token is not a string.

  • ValueError – The specified token is empty.

async close() → None

Closes the Client object. Nothing will happen if the client uses a pre-existing ClientSession or if the session is already closed.

async compare_bot_monthly_votes(period: Period | int | None, *ids: int) → Iterable[tuple[Timestamped, ...]]

Fetches and yields several Discord bots’ historical monthly vote count for a certain period of time.

Parameters:

  • period (Period | int | None) – The requested time period. Defaults to Period.ALL_TIME. If this argument is an int, then it will be treated as a bot ID as a part of the second argument.

  • ids (int) – Set of bot IDs to compare. The API currently only accepts 2 to 4 IDs.

Raises:

  • IndexError – The amount of IDs provided are not within range.

  • Error – The client is already closed.

  • RequestError – One of the specified bots do not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of monthly vote counts to compare.

Return type:

Iterable[tuple[Timestamped, …]]

async compare_bot_review_count(period: Period | int | None, *ids: int) → Iterable[tuple[Timestamped, ...]]

Fetches and yields several Discord bots’ historical review count for a certain period of time.

Parameters:

  • period (Period | int | None) – The requested time period. Defaults to Period.ALL_TIME. If this argument is an int, then it will be treated as a bot ID as a part of the second argument.

  • ids (int) – Set of bot IDs to compare. The API currently only accepts 2 to 4 IDs.

Raises:

  • IndexError – The amount of IDs provided are not within range.

  • Error – The client is already closed.

  • RequestError – One of the specified bots do not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of review counts to compare.

Return type:

Iterable[tuple[Timestamped, …]]

async compare_bot_server_count(period: Period | int | None, *ids: int) → Iterable[tuple[Timestamped, ...]]

Fetches and yields several Discord bots’ historical server count for a certain period of time.

Parameters:

  • period (Period | int | None) – The requested time period. Defaults to Period.ALL_TIME. If this argument is an int, then it will be treated as a bot ID as a part of the second argument.

  • ids (int) – Set of bot IDs to compare. The API currently only accepts 2 to 4 IDs.

Raises:

  • IndexError – The amount of IDs provided are not within range.

  • Error – The client is already closed.

  • RequestError – One of the specified bots do not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of server counts to compare.

Return type:

Iterable[tuple[Timestamped, …]]

async compare_bot_total_votes(period: Period | int | None, *ids: int) → Iterable[tuple[Timestamped, ...]]

Fetches and yields several Discord bots’ historical total vote count for a certain period of time.

Parameters:

  • period (Period | int | None) – The requested time period. Defaults to Period.ALL_TIME. If this argument is an int, then it will be treated as a bot ID as a part of the second argument.

  • ids (int) – Set of bot IDs to compare. The API currently only accepts 2 to 4 IDs.

Raises:

  • IndexError – The amount of IDs provided are not within range.

  • Error – The client is already closed.

  • RequestError – One of the specified bots do not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of total vote counts to compare.

Return type:

Iterable[tuple[Timestamped, …]]

async compare_bots(*ids: int) → Iterable[Bot]

Fetches and yields several Discord bots from a set of IDs.

Parameters:

ids (int) – Set of bot IDs to compare. The API currently only accepts 2 to 4 IDs.

Raises:

  • IndexError – The amount of IDs provided are not within range.

  • Error – The client is already closed.

  • RequestError – One of the specified bots do not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of bots to compare.

Return type:

Iterable[Bot]

async get_bot(id: int) → Bot

Fetches a Discord bot from its ID.

Parameters:

id (int) – The requested bot’s ID.

Raises:

  • Error – The client is already closed.

  • RequestError – The specified bot does not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested bot.

Return type:

Bot

async get_historical_bot_monthly_votes(id: int, period: Period | None = None) → Iterable[Timestamped]

Fetches and yields a Discord bot’s historical monthly vote count for a certain period of time.

Parameters:
Raises:

  • Error – The client is already closed.

  • RequestError – The specified bot does not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of this bot’s monthly vote counts.

Return type:

Iterable[Timestamped]

async get_historical_bot_review_count(id: int, period: Period | None = None) → Iterable[Timestamped]

Fetches and yields a Discord bot’s historical review count for a certain period of time.

Parameters:
Raises:

  • Error – The client is already closed.

  • RequestError – The specified bot does not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of this bot’s review counts.

Return type:

Iterable[Timestamped]

async get_historical_bot_server_count(id: int, period: Period | None = None) → Iterable[Timestamped]

Fetches and yields a Discord bot’s historical server count for a certain period of time.

Parameters:
Raises:

  • Error – The client is already closed.

  • RequestError – The specified bot does not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of this bot’s server counts.

Return type:

Iterable[Timestamped]

async get_historical_bot_total_votes(id: int, period: Period | None = None) → Iterable[Timestamped]

Fetches and yields a Discord bot’s historical total vote count for a certain period of time.

Parameters:
Raises:

  • Error – The client is already closed.

  • RequestError – The specified bot does not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of this bot’s total vote counts.

Return type:

Iterable[Timestamped]

async get_recent_bot_stats(id: int) → RecentBotStats

Fetches recent stats of a Discord bot for the past 30 hours and past month.

Parameters:

id (int) – The requested bot’s ID.

Raises:

  • Error – The client is already closed.

  • RequestError – The client received a non-favorable response from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested recent bot stats for the past 30 hours and past month.

Return type:

RecentBotStats

async get_top_bots(sort_by: SortBy, *, limit: int | None = None) → Iterable[PartialBot]

Fetches and yields top Discord bots based on a certain criteria.

Parameters:

  • sort_by (SortBy) – The requested criteria and sorting method.

  • limit (int | None) – Limit of data to be returned. Defaults to 100. This can’t exceed 100.

Raises:

  • TypeError – The requested sorting criteria’s type is invalid.

  • Error – The client is already closed.

  • RequestError – The client received a non-favorable response from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of top bots based on the requested criteria.

Return type:

Iterable[PartialBot]

async get_users_bot(id: int) → Iterable[Bot]

Fetches a Discord user’s Discord bots from their ID.

Warning:

Data returned by this method may be inaccurate! This is because bots moved to a team will remain on a user’s account irrespective of ownership.

Parameters:

id (int) – The requested user’s ID.

Raises:

  • Error – The client is already closed.

  • RequestError – The specified user has not logged in to Top.gg or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of bots made by this user.

Return type:

Iterable[Bot]

async search_bots(*, name: str | None = None, tag: str | None = None, offset: int | None = None, limit: int | None = None, include_deleted: bool = False) → Iterable[Bot]

Fetches and yields several Discord bots from their name or tag.

Parameters:

  • name (str | None) – The requested bot name. If None, defaults to the tag parameter.

  • tag (str | None) – The requested bot tag. If None, defaults to the name parameter.

  • offset (int | None) – The amount of bots to be skipped.

  • limit (int | None) – The maximum amount of bots to be queried. Defaults to 50 or 100 depending on the parameter. This can’t exceed the default value.

  • include_deleted (bool) – Whether to include deleted bots or not. Defaults to False.

Raises:

  • Error – The client is already closed or both the name and tag parameters are unspecified.

  • RequestError – The specified bot does not exist or the client has received other non-favorable responses from the API.

  • Ratelimited – Ratelimited from sending more requests.

Returns:

The requested list of bots that matches the specified query.

Return type:

Iterable[Bot]

class topstats.data.Period

The requested time period for fetching historical bot stats.

ALL_TIME = 'alltime'
LAST_12_HOURS = '12h'
LAST_3_DAYS = '3d'
LAST_3_MONTHS = '90d'
LAST_3_YEARS = '3y'
LAST_5_YEARS = '5y'
LAST_6_HOURS = '6h'
LAST_6_MONTHS = '180d'
LAST_9_MONTHS = '270d'
LAST_DAY = '1d'
LAST_MONTH = '30d'
LAST_WEEK = '7d'
LAST_YEAR = '1y'
class topstats.data.SortBy

The requested sorting method for sorting Discord bots.

static monthly_votes(*, ascending: bool = False) → SortBy

Sorts Discord bots by their monthly vote count.

Parameters:

ascending (bool) – Whether to sort by ascending or not. Defaults to sort by descending.

static review_count(*, ascending: bool = False) → SortBy

Sorts Discord bots by their review count.

Parameters:

ascending (bool) – Whether to sort by ascending or not. Defaults to sort by descending.

static server_count(*, ascending: bool = False) → SortBy

Sorts Discord bots by their server count.

Parameters:

ascending (bool) – Whether to sort by ascending or not. Defaults to sort by descending.

static total_votes(*, ascending: bool = False) → SortBy

Sorts Discord bots by their total vote count.

Parameters:

ascending (bool) – Whether to sort by ascending or not. Defaults to sort by descending.

class topstats.errors.Error

The base error class. Extends Exception.

class topstats.errors.RequestError

Thrown upon HTTP request failure. Extends Error.

message: str | None

The message returned from the API.

status: int | None

The status code returned from the API.

class topstats.errors.Ratelimited

Thrown upon HTTP request failure due to the client being ratelimited. Because of this, the client is not allowed to make requests for a period of time. Extends Error.

retry_after: float

How long the client should wait (in seconds) until it can make a request to the API again.