Administration and moderation

These functions allow you to perform moderation actions on users and generally process reports using the API. To do this, you need access to the “admin:read” and/or “admin:write” scopes or their more granular variants (both for the application and the access token), as well as at least moderator access. Mastodon.py will not request these by default, as that would be very dangerous.

BIG WARNING: TREAT ANY ACCESS TOKENS THAT HAVE ADMIN CREDENTIALS AS EXTREMELY, MASSIVELY SENSITIVE DATA AND MAKE EXTRA SURE TO REVOKE THEM AFTER TESTING, NOT LET THEM SIT IN FILES SOMEWHERE, TRACK WHICH ARE ACTIVE, ET CETERA. ANY EXPOSURE OF SUCH ACCESS TOKENS MEANS YOU EXPOSE THE PERSONAL DATA OF ALL YOUR USERS TO WHOEVER HAS THESE TOKENS. TREAT THEM WITH EXTREME CARE.

This is not to say that you should not treat access tokens from admin accounts that do not have admin: scopes attached with a lot of care, but be extra careful with those that do.

Accounts

Mastodon.admin_accounts_v2(origin=None, by_domain=None, status=None, username=None, display_name=None, email=None, ip=None, permissions=None, invited_by=None, role_ids=None, max_id=None, min_id=None, since_id=None, limit=None)[source]

Fetches a list of accounts that match given criteria. By default, local accounts are returned.

  • Set origin to “local” or “remote” to get only local or remote accounts.
  • Set by_domain to a domain to get only accounts from that domain.
  • Set status to one of “active”, “pending”, “disabled”, “silenced” or “suspended” to get only accounts with that moderation status (default: active)
  • Set username to a string to get only accounts whose username contains this string.
  • Set display_name to a string to get only accounts whose display name contains this string.
  • Set email to an email to get only accounts with that email (this only works on local accounts).
  • Set ip to an ip (as a string, standard v4/v6 notation) to get only accounts whose last active ip is that ip (this only works on local accounts).
  • Set permissions to “staff” to only get accounts with staff permissions.
  • Set invited_by to an account id to get only accounts invited by this user.
  • Set role_ids to a list of role IDs to get only accounts with those roles.

Returns a list of admin account dicts.

Added: Mastodon v2.9.1, last changed: Mastodon v4.0.0

Mastodon.admin_accounts(remote=False, by_domain=None, status='active', username=None, display_name=None, email=None, ip=None, staff_only=False, max_id=None, min_id=None, since_id=None, limit=None)[source]

Currently a synonym for admin_accounts_v1, now deprecated. You are strongly encouraged to use admin_accounts_v2 instead, since this one is kind of bad.

!!!!! This function may be switched to calling the v2 API in the future. This is your warning. If you want to keep using v1, use it explicitly. !!!!!

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_accounts_v1(remote=False, by_domain=None, status='active', username=None, display_name=None, email=None, ip=None, staff_only=False, max_id=None, min_id=None, since_id=None, limit=None)[source]

Fetches a list of accounts that match given criteria. By default, local accounts are returned.

  • Set remote to True to get remote accounts, otherwise local accounts are returned (default: local accounts)
  • Set by_domain to a domain to get only accounts from that domain.
  • Set status to one of “active”, “pending”, “disabled”, “silenced” or “suspended” to get only accounts with that moderation status (default: active)
  • Set username to a string to get only accounts whose username contains this string.
  • Set display_name to a string to get only accounts whose display name contains this string.
  • Set email to an email to get only accounts with that email (this only works on local accounts).
  • Set ip to an ip (as a string, standard v4/v6 notation) to get only accounts whose last active ip is that ip (this only works on local accounts).
  • Set staff_only to True to only get staff accounts (this only works on local accounts).

Note that setting the boolean parameters to False does not mean “give me users to which this does not apply” but instead means “I do not care if users have this attribute”.

Deprecated in Mastodon version 3.5.0.

Returns a list of admin account dicts.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_account(id)[source]

Fetches a single admin account dict for the user with the given id.

Returns that dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_account_enable(id)[source]

Reenables login for a local account for which login has been disabled.

Returns the updated admin account dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_account_approve(id)[source]

