Every function on a huge CTRL-F-able page

Mastodon.retrieve_mastodon_version()

Determine installed Mastodon version and set major, minor and patch (not including RC info) accordingly.

Returns the version string, possibly including rc info.

Mastodon.verify_minimum_version(version_str, cached=False)

Update version info from server and verify that at least the specified version is present.

If you specify “cached”, the version info update part is skipped.

Returns True if version requirement is satisfied, False if not.

static Mastodon.create_app(client_name, scopes=['read', 'write', 'follow', 'push'], redirect_uris=None, website=None, to_file=None, api_base_url=None, request_timeout=300, session=None)

Create a new app with given client_name and scopes (The basic scopes are “read”, “write”, “follow” and “push” - more granular scopes are available, please refer to Mastodon documentation for which) on the instance given by api_base_url.

Specify redirect_uris if you want users to be redirected to a certain page after authenticating in an OAuth flow. You can specify multiple URLs by passing a list. Note that if you wish to use OAuth authentication with redirects, the redirect URI must be one of the URLs specified here.

Specify to_file to persist your app’s info to a file so you can use it in the constructor. Specify website to give a website for your app.

Specify session with a requests.Session for it to be used instead of the default. This can be used to, amongst other things, adjust proxy or SSL certificate settings.

Presently, app registration is open by default, but this is not guaranteed to be the case for all Mastodon instances in the future.

Returns client_id and client_secret, both as strings.

Mastodon.app_verify_credentials()

Fetch information about the current application.

Returns an application dict.

Added: Mastodon v2.0.0, last changed: Mastodon v2.7.2

Mastodon.__init__(client_id=None, client_secret=None, access_token=None, api_base_url=None, debug_requests=False, ratelimit_method='wait', ratelimit_pacefactor=1.1, request_timeout=300, mastodon_version=None, version_check_mode='created', session=None, feature_set='mainline', user_agent='mastodonpy', lang=None)

Create a new API wrapper instance based on the given client_secret and client_id on the instance given by api_base_url. If you give a client_id and it is not a file, you must also give a secret. If you specify an access_token then you don’t need to specify a client_id. It is allowed to specify neither - in this case, you will be restricted to only using endpoints that do not require authentication. If a file is given as client_id, client ID, secret and base url are read from that file.

You can also specify an access_token, directly or as a file (as written by log_in()). If a file is given, Mastodon.py also tries to load the base URL from this file, if present. A client id and secret are not required in this case.

Mastodon.py can try to respect rate limits in several ways, controlled by ratelimit_method. “throw” makes functions throw a MastodonRatelimitError when the rate limit is hit. “wait” mode will, once the limit is hit, wait and retry the request as soon as the rate limit resets, until it succeeds. “pace” works like throw, but tries to wait in between calls so that the limit is generally not hit (how hard it tries to avoid hitting the rate limit can be controlled by ratelimit_pacefactor). The default setting is “wait”. Note that even in “wait” and “pace” mode, requests can still fail due to network or other problems! Also note that “pace” and “wait” are NOT thread safe.

By default, a timeout of 300 seconds is used for all requests. If you wish to change this, pass the desired timeout (in seconds) as request_timeout.

For fine-tuned control over the requests object use session with a requests.Session.

The mastodon_version parameter can be used to specify the version of Mastodon that Mastodon.py will expect to be installed on the server. The function will throw an error if an unparseable Version is specified. If no version is specified, Mastodon.py will set mastodon_version to the detected version.

The version check mode can be set to “created” (the default behaviour), “changed” or “none”. If set to “created”, Mastodon.py will throw an error if the version of Mastodon it is connected to is too old to have an endpoint. If it is set to “changed”, it will throw an error if the endpoint’s behaviour has changed after the version of Mastodon that is connected has been released. If it is set to “none”, version checking is disabled.

feature_set can be used to enable behaviour specific to non-mainline Mastodon API implementations. Details are documented in the functions that provide such functionality. Currently supported feature sets are mainline, fedibird and pleroma.

For some Mastodon instances a User-Agent header is needed. This can be set by parameter user_agent. Starting from Mastodon.py 1.5.2 create_app() stores the application name into the client secret file. If client_id points to this file, the app name will be used as User-Agent header as default. It is possible to modify old secret files and append a client app name to use it as a User-Agent name.

lang can be used to change the locale Mastodon will use to generate responses. Valid parameters are all ISO 639-1 (two letter) or for a language that has none, 639-3 (three letter) language codes. This affects some error messages (those related to validation) and trends. You can change the language using set_language().

If no other User-Agent is specified, “mastodonpy” will be used.

Mastodon.log_in(username=None, password=None, code=None, redirect_uri='urn:ietf:wg:oauth:2.0:oob', refresh_token=None, scopes=['read', 'write', 'follow', 'push'], to_file=None)

Get the access token for a user.

The username is the email address used to log in into Mastodon.

Can persist access token to file to_file, to be used in the constructor.

Handles password and OAuth-based authorization.

Will throw a MastodonIllegalArgumentError if the OAuth flow data or the username / password credentials given are incorrect, and MastodonAPIError if all of the requested scopes were not granted.

For OAuth 2, obtain a code via having your user go to the URL returned by auth_request_url() and pass it as the code parameter. In this case, make sure to also pass the same redirect_uri parameter as you used when generating the auth request URL.

Returns the access token as a string.

Mastodon.auth_request_url(client_id=None, redirect_uris='urn:ietf:wg:oauth:2.0:oob', scopes=['read', 'write', 'follow', 'push'], force_login=False, state=None, lang=None)

Returns the URL that a client needs to request an OAuth grant from the server.

To log in with OAuth, send your user to this URL. The user will then log in and get a code which you can pass to log_in().

