Mod log

Mod log has now been separated from Mod for V3.

Basic Usage

from redbot.core import commands, modlog
import discord

class MyCog(commands.Cog):
    async def ban(self, ctx, user: discord.Member, reason: str = None):
        await ctx.guild.ban(user)
        case = await modlog.create_case(
  , ctx.guild, ctx.message.created_at, action_type="ban",
            user=user,, reason=reason
        await ctx.send("Done. It was about time.")

Registering Case types

To register case types, use an asynchronous initialize() method and call it from your setup function:

# mycog/
from redbot.core import modlog, commands
import discord

class MyCog(commands.Cog):

    async def initialize(self):
        await self.register_casetypes()

    async def register_casetypes():
        # Registering a single casetype
        ban_case = {
            "name": "ban",
            "default_setting": True,
            "image": "\N{HAMMER}",
            "case_str": "Ban",
            await modlog.register_casetype(**ban_case)
        except RuntimeError:

        # Registering multiple casetypes
        new_types = [
                "name": "hackban",
                "default_setting": True,
                "image": "\N{BUST IN SILHOUETTE}\N{HAMMER}",
                "case_str": "Hackban",
                "name": "kick",
                "default_setting": True,
                "image": "\N{WOMANS BOOTS}",
                "case_str": "Kick",
        await modlog.register_casetypes(new_types)
# mycog/
from .mycog import MyCog

async def setup(bot):
    cog = MyCog()
    await cog.initialize()


Image should be the emoji you want to represent your case type with.

API Reference

Mod log

class redbot.core.modlog.Case(bot, guild, created_at, action_type, user, moderator, case_number, reason=None, until=None, channel=None, amended_by=None, modified_at=None, message=None)[source]

Bases: object

A single mod log case

await edit(data)[source]

Edits a case

Parameters:data (dict) – The attributes to change
classmethod await from_json(mod_channel, bot, case_number, data, **kwargs)[source]

Get a Case object from the provided information

  • mod_channel (discord.TextChannel) – The mod log channel for the guild
  • bot (Red) – The bot’s instance. Needed to get the target user
  • case_number (int) – The case’s number.
  • data (dict) – The JSON representation of the case to be gotten
  • **kwargs – Extra attributes for the Case instance which override values in the data dict. These should be complete objects and not IDs, where possible.

The case object for the requested case

Return type:


await message_content(embed=True)[source]

Format a case message

Parameters:embed (bool) – Whether or not to get an embed
Returns:A rich embed or string representing a case message
Return type:discord.Embed or str

Transform the object to a dict

Returns:The case in the form of a dict
Return type:dict
class redbot.core.modlog.CaseType(name, default_setting, image, case_str, guild=None, **kwargs)[source]

Bases: object

A single case type


The name of the case


Whether the case type should be on (if True) or off (if False) by default


The emoji to use for the case type (for example, :boot:)


The string representation of the case (example: Ban)

classmethod from_json(name, data, **kwargs)[source]
  • name (str) – The casetype’s name.
  • data (dict) – The JSON data to create an instance from
  • **kwargs – Values for other attributes of the instance

The case type object created from given data.

Return type:


await is_enabled()[source]

Determines if the case is enabled. If the guild is not set, this will always return False

Returns:True if the guild is set and the casetype is enabled for the guild

False if the guild is not set or if the guild is set and the type is disabled

Return type:bool
await set_enabled(enabled)[source]

Sets the case as enabled or disabled

Parameters:enabled (bool) – True if the case should be enabled, otherwise False
await to_json()[source]

Transforms the case type into a dict and saves it

await redbot.core.modlog.get_case(case_number, guild, bot)[source]

Gets the case with the associated case number

  • case_number (int) – The case number for the case to get
  • guild (discord.Guild) – The guild to get the case from
  • bot (Red) – The bot’s instance

The case associated with the case number

Return type:



RuntimeError – If there is no case for the specified number

await redbot.core.modlog.get_all_cases(guild, bot)[source]

Gets all cases for the specified guild

  • guild (discord.Guild) – The guild to get the cases from
  • bot (Red) – The bot’s instance

A list of all cases for the guild

Return type:


await redbot.core.modlog.get_cases_for_member(guild, bot, *, member=None, member_id=None)[source]

Gets all cases for the specified member or member id in a guild.

  • guild (discord.Guild) – The guild to get the cases from
  • bot (Red) – The bot’s instance
  • member (discord.Member) – The member to get cases about
  • member_id (int) – The id of the member to get cases about

A list of all matching cases.

Return type:


await redbot.core.modlog.create_case(bot, guild, created_at, action_type, user, moderator=None, reason=None, until=None, channel=None)[source]

Creates a new case.

This fires an event on_modlog_case_create

  • bot (Red) – The bot object
  • guild (discord.Guild) – The guild the action was taken in
  • created_at (datetime) – The time the action occurred at
  • action_type (str) – The type of action that was taken
  • user (Union[discord.User, discord.Member]) – The user target by the action
  • moderator (Optional[Union[discord.User, discord.Member]]) – The moderator who took the action
  • reason (Optional[str]) – The reason the action was taken
  • until (Optional[datetime]) – The time the action is in effect until
  • channel (Optional[discord.TextChannel]) – The channel the action was taken in
await redbot.core.modlog.get_casetype(name, guild=None)[source]

Gets the case type

  • name (str) – The name of the case type to get
  • guild (Optional[discord.Guild]) – If provided, sets the case type’s guild attribute to this guild

Case type with provided name. If such case type doesn’t exist this will be None.

Return type:


await redbot.core.modlog.get_all_casetypes(guild=None)[source]

Get all currently registered case types

Returns:A list of case types
Return type:list
await redbot.core.modlog.register_casetype(name, default_setting, image, case_str)[source]

Registers a case type. If the case type exists and there are differences between the values passed and what is stored already, the case type will be updated with the new values

  • name (str) – The name of the case
  • default_setting (bool) – Whether the case type should be on (if True) or off (if False) by default
  • image (str) – The emoji to use for the case type (for example, :boot:)
  • case_str (str) – The string representation of the case (example: Ban)

The case type that was registered

Return type:


await redbot.core.modlog.register_casetypes(new_types)[source]

Registers multiple case types


new_types (list) – The new types to register


True if all were registered successfully

Return type:


await redbot.core.modlog.get_modlog_channel(guild)[source]

Get the current modlog channel.

Parameters:guild (discord.Guild) – The guild to get the modlog channel for.
Returns:The channel object representing the modlog channel.
Return type:discord.TextChannel
Raises:RuntimeError – If the modlog channel is not found.
await redbot.core.modlog.set_modlog_channel(guild, channel)[source]

Changes the modlog channel


True if successful

Return type:


await redbot.core.modlog.reset_cases(guild)[source]

Wipes all modlog cases for the specified guild.

Parameters:guild (discord.Guild) – The guild to reset cases for