Approves a pending account.

Returns the updated admin account dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_account_reject(id)[source]

Rejects and deletes a pending account.

Returns the updated admin account dict for the account that is now gone.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_account_unsilence(id)[source]

Unsilences an account.

Returns the updated admin account dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_account_unsuspend(id)[source]

Unsuspends an account.

Returns the updated admin account dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_account_moderate(id, action=None, report_id=None, warning_preset_id=None, text=None, send_email_notification=True)[source]

Perform a moderation action on an account.

Valid actions are:
  • “disable” - for a local user, disable login.
  • “silence” - hide the users posts from all public timelines.
  • “suspend” - irreversibly delete all the user’s posts, past and future.
  • “sensitive” - forcce an accounts media visibility to always be sensitive.

If no action is specified, the user is only issued a warning.

Specify the id of a report as report_id to close the report with this moderation action as the resolution. Specify warning_preset_id to use a warning preset as the notification text to the user, or text to specify text directly. If both are specified, they are concatenated (preset first). Note that there is currently no API to retrieve or create warning presets.

Set send_email_notification to False to not send the user an email notification informing them of the moderation action.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Reports

Mastodon.admin_reports(resolved=False, account_id=None, target_account_id=None, max_id=None, min_id=None, since_id=None, limit=None)[source]

Fetches the list of reports.

Set resolved to True to search for resolved reports. account_id and target_account_id can be used to get reports filed by or about a specific user.

Returns a list of report dicts.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_report(id)[source]

Fetches the report with the given id.

Returns a report dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_report_assign(id)[source]

Assigns the given report to the logged-in user.

Returns the updated report dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_report_unassign(id)[source]

Unassigns the given report from the logged-in user.

Returns the updated report dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_report_reopen(id)[source]

Reopens a closed report.

Returns the updated report dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Mastodon.admin_report_resolve(id)[source]

Marks a report as resolved (without taking any action).

Returns the updated report dict.

Added: Mastodon v2.9.1, last changed: Mastodon v2.9.1

Federation

Mastodon.admin_create_domain_block(domain: str, severity: str = None, reject_media: bool = None, reject_reports: bool = None, private_comment: str = None, public_comment: str = None, obfuscate: bool = None)[source]

Perform a moderation action on a domain. Requires scope admin:write:domain_blocks.

Valid severities are:
  • “silence” - hide all posts from federated timelines and do not show notifications to local users from the remote instance’s users unless they are following the remote user.
  • “suspend” - deny interactions with this instance going forward. This action is reversible.
  • “limit” - generally used with reject_media=true to force reject media from an instance without silencing or suspending..

If no action is specified, the domain is only silenced. domain is the domain to block. Note that using the top level domain will also imapct all subdomains. ie, example.com will also impact subdomain.example.com. reject_media will not download remote media on to your local instance media storage. reject_reports ignores all reports from the remote instance. private_comment sets a private admin comment for the domain. public_comment sets a publicly available comment for this domain, which will be available to local users and may be available to everyone depending on your settings. obfuscate censors some part of the domain name. Useful if the domain name contains unwanted words like slurs.

Returns the new domain block as an admin domain block dict.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0

Mastodon.admin_update_domain_block(id, severity: str = None, reject_media: bool = None, reject_reports: bool = None, private_comment: str = None, public_comment: str = None, obfuscate: bool = None)[source]

Modify existing moderation action on a domain. Requires scope admin:write:domain_blocks.

Valid severities are:
  • “silence” - hide all posts from federated timelines and do not show notifications to local users from the remote instance’s users unless they are following the remote user.
  • “suspend” - deny interactions with this instance going forward. This action is reversible.
  • “limit” - generally used with reject_media=true to force reject media from an instance without silencing or suspending.

If no action is specified, the domain is only silenced. domain is the domain to block. Note that using the top level domain will also imapct all subdomains. ie, example.com will also impact subdomain.example.com. reject_media will not download remote media on to your local instance media storage. reject_reports ignores all reports from the remote instance. private_comment sets a private admin comment for the domain. public_comment sets a publicly available comment for this domain, which will be available to local users and may be available to everyone depending on your settings. obfuscate censors some part of the domain name. Useful if the domain name contains unwanted words like slurs.