scopes are as in log_in(), redirect_uris is where the user should be redirected to after authentication. Note that redirect_uris must be one of the URLs given during app registration. When using urn:ietf:wg:oauth:2.0:oob, the code is simply displayed, otherwise it is added to the given URL as the “code” request parameter.

Pass force_login if you want the user to always log in even when already logged into web Mastodon (i.e. when registering multiple different accounts in an app).

state is the oauth state parameter to pass to the server. It is strongly suggested to use a random, nonguessable value (i.e. nothing meaningful and no incrementing ID) to preserve security guarantees. It can be left out for non-web login flows.

Pass an ISO 639-1 (two letter) or, for languages that do not have one, 639-3 (three letter) language code as lang to control the display language for the oauth form.

Mastodon.set_language(lang)

Set the locale Mastodon will use to generate responses. Valid parameters are all ISO 639-1 (two letter) or, for languages that do not have one, 639-3 (three letter) language codes. This affects some error messages (those related to validation) and trends.

Mastodon.revoke_access_token()

Revoke the oauth token the user is currently authenticated with, effectively removing the apps access and requiring the user to log in again.

Mastodon.create_account(username, password, email, agreement=False, reason=None, locale='en', scopes=['read', 'write', 'follow', 'push'], to_file=None, return_detailed_error=False)

Creates a new user account with the given username, password and email. “agreement” must be set to true (after showing the user the instance’s user agreement and having them agree to it), “locale” specifies the language for the confirmation email as an ISO 639-1 (two letter) or, if a language does not have one, 639-3 (three letter) language code. reason can be used to specify why a user would like to join if approved-registrations mode is on.

Does not require an access token, but does require a client grant.

By default, this method is rate-limited by IP to 5 requests per 30 minutes.

Returns an access token (just like log_in), which it can also persist to to_file, and sets it internally so that the user is now logged in. Note that this token can only be used after the user has confirmed their email.

By default, the function will throw if the account could not be created. Alternately, when return_detailed_error is passed, Mastodon.py will return the detailed error response that the API provides (Starting from version 3.4.0 - not checked here) as an dict with error details as the second return value and the token returned as None in case of error. The dict will contain a text error values as well as a details value which is a dict with one optional key for each potential field (username, password, email and agreement), each if present containing a dict with an error category and free text description. Valid error categories are:

• ERR_BLOCKED - When e-mail provider is not allowed
• ERR_UNREACHABLE - When e-mail address does not resolve to any IP via DNS (MX, A, AAAA)
• ERR_TAKEN - When username or e-mail are already taken
• ERR_RESERVED - When a username is reserved, e.g. “webmaster” or “admin”
• ERR_ACCEPTED - When agreement has not been accepted
• ERR_BLANK - When a required attribute is blank
• ERR_INVALID - When an attribute is malformed, e.g. wrong characters or invalid e-mail address
• ERR_TOO_LONG - When an attribute is over the character limit
• ERR_TOO_SHORT - When an attribute is under the character requirement
• ERR_INCLUSION - When an attribute is not one of the allowed values, e.g. unsupported locale

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

Mastodon.email_resend_confirmation()

Requests a re-send of the users confirmation mail for an unconfirmed logged in user.

Only available to the app that the user originally signed up with.

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

Mastodon.status(id)

Fetch information about a single toot.

Does not require authentication for publicly visible statuses.

Returns a status dict.

Added: Mastodon v1.0.0, last changed: Mastodon v2.0.0

Mastodon.status_context(id)

Fetch information about ancestors and descendants of a toot.

Does not require authentication for publicly visible statuses.

Returns a context dict.

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

Mastodon.status_reblogged_by(id)

Fetch a list of users that have reblogged a status.

Does not require authentication for publicly visible statuses.

Returns a list of account dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v2.1.0

Mastodon.status_favourited_by(id)

Fetch a list of users that have favourited a status.

Does not require authentication for publicly visible statuses.

Returns a list of account dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v2.1.0

Mastodon.status_card(id)

Fetch a card associated with a status. A card describes an object (such as an external video or link) embedded into a status.

Does not require authentication for publicly visible statuses.

This function is deprecated as of 3.0.0 and the endpoint does not exist anymore - you should just use the “card” field of the status dicts instead. Mastodon.py will try to mimic the old behaviour, but this is somewhat inefficient and not guaranteed to be the case forever.

Returns a card dict.

Added: Mastodon v1.0.0, last changed: Mastodon v3.0.0

Mastodon.status_history(id)

Returns the edit history of a status as a list of status edit dicts, starting from the original form. Note that this means that a status that has been edited once will have two entries in this list, a status that has been edited twice will have three, and so on.

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

Mastodon.status_source(id)

Returns the source of a status for editing.

Return value is a dictionary containing exactly the parameters you could pass to status_update() to change nothing about the status, except status is text instead.

Mastodon.favourites(max_id=None, min_id=None, since_id=None, limit=None)

Fetch the logged-in user’s favourited statuses.

Returns a list of status dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v2.6.0

Mastodon.bookmarks(max_id=None, min_id=None, since_id=None, limit=None)

Get a list of statuses bookmarked by the logged-in user.

Returns a list of status dicts.

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

Mastodon.status_post(status, in_reply_to_id=None, media_ids=None, sensitive=False, visibility=None, spoiler_text=None, language=None, idempotency_key=None, content_type=None, scheduled_at=None, poll=None, quote_id=None)

Post a status. Can optionally be in reply to another status and contain media.

media_ids should be a list. (If it’s not, the function will turn it into one.) It can contain up to four pieces of media (uploaded via media_post()). media_ids can also be the `media dicts`_ returned by media_post() - they are unpacked automatically.

