Accounts, relationships and lists

Accounts

These functions allow you to get information about accounts and associated data as well as update that data - profile data (incuding pinned statuses and endorsements) for the logged in users account, and notes for everyone else

Reading

Mastodon.account_verify_credentials()[source]

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()[source]

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)[source]

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

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)[source]

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()[source]

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()[source]

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

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

Writing

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

Following and followers

These functions allow you to get information about the logged in users followers and users that the logged in users follows as well as follow requests and follow suggestions, and to manage that data - most importantly, follow and unfollow users.

Reading

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

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)[source]

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)[source]

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)[source]

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()[source]

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

Writing

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

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)[source]

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)[source]

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)[source]

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)[source]

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

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

Mutes and blocks

These functions allow you to get information about accounts and domains that are muted or blocked by the logged in user, and to block and mute users and domains

Reading

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

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)[source]

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)[source]

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

Writing

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

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Remove a domain block for the logged-in user.

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

Lists

These functions allow you to view information about lists as well as to create and update them. By default, the maximum number of lists for a user is 50.

Reading

Mastodon.lists()[source]

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)[source]

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)[source]

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

Writing

Mastodon.list_create(title)[source]

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)[source]

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)[source]

Delete a list.

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

Mastodon.list_accounts_add(id, account_ids)[source]

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)[source]

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

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