Returns the modified domain block as an admin domain block dict, raises a MastodonAPIError if the specified block does not exist.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0

Mastodon.admin_delete_domain_block(id=None)[source]

Removes moderation action against a given domain. Requires scope admin:write:domain_blocks.

Provide an id to remove a specific domain block based on its database id.

Raises a MastodonAPIError if the specified block does not exist.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0

Moderation actions

Mastodon.admin_measures(start_at, end_at, active_users=False, new_users=False, interactions=False, opened_reports=False, resolved_reports=False, tag_accounts=None, tag_uses=None, tag_servers=None, instance_accounts=None, instance_media_attachments=None, instance_reports=None, instance_statuses=None, instance_follows=None, instance_followers=None)[source]

Retrieves numerical instance information for the time period (at day granularity) between start_at and end_at.

  • active_users: Pass true to retrieve the number of active users on your instance within the time period
  • new_users: Pass true to retrieve the number of users who joined your instance within the time period
  • interactions: Pass true to retrieve the number of interactions (favourites, boosts, replies) on local statuses within the time period
  • opened_reports: Pass true to retrieve the number of reports filed within the time period
  • resolved_reports = Pass true to retrieve the number of reports resolved within the time period
  • tag_accounts: Pass a tag ID to get the number of accounts which used that tag in at least one status within the time period
  • tag_uses: Pass a tag ID to get the number of statuses which used that tag within the time period
  • tag_servers: Pass a tag ID to to get the number of remote origin servers for statuses which used that tag within the time period
  • instance_accounts: Pass a domain to get the number of accounts originating from that remote domain within the time period
  • instance_media_attachments: Pass a domain to get the amount of space used by media attachments from that remote domain within the time period
  • instance_reports: Pass a domain to get the number of reports filed against accounts from that remote domain within the time period
  • instance_statuses: Pass a domain to get the number of statuses originating from that remote domain within the time period
  • instance_follows: Pass a domain to get the number of accounts from a remote domain followed by that local user within the time period
  • instance_followers: Pass a domain to get the number of local accounts followed by accounts from that remote domain within the time period

This API call is relatively expensive - watch your servers load if you want to get a lot of statistical data. Especially the instance_statuses stats might take a long time to compute and, in fact, time out.

There is currently no way to get tag IDs implemented in Mastodon.py, because the Mastodon public API does not implement one. This will be fixed in a future release.

Returns a list of admin measure dicts.

Added: Mastodon v3.5.0, last changed: Mastodon v3.5.0

Mastodon.admin_dimensions(start_at, end_at, limit=None, languages=False, sources=False, servers=False, space_usage=False, software_versions=False, tag_servers=None, tag_languages=None, instance_accounts=None, instance_languages=None)[source]

Retrieves primarily categorical instance information for the time period (at day granularity) between start_at and end_at.

  • languages: Pass true to get the most-used languages on this server
  • sources: Pass true to get the most-used client apps on this server
  • servers: Pass true to get the remote servers with the most statuses
  • space_usage: Pass true to get the how much space is used by different components your software stack
  • software_versions: Pass true to get the version numbers for your software stack
  • tag_servers: Pass a tag ID to get the most-common servers for statuses including a trending tag
  • tag_languages: Pass a tag ID to get the most-used languages for statuses including a trending tag
  • instance_accounts: Pass a domain to get the most-followed accounts from a remote server
  • instance_languages: Pass a domain to get the most-used languages from a remote server

Pass limit to set how many results you want on queries where that makes sense.

This API call is relatively expensive - watch your servers load if you want to get a lot of statistical data.

There is currently no way to get tag IDs implemented in Mastodon.py, because the Mastodon public API does not implement one. This will be fixed in a future release.

Returns a list of admin dimension dicts.

Added: Mastodon v3.5.0, last changed: Mastodon v3.5.0

Mastodon.admin_retention(start_at, end_at, frequency='day')[source]

Gets user retention statistics (at frequency - “day” or “month” - granularity) between start_at and end_at.

Returns a list of admin retention dicts

Added: Mastodon v3.5.0, last changed: Mastodon v3.5.0