The sensitive boolean decides whether or not media attached to the post should be marked as sensitive, which hides it by default on the Mastodon web front-end.

The visibility parameter is a string value and accepts any of: ‘direct’ - post will be visible only to mentioned users ‘private’ - post will be visible only to followers ‘unlisted’ - post will be public but not appear on the public timeline ‘public’ - post will be public

If not passed in, visibility defaults to match the current account’s default-privacy setting (starting with Mastodon version 1.6) or its locked setting - private if the account is locked, public otherwise (for Mastodon versions lower than 1.6).

The spoiler_text parameter is a string to be shown as a warning before the text of the status. If no text is passed in, no warning will be displayed.

Specify language to override automatic language detection. The parameter accepts all valid ISO 639-1 (2-letter) or for languages where that do not have one, 639-3 (three letter) language codes.

You can set idempotency_key to a value to uniquely identify an attempt at posting a status. Even if you call this function more than once, if you call it with the same idempotency_key, only one status will be created.

Pass a datetime as scheduled_at to schedule the toot for a specific time (the time must be at least 5 minutes into the future). If this is passed, status_post returns a scheduled status dict instead.

Pass poll to attach a poll to the status. An appropriate object can be constructed using make_poll() . Note that as of Mastodon version 2.8.2, you can only have either media or a poll attached, not both at the same time.

Specific to “pleroma” feature set:: Specify content_type to set the content type of your post on Pleroma. It accepts ‘text/plain’ (default), ‘text/markdown’, ‘text/html’ and ‘text/bbcode’. This parameter is not supported on Mastodon servers, but will be safely ignored if set.

Specific to “fedibird” feature set:: The quote_id parameter is a non-standard extension that specifies the id of a quoted status.

Returns a status dict with the new status.

Added: Mastodon v1.0.0, last changed: Mastodon v2.8.0

Mastodon.status_reply(to_status, status, in_reply_to_id=None, media_ids=None, sensitive=False, visibility=None, spoiler_text=None, language=None, idempotency_key=None, content_type=None, scheduled_at=None, poll=None, untag=False)

Helper function - acts like status_post, but prepends the name of all the users that are being replied to to the status text and retains CW and visibility if not explicitly overridden.

Set untag to True if you want the reply to only go to the user you are replying to, removing every other mentioned user from the conversation.

Added: Mastodon v1.0.0, last changed: Mastodon v2.8.0

Mastodon.toot(status)

Synonym for status_post() that only takes the status text as input.

Usage in production code is not recommended.

Returns a status dict with the new status.

Added: Mastodon v1.0.0, last changed: Mastodon v2.8.0

Mastodon.make_poll(options, expires_in, multiple=False, hide_totals=False)

Generate a poll object that can be passed as the poll option when posting a status.

options is an array of strings with the poll options (Maximum, by default: 4), expires_in is the time in seconds for which the poll should be open. Set multiple to True to allow people to choose more than one answer. Set hide_totals to True to hide the results of the poll until it has expired.

Mastodon.status_reblog(id, visibility=None)

Reblog / boost a status.

The visibility parameter functions the same as in status_post() and allows you to reduce the visibility of a reblogged status.

Returns a status dict with a new status that wraps around the reblogged one.

Added: Mastodon v1.0.0, last changed: Mastodon v2.0.0

Mastodon.status_unreblog(id)

Un-reblog a status.

Returns a status dict with the status that used to be reblogged.

Added: Mastodon v1.0.0, last changed: Mastodon v2.0.0

Mastodon.status_favourite(id)

Favourite a status.

Returns a status dict with the favourited status.

Added: Mastodon v1.0.0, last changed: Mastodon v2.0.0

Mastodon.status_unfavourite(id)

Un-favourite a status.

Returns a status dict with the un-favourited status.

Added: Mastodon v1.0.0, last changed: Mastodon v2.0.0

Mastodon.status_mute(id)

Mute notifications for a status.

Returns a status dict with the now muted status

Added: Mastodon v1.4.0, last changed: Mastodon v2.0.0

Mastodon.status_unmute(id)

Unmute notifications for a status.

Returns a status dict with the status that used to be muted.

Added: Mastodon v1.4.0, last changed: Mastodon v2.0.0

Mastodon.status_bookmark(id)

Bookmark a status as the logged-in user.

Returns a status dict with the now bookmarked status

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

Mastodon.status_unbookmark(id)

Unbookmark a bookmarked status for the logged-in user.

Returns a status dict with the status that used to be bookmarked.

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

Mastodon.status_delete(id)

Delete a status

Returns the now-deleted status, with an added “source” attribute that contains the text that was used to compose this status (this can be used to power “delete and redraft” functionality)

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

Mastodon.status_update(id, status=None, spoiler_text=None, sensitive=None, media_ids=None, poll=None)

Edit a status. The meanings of the fields are largely the same as in status_post(), though not every field can be edited.

Note that editing a poll will reset the votes.

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

Mastodon.scheduled_statuses()

Fetch a list of scheduled statuses

Returns a list of scheduled status dicts.

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

Mastodon.scheduled_status(id)

Fetch information about the scheduled status with the given id.

Returns a scheduled status dict.

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

Mastodon.scheduled_status_update(id, scheduled_at)

Update the scheduled time of a scheduled status.

New time must be at least 5 minutes into the future.

Returns a scheduled status dict

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

Mastodon.scheduled_status_delete(id)

Deletes a scheduled status.

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

Mastodon.media_post(media_file, mime_type=None, description=None, focus=None, file_name=None, thumbnail=None, thumbnail_mime_type=None, synchronous=False)

Post an image, video or audio file. media_file can either be data or a file name. If data is passed directly, the mime type has to be specified manually, otherwise, it is determined from the file name. focus should be a tuple of floats between -1 and 1, giving the x and y coordinates of the images focus point for cropping (with the origin being the images center).

Throws a MastodonIllegalArgumentError if the mime type of the passed data or file can not be determined properly.

file_name can be specified to upload a file with the given name, which is ignored by Mastodon, but some other Fediverse server software will display it. If no name is specified, a random name will be generated. The filename of a file specified in media_file will be ignored.

Starting with Mastodon 3.2.0, thumbnail can be specified in the same way as media_file to upload a custom thumbnail image for audio and video files.

Returns a media dict. This contains the id that can be used in status_post to attach the media file to a toot.

When using the v2 API (post Mastodon version 3.1.4), the url in the returned dict will be null, since attachments are processed asynchronously. You can fetch an updated dict using media. Pass “synchronous” to emulate the old behaviour. Not recommended, inefficient and deprecated, will eat your API quota, you know the deal.

Added: Mastodon v1.0.0, last changed: Mastodon v3.2.0

Mastodon.media_update(id, description=None, focus=None, thumbnail=None, thumbnail_mime_type=None)

Update the metadata of the media file with the given id. description and focus and thumbnail are as in media_post() .

Returns the updated media dict.

Added: Mastodon v2.3.0, last changed: Mastodon v3.2.0

Mastodon.poll(id)

Fetch information about the poll with the given id

Returns a poll dict.

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

Mastodon.account_verify_credentials()

Fetch logged-in user’s account information.

Returns a account dict (Starting from 2.1.0, with an additional “source” field).

Added: Mastodon v1.0.0, last changed: Mastodon v2.1.0

Mastodon.me()

Get this user’s account. Synonym for account_verify_credentials(), does exactly the same thing, just exists becase account_verify_credentials() has a confusing name.

Added: Mastodon v1.0.0, last changed: Mastodon v2.1.0

Mastodon.account(id)

Fetch account information by user id.

Does not require authentication for publicly visible accounts.

Returns a account dict.

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

Mastodon.account_search(q, limit=None, following=False)

Fetch matching accounts. Will lookup an account remotely if the search term is in the username@domain format and not yet in the database. Set following to True to limit the search to users the logged-in user follows.

Returns a list of account dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v2.3.0

Mastodon.account_lookup(acct)

Look up an account from user@instance form (@instance allowed but not required for local accounts). Will only return accounts that the instance already knows about, and not do any webfinger requests. Use account_search if you need to resolve users through webfinger from remote.

Returns an account dict.

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

Mastodon.featured_tags()

Return the hashtags the logged-in user has set to be featured on their profile as a list of featured tag dicts.

Returns a list of featured tag dicts.

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

Mastodon.featured_tag_suggestions()

Returns the logged-in user’s 10 most commonly-used hashtags.

Returns a list of hashtag dicts.

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

Mastodon.account_featured_tags(id)

Get an account’s featured hashtags.

Returns a list of hashtag dicts (NOT `featured tag dicts`_).

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

Mastodon.endorsements()

Fetch list of users endorsed by the logged-in user.

Returns a list of account dicts.

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

Mastodon.account_statuses(id, only_media=False, pinned=False, exclude_replies=False, exclude_reblogs=False, tagged=None, max_id=None, min_id=None, since_id=None, limit=None)

Fetch statuses by user id. Same options as timeline() are permitted. Returned toots are from the perspective of the logged-in user, i.e. all statuses visible to the logged-in user (including DMs) are included.

If only_media is set, return only statuses with media attachments. If pinned is set, return only statuses that have been pinned. Note that as of Mastodon 2.1.0, this only works properly for instance-local users. If exclude_replies is set, filter out all statuses that are replies. If exclude_reblogs is set, filter out all statuses that are reblogs. If tagged is set, return only statuses that are tagged with tagged. Only a single tag without a ‘#’ is valid.

Does not require authentication for Mastodon versions after 2.7.0 (returns publicly visible statuses in that case), for publicly visible accounts.

Returns a list of status dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v2.8.0

Mastodon.account_following(id, max_id=None, min_id=None, since_id=None, limit=None)

Fetch users the given user is following.

Returns a list of account dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v2.6.0

Mastodon.account_familiar_followers(id)

Find followers for the account given by id (can be a list) that also follow the logged in account.

Returns a list of familiar follower dicts

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

Mastodon.account_lists(id)

Get all of the logged-in user’s lists which the specified user is a member of.

Returns a list of list dicts.

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

Mastodon.account_update_credentials(display_name=None, note=None, avatar=None, avatar_mime_type=None, header=None, header_mime_type=None, locked=None, bot=None, discoverable=None, fields=None)

Update the profile for the currently logged-in user.

note is the user’s bio.

avatar and ‘header’ are images. As with media uploads, it is possible to either pass image data and a mime type, or a filename of an image file, for either.

locked specifies whether the user needs to manually approve follow requests.

bot specifies whether the user should be set to a bot.

discoverable specifies whether the user should appear in the user directory.

fields can be a list of up to four name-value pairs (specified as tuples) to appear as semi-structured information in the user’s profile.

Returns the updated account dict of the logged-in user.

Added: Mastodon v1.1.1, last changed: Mastodon v3.1.0

Mastodon.account_pin(id)

Pin / endorse a user.

Returns a relationship dict containing the updated relationship to the user.

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

Mastodon.account_unpin(id)

Unpin / un-endorse a user.

Returns a relationship dict containing the updated relationship to the user.

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

Mastodon.account_note_set(id, comment)

Set a note (visible to the logged in user only) for the given account.

Returns a status dict with the note updated.

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

Mastodon.featured_tag_create(name)

Creates a new featured hashtag displayed on the logged-in user’s profile.

Returns a featured tag dict with the newly featured tag.

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

Mastodon.featured_tag_delete(id)

Deletes one of the logged-in user’s featured hashtags.

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

Mastodon.status_pin(id)

Pin a status for the logged-in user.

Returns a status dict with the now pinned status

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

Mastodon.status_unpin(id)

Unpin a pinned status for the logged-in user.

Returns a status dict with the status that used to be pinned.

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

Mastodon.account_followers(id, max_id=None, min_id=None, since_id=None, limit=None)

Fetch users the given user is followed by.

Returns a list of account dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v2.6.0

Mastodon.account_relationships(id)

Fetch relationship (following, followed_by, blocking, follow requested) of the logged in user to a given account. id can be a list.

Returns a list of relationship dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v1.4.0

Mastodon.follows(uri)

Follow a remote user by uri (username@domain).

Returns a account dict.

Added: Mastodon v1.0.0, last changed: Mastodon v2.1.0

Mastodon.follow_requests(max_id=None, min_id=None, since_id=None, limit=None)

Fetch the logged-in user’s incoming follow requests.

Returns a list of account dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v2.6.0

Mastodon.suggestions()

Fetch follow suggestions for the logged-in user.

Returns a list of account dicts.

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

Mastodon.account_follow(id, reblogs=True, notify=False)

Follow a user.

Set reblogs to False to hide boosts by the followed user. Set notify to True to get a notification every time the followed user posts.

Returns a relationship dict containing the updated relationship to the user.

Added: Mastodon v1.0.0, last changed: Mastodon v3.3.0

Mastodon.account_unfollow(id)

Unfollow a user.

Returns a relationship dict containing the updated relationship to the user.

Added: Mastodon v1.0.0, last changed: Mastodon v1.4.0

Mastodon.follow_request_authorize(id)

Accept an incoming follow request.

Returns the updated relationship dict for the requesting account.

Added: Mastodon v1.0.0, last changed: Mastodon v3.0.0

Mastodon.follow_request_reject(id)

Reject an incoming follow request.

Returns the updated relationship dict for the requesting account.

Added: Mastodon v1.0.0, last changed: Mastodon v3.0.0

Mastodon.suggestion_delete(account_id)

Remove the user with the given account_id from the follow suggestions.

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

Mastodon.mutes(max_id=None, min_id=None, since_id=None, limit=None)

Fetch a list of users muted by the logged-in user.

Returns a list of account dicts.

Added: Mastodon v1.1.0, last changed: Mastodon v2.6.0

Mastodon.blocks(max_id=None, min_id=None, since_id=None, limit=None)

Fetch a list of users blocked by the logged-in user.

Returns a list of account dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v2.6.0

Mastodon.domain_blocks(max_id=None, min_id=None, since_id=None, limit=None)

Fetch the logged-in user’s blocked domains.

Returns a list of blocked domain URLs (as strings, without protocol specifier).

Added: Mastodon v1.4.0, last changed: Mastodon v2.6.0

Mastodon.account_mute(id, notifications=True, duration=None)

Mute a user.

Set notifications to False to receive notifications even though the user is muted from timelines. Pass a duration in seconds to have Mastodon automatically lift the mute after that many seconds.

Returns a relationship dict containing the updated relationship to the user.

Added: Mastodon v1.1.0, last changed: Mastodon v2.4.3

Mastodon.account_unmute(id)

Unmute a user.

Returns a relationship dict containing the updated relationship to the user.

Added: Mastodon v1.1.0, last changed: Mastodon v1.4.0

Mastodon.account_block(id)

Block a user.

Returns a relationship dict containing the updated relationship to the user.

Added: Mastodon v1.0.0, last changed: Mastodon v1.4.0

Mastodon.account_unblock(id)

Unblock a user.

Returns a relationship dict containing the updated relationship to the user.

Added: Mastodon v1.0.0, last changed: Mastodon v1.4.0

Mastodon.account_remove_from_followers(id)

Remove a user from the logged in users followers (i.e. make them unfollow the logged in user / “softblock” them).

Returns a relationship dict reflecting the updated following status.

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

Mastodon.domain_block(domain=None)

Add a block for all statuses originating from the specified domain for the logged-in user.

Added: Mastodon v1.4.0, last changed: Mastodon v1.4.0

Mastodon.domain_unblock(domain=None)

Remove a domain block for the logged-in user.

Added: Mastodon v1.4.0, last changed: Mastodon v1.4.0

Mastodon.lists()

Fetch a list of all the Lists by the logged-in user.

Returns a list of list dicts.

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

Mastodon.list(id)

Fetch info about a specific list.

Returns a list dict.

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

Mastodon.list_accounts(id, max_id=None, min_id=None, since_id=None, limit=None)

Get the accounts that are on the given list.

Returns a list of account dicts.

Added: Mastodon v2.1.0, last changed: Mastodon v2.6.0

Mastodon.list_create(title)

Create a new list with the given title.

Returns the list dict of the created list.

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

Mastodon.list_update(id, title)

Update info about a list, where “info” is really the lists title.

Returns the list dict of the modified list.

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

Mastodon.list_delete(id)

Delete a list.

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

Mastodon.list_accounts_add(id, account_ids)

Add the account(s) given in account_ids to the list.

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

Mastodon.list_accounts_delete(id, account_ids)

Remove the account(s) given in account_ids from the list.

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

Mastodon.timeline(timeline='home', max_id=None, min_id=None, since_id=None, limit=None, only_media=False, local=False, remote=False)

Fetch statuses, most recent ones first. timeline can be ‘home’, ‘local’, ‘public’, ‘tag/hashtag’ or ‘list/id’. See the following functions documentation for what those do.

The default timeline is the “home” timeline.

Specify only_media to only get posts with attached media. Specify local to only get local statuses, and remote to only get remote statuses. Some options are mutually incompatible as dictated by logic.

May or may not require authentication depending on server settings and what is specifically requested.

Returns a list of status dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v3.1.4

Mastodon.timeline_home(max_id=None, min_id=None, since_id=None, limit=None, only_media=False, local=False, remote=False)

Convenience method: Fetches the logged-in user’s home timeline (i.e. followed users and self). Params as in timeline().

Returns a list of status dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v3.1.4

Mastodon.timeline_local(max_id=None, min_id=None, since_id=None, limit=None, only_media=False)

Convenience method: Fetches the local / instance-wide timeline, not including replies. Params as in timeline().

Returns a list of status dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v3.1.4

Mastodon.timeline_public(max_id=None, min_id=None, since_id=None, limit=None, only_media=False, local=False, remote=False)

Convenience method: Fetches the public / visible-network / federated timeline, not including replies. Params as in timeline().

Returns a list of status dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v3.1.4

Mastodon.timeline_hashtag(hashtag, local=False, max_id=None, min_id=None, since_id=None, limit=None, only_media=False, remote=False)

Convenience method: Fetch a timeline of toots with a given hashtag. The hashtag parameter should not contain the leading #. Params as in timeline().

Returns a list of status dicts.

Added: Mastodon v1.0.0, last changed: Mastodon v3.1.4

Mastodon.timeline_list(id, max_id=None, min_id=None, since_id=None, limit=None, only_media=False, local=False, remote=False)

Convenience method: Fetches a timeline containing all the toots by users in a given list. Params as in timeline().

Returns a list of status dicts.

Added: Mastodon v2.1.0, last changed: Mastodon v3.1.4

Mastodon.instance()

Retrieve basic information about the instance, including the URI and administrative contact email.

Does not require authentication unless locked down by the administrator.

Returns an instance dict.

Added: Mastodon v1.1.0, last changed: Mastodon v2.3.0

Mastodon.instance_activity()

Retrieve activity stats about the instance. May be disabled by the instance administrator - throws a MastodonNotFoundError in that case.

Activity is returned for 12 weeks going back from the current week.

Returns a list of activity dicts.

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

Mastodon.instance_peers()

Retrieve the instances that this instance knows about. May be disabled by the instance administrator - throws a MastodonNotFoundError in that case.

Returns a list of URL strings.

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

Mastodon.instance_health()

Basic health check. Returns True if healthy, False if not.

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

Mastodon.instance_nodeinfo(schema='http://nodeinfo.diaspora.software/ns/schema/2.0')

Retrieves the instance’s nodeinfo information.

For information on what the nodeinfo can contain, see the nodeinfo specification: https://github.com/jhass/nodeinfo . By default, Mastodon.py will try to retrieve the version 2.0 schema nodeinfo.

To override the schema, specify the desired schema with the schema parameter.

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

Mastodon.instance_rules()

Retrieve instance rules.

Returns a list of id + text dicts, same as the rules field in the instance dicts.

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

Mastodon.directory(offset=None, limit=None, order=None, local=None)

Fetch the contents of the profile directory, if enabled on the server.

offset how many accounts to skip before returning results. Default 0.

limit how many accounts to load. Default 40.

order “active” to sort by most recently posted statuses (default) or

“new” to sort by most recently created profiles.

local True to return only local accounts.

Returns a list of account dicts.

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

Mastodon.custom_emojis()

Fetch the list of custom emoji the instance has installed.

Does not require authentication unless locked down by the administrator.

Returns a list of emoji dicts.

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

Mastodon.announcements()

Fetch currently active announcements.

Returns a list of announcement dicts.

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

Mastodon.announcement_dismiss(id)

Set the given annoucement to read.

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

Mastodon.announcement_reaction_create(id, reaction)

Add a reaction to an announcement. reaction can either be a unicode emoji or the name of one of the instances custom emoji.

Will throw an API error if the reaction name is not one of the allowed things or when trying to add a reaction that the user has already added (adding a reaction that a different user added is legal and increments the count).

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

Mastodon.announcement_reaction_delete(id, reaction)

Remove a reaction to an announcement.

Will throw an API error if the reaction does not exist.

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

Mastodon.trending_tags(limit=None, lang=None)

Fetch trending-hashtag information, if the instance provides such information.

Specify limit to limit how many results are returned (the maximum number of results is 10, the endpoint is not paginated).

Does not require authentication unless locked down by the administrator.

Important versioning note: This endpoint does not exist for Mastodon versions between 2.8.0 (inclusive) and 3.0.0 (exclusive).

Pass lang to override the global locale parameter, which may affect trend ordering.

Returns a list of hashtag dicts, sorted by the instance’s trending algorithm, descending.

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

Mastodon.trending_statuses()

Fetch trending-status information, if the instance provides such information.

Specify limit to limit how many results are returned (the maximum number of results is 10, the endpoint is not paginated).

Pass lang to override the global locale parameter, which may affect trend ordering.

Returns a list of status dicts, sorted by the instances’s trending algorithm, descending.

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

Mastodon.trending_links()

Fetch trending-link information, if the instance provides such information.

Specify limit to limit how many results are returned (the maximum number of results is 10, the endpoint is not paginated).

Returns a list of card dicts, sorted by the instances’s trending algorithm, descending.

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

Mastodon.trends(limit=None)

Alias for trending_tags()

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

Mastodon.search(q, resolve=True, result_type=None, account_id=None, offset=None, min_id=None, max_id=None, exclude_unreviewed=True)

Fetch matching hashtags, accounts and statuses. Will perform webfinger lookups if resolve is True. Full-text search is only enabled if the instance supports it, and is restricted to statuses the logged-in user wrote or was mentioned in.

result_type can be one of “accounts”, “hashtags” or “statuses”, to only search for that type of object.

Specify account_id to only get results from the account with that id.

offset, min_id and max_id can be used to paginate.

exclude_unreviewed can be used to restrict search results for hashtags to only those that have been reviewed by moderators. It is on by default. When using the v1 search API (pre 2.4.1), it is ignored.

Will use search_v1 (no tag dicts in return values) on Mastodon versions before 2.4.1), search_v2 otherwise. Parameters other than resolve are only available on Mastodon 2.8.0 or above - this function will throw a MastodonVersionError if you try to use them on versions before that. Note that the cached version number will be used for this to avoid uneccesary requests.

Returns a search result dict, with tags as `hashtag dicts`_.

Added: Mastodon v1.1.0, last changed: Mastodon v2.8.0

Mastodon.search_v2(q, resolve=True, result_type=None, account_id=None, offset=None, min_id=None, max_id=None, exclude_unreviewed=True)

Identical to search_v1(), except in that it returns tags as hashtag dicts, has more parameters, and resolves by default.

For more details documentation, please see search()

Returns a search result dict.

Added: Mastodon v2.4.1, last changed: Mastodon v2.8.0

Mastodon.notifications(id=None, account_id=None, max_id=None, min_id=None, since_id=None, limit=None, exclude_types=None, types=None, mentions_only=None)

Fetch notifications (mentions, favourites, reblogs, follows) for the logged-in user. Pass account_id to get only notifications originating from the given account.

There are different types of notifications:

• follow - A user followed the logged in user
• follow_request - A user has requested to follow the logged in user (for locked accounts)
• favourite - A user favourited a post by the logged in user
• reblog - A user reblogged a post by the logged in user
• mention - A user mentioned the logged in user
• poll - A poll the logged in user created or voted in has ended
• update - A status the logged in user has reblogged (and only those, as of 4.0.0) has been edited
• status - A user that the logged in user has enabned notifications for has enabled notify (see account_follow())
• admin.sign_up - For accounts with appropriate permissions (TODO: document which those are when adding the permission API): A new user has signed up
• admin.report - For accounts with appropriate permissions (TODO: document which those are when adding the permission API): A new report has been received

Parameters exclude_types and types are array of these types, specifying them will in- or exclude the types of notifications given. It is legal to give both parameters at the same tine, the result will then be the intersection of the results of both filters. Specifying mentions_only is a deprecated way to set exclude_types to all but mentions.

Can be passed an id to fetch a single notification.

Returns a list of notification dicts.

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

Mastodon.notifications_clear()

Clear out a user’s notifications

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

Mastodon.notifications_dismiss(id)

Deletes a single notification

Added: Mastodon v1.3.0, last changed: Mastodon v2.9.2

Mastodon.conversations_read(id)

Marks a single conversation as read.

Returns the updated conversation dict.

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

Mastodon.filters()

Fetch all of the logged-in user’s filters.

Returns a list of filter dicts. Not paginated.

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

Mastodon.filter(id)

Fetches information about the filter with the specified id.

Returns a filter dict.

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

Mastodon.filters_apply(objects, filters, context)

Helper function: Applies a list of filters to a list of either statuses or notifications and returns only those matched by none. This function will apply all filters that match the context provided in context, i.e. if you want to apply only notification-relevant filters, specify ‘notifications’. Valid contexts are ‘home’, ‘notifications’, ‘public’ and ‘thread’.

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

Mastodon.filter_create(phrase, context, irreversible=False, whole_word=True, expires_in=None)

Creates a new keyword filter. phrase is the phrase that should be filtered out, context specifies from where to filter the keywords. Valid contexts are ‘home’, ‘notifications’, ‘public’ and ‘thread’.

Set irreversible to True if you want the filter to just delete statuses server side. This works only for the ‘home’ and ‘notifications’ contexts.

Set whole_word to False if you want to allow filter matches to start or end within a word, not only at word boundaries.

Set expires_in to specify for how many seconds the filter should be kept around.

Returns the filter dict of the newly created filter.

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

Mastodon.filter_update(id, phrase=None, context=None, irreversible=None, whole_word=None, expires_in=None)

Updates the filter with the given id. Parameters are the same as in filter_create().

Returns the filter dict of the updated filter.

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

Mastodon.filter_delete(id)

Deletes the filter with the given id.

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

Mastodon.push_subscription()

Fetch the current push subscription the logged-in user has for this app.

Returns a push subscription dict.

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

Mastodon.push_subscription_set(endpoint, encrypt_params, follow_events=None, favourite_events=None, reblog_events=None, mention_events=None, poll_events=None, follow_request_events=None, status_events=None, policy='all')

Sets up or modifies the push subscription the logged-in user has for this app.

endpoint is the endpoint URL mastodon should call for pushes. Note that mastodon requires https for this URL. encrypt_params is a dict with key parameters that allow the server to encrypt data for you: A public key pubkey and a shared secret auth. You can generate this as well as the corresponding private key using the push_subscription_generate_keys() function.

policy controls what sources will generate webpush events. Valid values are all, none, follower and followed.

The rest of the parameters controls what kind of events you wish to subscribe to.

Returns a push subscription dict.

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

Mastodon.push_subscription_update(follow_events=None, favourite_events=None, reblog_events=None, mention_events=None, poll_events=None, follow_request_events=None)

Modifies what kind of events the app wishes to subscribe to.

Returns the updated push subscription dict.

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

Mastodon.push_subscription_generate_keys()

Generates a private key, public key and shared secret for use in webpush subscriptions.

Returns two dicts: One with the private key and shared secret and another with the public key and shared secret.

Mastodon.push_subscription_decrypt_push(data, decrypt_params, encryption_header, crypto_key_header)

Decrypts data received in a webpush request. Requires the private key dict from push_subscription_generate_keys() (decrypt_params) as well as the Encryption and server Crypto-Key headers from the received webpush

Returns the decoded webpush as a push notification dict.

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

Mastodon.stream_user(listener, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)

Streams events that are relevant to the authorized user, i.e. home timeline and notifications.

Added: Mastodon v1.1.0, last changed: Mastodon v1.4.2

Mastodon.stream_public(listener, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)

Streams public events.

Added: Mastodon v1.1.0, last changed: Mastodon v1.4.2

Mastodon.stream_local(listener, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)

Streams local public events.

Added: Mastodon v1.1.0, last changed: Mastodon v1.4.2

Mastodon.stream_hashtag(tag, listener, local=False, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)

Stream for all public statuses for the hashtag ‘tag’ seen by the connected instance.

Set local to True to only get local statuses.

Added: Mastodon v1.1.0, last changed: Mastodon v1.4.2

Mastodon.stream_list(id, listener, run_async=False, timeout=300, reconnect_async=False, reconnect_async_wait_sec=5)

Stream events for the current user, restricted to accounts on the given list.

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

Mastodon.stream_healthy()

Returns without True if streaming API is okay, False or raises an error otherwise.

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

class mastodon.StreamListener

Callbacks for the streaming API. Create a subclass, override the on_xxx methods for the kinds of events you’re interested in, then pass an instance of your subclass to Mastodon.user_stream(), Mastodon.public_stream(), or Mastodon.hashtag_stream().

StreamListener.on_update(status)

A new status has appeared. status is the parsed status dict describing the status.

StreamListener.on_notification(notification)

A new notification. notification is the parsed notification dict describing the notification.

StreamListener.on_delete(status_id)

A status has been deleted. status_id is the status’ integer ID.

StreamListener.on_conversation(conversation)

A direct message (in the direct stream) has been received. conversation is the parsed conversation dict dictionary describing the conversation

StreamListener.on_status_update(status)

A status has been edited. ‘status’ is the parsed JSON dictionary describing the updated status.

StreamListener.on_unknown_event(name, unknown_event=None)

An unknown mastodon API event has been received. The name contains the event-name and unknown_event contains the content of the unknown event.

StreamListener.on_abort(err)

There was a connection error, read timeout or other error fatal to the streaming connection. The exception object about to be raised is passed to this function for reference.

Note that the exception will be raised properly once you return from this function, so if you are using this handler to reconnect, either never return or start a thread and then catch and ignore the exception.

StreamListener.handle_heartbeat()

The server has sent us a keep-alive message. This callback may be useful to carry out periodic housekeeping tasks, or just to confirm that the connection is still open.

Mastodon.markers_get(timeline=['home'])

Get the last-read-location markers for the specified timelines. Valid timelines are the same as in timeline()

Note that despite the singular name, timeline can be a list.

Returns a dict of read marker dicts, keyed by timeline name.

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

Mastodon.markers_set(timelines, last_read_ids)

Set the “last read” marker(s) for the given timeline(s) to the given id(s)

Note that if you give an invalid timeline name, this will silently do nothing.

Returns a dict with the updated read marker dicts, keyed by timeline name.

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

Mastodon.reports()

Fetch a list of reports made by the logged-in user.

Returns a list of report dicts.

Warning: This method has now finally been removed, and will not work on Mastodon versions 2.5.0 and above.

Added: Mastodon v1.1.0, last changed: Mastodon v1.1.0

Mastodon.fetch_next(previous_page)

Fetches the next page of results of a paginated request. Pass in the previous page in its entirety, or the pagination information dict returned as a part of that pages last status (‘_pagination_next’).

Returns the next page or None if no further data is available.

Mastodon.fetch_previous(next_page)

Fetches the previous page of results of a paginated request. Pass in the previous page in its entirety, or the pagination information dict returned as a part of that pages first status (‘_pagination_prev’).

Returns the previous page or None if no further data is available.

Mastodon.fetch_remaining(first_page)

Fetches all the remaining pages of a paginated request starting from a first page and returns the entire set of results (including the first page that was passed in) as a big list.

Be careful, as this might generate a lot of requests, depending on what you are fetching, and might cause you to run into rate limits very quickly.

Mastodon.decode_blurhash(media_dict, out_size=(16, 16), size_per_component=True, return_linear=True)

Basic media-dict blurhash decoding.

out_size is the desired result size in pixels, either absolute or per blurhash component (this is the default).

By default, this function will return the image as linear RGB, ready for further scaling operations. If you want to display the image directly, set return_linear to False.

Returns the decoded blurhash image as a three-dimensional list: [height][width][3], with the last dimension being RGB colours.

For further info and tips for advanced usage, refer to the documentation for the blurhash module: https://github.com/halcy/blurhash-python

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

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

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)

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)

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)

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)

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)

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

Mastodon.admin_trending_tags(limit=None)

Admin version of trending_tags(). Includes unapproved tags.

Returns a list of hashtag dicts, sorted by the instance’s trending algorithm, descending.

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

Mastodon.admin_trending_statuses()

Admin version of trending_statuses(). Includes unapproved tags.

Returns a list of status dicts, sorted by the instance’s trending algorithm, descending.

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

Mastodon.admin_trending_links()

Admin version of trending_links(). Includes unapproved tags.

Returns a list of card dicts, sorted by the instance’s trending algorithm, descending.

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

Mastodon.admin_domain_blocks(id=None, limit: int = None)

Fetches a list of blocked domains. Requires scope admin:read:domain_blocks.

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

Returns a list of admin domain block dicts, raises a MastodonAPIError if the specified block does not exist.

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

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)

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)

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)

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

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)

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)

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')

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