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() Account[source]
Fetch logged-in user’s account information. Returns the version of the Account object with source field.
Added: Mastodon v1.0.0, last changed: Mastodon v2.1.0 (parameters), Mastodon v4.2.0 (return value)
- Mastodon.me() Account[source]
Get this user’s account. Synonym for account_verify_credentials(), does exactly the same thing, just exists because account_verify_credentials() has a confusing name.
Added: Mastodon v1.0.0, last changed: Mastodon v2.1.0 (parameters), Mastodon v4.2.0 (return value)
- Mastodon.account(id: Account | str | int | MaybeSnowflakeIdType | datetime) Account[source]
Fetch account information by user id.
Does not require authentication for publicly visible accounts.
Added: Mastodon v1.0.0, last changed: Mastodon v1.0.0 (parameters), Mastodon v4.2.0 (return value)
- Mastodon.account_search(q: str, limit: int | None = None, following: bool = False, resolve: bool = False, offset: int | None = None) NonPaginatableList[Account][source]
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.
Paginated in a weird way (“limit” / “offset”), if you want to fetch all results here please do it yourself for now.
Added: Mastodon v1.0.0, last changed: Mastodon v2.8.0
- Mastodon.account_lookup(acct: str) Account[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.
Added: Mastodon v3.4.0, last changed: Mastodon v3.4.0 (parameters), Mastodon v4.2.0 (return value)
- Mastodon.accounts(ids: List[Account | str | int | MaybeSnowflakeIdType | datetime]) List[Account][source]
Fetch information from multiple accounts by a list of user id.
Does not require authentication for publicly visible accounts.
Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0
- Mastodon.featured_tags() NonPaginatableList[FeaturedTag][source]
Return the hashtags the logged-in user has set to be featured on their profile.
Added: Mastodon v3.0.0, last changed: Mastodon v3.0.0
- Mastodon.featured_tag_suggestions() NonPaginatableList[FeaturedTag][source]
Returns the logged-in user’s 10 most commonly-used hashtags.
Added: Mastodon v3.0.0, last changed: Mastodon v3.0.0
- Mastodon.account_featured_tags(id: Account | str | int | MaybeSnowflakeIdType | datetime) NonPaginatableList[Tag][source]
Get an account’s featured hashtags.
Added: Mastodon v3.3.0, last changed: Mastodon v3.3.0
- Mastodon.endorsements() NonPaginatableList[Account][source]
Fetch list of users endorsed by the logged-in user.
Added: Mastodon v2.5.0, last changed: Mastodon v2.5.0
- Mastodon.account_statuses(id: Account | str | int | MaybeSnowflakeIdType | datetime, only_media: bool = False, pinned: bool = False, exclude_replies: bool = False, exclude_reblogs: bool = False, tagged: str | None = None, max_id: Status | str | int | MaybeSnowflakeIdType | datetime | None = None, min_id: Status | str | int | MaybeSnowflakeIdType | datetime | None = None, since_id: Status | str | int | MaybeSnowflakeIdType | datetime | None = None, limit: int | None = None) PaginatableList[Status][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.
Added: Mastodon v1.0.0, last changed: Mastodon v2.8.0
- Mastodon.account_familiar_followers(id: List[Account | str | int | MaybeSnowflakeIdType | datetime] | Account | str | int | MaybeSnowflakeIdType | datetime) NonPaginatableList[FamiliarFollowers][source]
Find followers for the account given by id (can be a list) that also follow the logged in account.
Added: Mastodon v3.5.0, last changed: Mastodon v3.5.0
- Mastodon.account_lists(id: Account | str | int | MaybeSnowflakeIdType | datetime) NonPaginatableList[UserList][source]
Get all of the logged-in user’s lists which the specified user is a member of.
Added: Mastodon v2.1.0, last changed: Mastodon v2.1.0
Writing
- Mastodon.account_update_credentials(display_name: str | None = None, note: str | None = None, avatar: str | PurePath | IO[bytes] | None = None, avatar_mime_type: str | None = None, header: str | PurePath | IO[bytes] | None = None, header_mime_type: str | None = None, locked: bool | None = None, bot: bool | None = None, discoverable: bool | None = None, fields: List[Tuple[str, str]] | None = None, attribution_domains: List[str] | None = None) Account[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.
attribution_domains can be a list of domains that the user wants to allow to attribute content to them.
The returned object reflects the updated account.
Added: Mastodon v1.1.1, last changed: Mastodon v3.1.0 (parameters), Mastodon v4.2.0 (return value)
- Mastodon.account_endorse(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Endorse a user.
The returned object reflects the updated relationship with the user.
Added: Mastodon v4.4.0, last changed: Mastodon v4.4.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.account_unendorse(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Unendorse a user.
The returned object reflects the updated relationship with the user.
Added: Mastodon v4.4.0, last changed: Mastodon v4.4.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.account_note_set(id: Account | str | int | MaybeSnowflakeIdType | datetime, comment: str) Relationship[source]
Set a note (visible to the logged in user only) for the given account.
The returned object contains the updated note.
nb: To retrieve the current note for an account, use account_relationships.
Added: Mastodon v3.2.0, last changed: Mastodon v3.2.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.tag_feature(name: str) Tag[source]
Creates a new featured hashtag displayed on the logged-in user’s profile.
Same effect as above, but newer. Likely obsoletes featured_tag_create.
Added: Mastodon v4.4.0, last changed: Mastodon v4.4.0 (parameters), Mastodon v4.4.0 (return value)
- Mastodon.tag_unfeature(name: str) Tag[source]
Deletes one of the logged-in user’s featured hashtags.
Same effect as above, but newer. Likely obsoletes featured_tag_delete.
Added: Mastodon v4.4.0, last changed: Mastodon v4.4.0 (parameters), Mastodon v4.4.0 (return value)
- Mastodon.status_pin(id: Status | str | int | MaybeSnowflakeIdType | datetime) Status[source]
Pin a status for the logged-in user.
Returns the now pinned status
Added: Mastodon v2.1.0, last changed: Mastodon v2.1.0 (parameters), Mastodon v4.4.0 (return value)
- Mastodon.status_unpin(id: Status | str | int | MaybeSnowflakeIdType | datetime) Status[source]
Unpin a pinned status for the logged-in user.
Returns the status that used to be pinned.
Added: Mastodon v2.1.0, last changed: Mastodon v2.1.0 (parameters), Mastodon v4.4.0 (return value)
Deprecated
- Mastodon.account_pin(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Pin / endorse a user.
The returned object reflects the updated relationship with the user.
Deprecated, use account_endorse instead.
Added: Mastodon v2.5.0, last changed: Mastodon v2.5.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.account_unpin(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Unpin / un-endorse a user.
The returned object reflects the updated relationship with the user.
Deprecated, use account_unendorse instead.
Added: Mastodon v2.5.0, last changed: Mastodon v2.5.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.featured_tag_create(name: str) FeaturedTag[source]
Creates a new featured hashtag displayed on the logged-in user’s profile.
The returned object is the newly featured tag.
Obsoleted by tag_feature / tag_unfeature.
Added: Mastodon v3.0.0, last changed: Mastodon v3.0.0 (parameters), Mastodon v3.3.0 (return value)
- Mastodon.featured_tag_delete(id: FeaturedTag | str | int | MaybeSnowflakeIdType | datetime)[source]
Deletes one of the logged-in user’s featured hashtags.
Obsoleted by tag_feature / tag_unfeature.
Added: Mastodon v3.0.0, last changed: Mastodon v3.0.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: Account | str | int | MaybeSnowflakeIdType | datetime, max_id: Account | str | int | MaybeSnowflakeIdType | datetime | None = None, min_id: Account | str | int | MaybeSnowflakeIdType | datetime | None = None, since_id: Account | str | int | MaybeSnowflakeIdType | datetime | None = None, limit: int | None = None) PaginatableList[Account][source]
Fetch users the given user is followed by.
Added: Mastodon v1.0.0, last changed: Mastodon v2.6.0
- Mastodon.account_following(id: Account | str | int | MaybeSnowflakeIdType | datetime, max_id: Account | str | int | MaybeSnowflakeIdType | datetime | None = None, min_id: Account | str | int | MaybeSnowflakeIdType | datetime | None = None, since_id: Account | str | int | MaybeSnowflakeIdType | datetime | None = None, limit: int | None = None) PaginatableList[Account][source]
Fetch users the given user is following.
Added: Mastodon v1.0.0, last changed: Mastodon v2.6.0
- Mastodon.account_relationships(id: List[Account | str | int | MaybeSnowflakeIdType | datetime] | Account | str | int | MaybeSnowflakeIdType | datetime, with_suspended: bool | None = None) NonPaginatableList[Relationship][source]
Fetch relationship (following, followed_by, blocking, follow requested) of the logged in user to a given account. id can be a list.
Pass with_suspended = True to include relationships with suspended accounts.
Added: Mastodon v1.0.0, last changed: Mastodon v1.4.0
- Mastodon.follows(uri: str) Relationship[source]
Follow a remote user with username given in username@domain form.
Deprecated - avoid using this. Currently uses a backwards compat implementation that may or may not work properly.
Added: Mastodon v1.0.0, last changed: Mastodon v2.1.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.follow_requests(max_id: str | int | MaybeSnowflakeIdType | datetime | None = None, min_id: str | int | MaybeSnowflakeIdType | datetime | None = None, since_id: str | int | MaybeSnowflakeIdType | datetime | None = None, limit: int | None = None) PaginatableList[Account][source]
Fetch the logged-in user’s incoming follow requests.
Added: Mastodon v1.0.0, last changed: Mastodon v2.6.0
- Mastodon.suggestions() NonPaginatableList[Suggestion] | NonPaginatableList[Account][source]
Fetch follow suggestions for the logged-in user.
Will use the v1 endpoint if the server is below 3.4.0, otherwise will use the v2 endpoint and unpack the account dicts.
Writing
- Mastodon.account_follow(id: Account | str | int | MaybeSnowflakeIdType | datetime, reblogs: bool = True, notify: bool = False) Relationship[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.
The returned object reflects the updated relationship with the user.
Added: Mastodon v1.0.0, last changed: Mastodon v3.3.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.account_unfollow(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Unfollow a user.
The returned object reflects the updated relationship with the user.
Added: Mastodon v1.0.0, last changed: Mastodon v1.4.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.follow_request_authorize(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Accept an incoming follow request from the given Account and returns the updated Relationship.
Added: Mastodon v1.0.0, last changed: Mastodon v3.0.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.follow_request_reject(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Reject an incoming follow request from the given Account and returns the updated Relationship.
Added: Mastodon v1.0.0, last changed: Mastodon v3.0.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.suggestion_delete(account_id: Account | str | int | MaybeSnowflakeIdType | datetime)[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: str | int | MaybeSnowflakeIdType | datetime | None = None, min_id: str | int | MaybeSnowflakeIdType | datetime | None = None, since_id: str | int | MaybeSnowflakeIdType | datetime | None = None, limit: int | None = None) PaginatableList[Account][source]
Fetch a list of users muted by the logged-in user.
Added: Mastodon v1.1.0, last changed: Mastodon v2.6.0
- Mastodon.blocks(max_id: str | int | MaybeSnowflakeIdType | datetime | None = None, min_id: str | int | MaybeSnowflakeIdType | datetime | None = None, since_id: str | int | MaybeSnowflakeIdType | datetime | None = None, limit: int | None = None) PaginatableList[Account][source]
Fetch a list of users blocked by the logged-in user.
Added: Mastodon v1.0.0, last changed: Mastodon v2.6.0
- Mastodon.domain_blocks(max_id: str | int | MaybeSnowflakeIdType | datetime | None = None, min_id: str | int | MaybeSnowflakeIdType | datetime | None = None, since_id: str | int | MaybeSnowflakeIdType | datetime | None = None, limit: int | None = None) PaginatableList[str][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: Account | str | int | MaybeSnowflakeIdType | datetime, notifications: bool = True, duration: int | None = None) Relationship[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.
The returned object reflects the updated relationship with the user.
Added: Mastodon v1.1.0, last changed: Mastodon v2.4.3 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.account_unmute(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Unmute a user.
The returned object reflects the updated relationship with the user.
Added: Mastodon v1.1.0, last changed: Mastodon v1.4.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.account_block(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Block a user.
The returned object reflects the updated relationship with the user.
Added: Mastodon v1.0.0, last changed: Mastodon v1.4.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.account_unblock(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Unblock a user.
The returned object reflects the updated relationship with the user.
Added: Mastodon v1.0.0, last changed: Mastodon v1.4.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.account_remove_from_followers(id: Account | str | int | MaybeSnowflakeIdType | datetime) Relationship[source]
Remove a user from the logged in users followers (i.e. make them unfollow the logged in user / “softblock” them).
The returned object reflects the updated relationship with the user.
Added: Mastodon v3.5.0, last changed: Mastodon v3.5.0 (parameters), Mastodon v4.0.0 (return value)
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() NonPaginatableList[UserList][source]
Fetch a list of all the Lists by the logged-in user.
Added: Mastodon v2.1.0, last changed: Mastodon v2.1.0
- Mastodon.list(id: UserList | str | int | MaybeSnowflakeIdType | datetime) UserList[source]
Fetch info about a specific list.
Added: Mastodon v2.1.0, last changed: Mastodon v2.1.0 (parameters), Mastodon v4.2.0 (return value)
- Mastodon.list_accounts(id: UserList | str | int | MaybeSnowflakeIdType | datetime, max_id: UserList | str | int | MaybeSnowflakeIdType | datetime | None = None, min_id: UserList | str | int | MaybeSnowflakeIdType | datetime | None = None, since_id: UserList | str | int | MaybeSnowflakeIdType | datetime | None = None, limit: int | None = None) PaginatableList[Account][source]
Get the accounts that are on the given list.
Added: Mastodon v2.1.0, last changed: Mastodon v2.6.0
Writing
- Mastodon.list_create(title: str, replies_policy: str = 'list', exclusive: bool = False) UserList[source]
Create a new list with the given title.
replies_policy controls which replies are shown in the list. It can be one of “followed”, “list” or “none”. followed means that only replies from accounts you follow will be shown, list means that only replies from accounts on the list will be shown, and none means that no replies will be shown.
Set exclusive to True if you want the list to be an exclusive list, meaning that accounts on the list will be excluded from the home timeline, appearing exclusively in the list timeline.
Added: Mastodon v2.1.0, last changed: Mastodon v4.2.0 (parameters), Mastodon v4.2.0 (return value)
- Mastodon.list_update(id: UserList | str | int | MaybeSnowflakeIdType | datetime, title: str, replies_policy: str = 'list', exclusive: bool = False) UserList[source]
Update info about a list, where “info” is really the lists title.
replies_policy controls which replies are shown in the list. It can be one of “followed”, “list” or “none”. followed means that only replies from accounts you follow will be shown, list means that only replies from accounts on the list will be shown, and none means that no replies will be shown.
Set exclusive to True if you want the list to be an exclusive list, meaning that accounts on the list will be excluded from the home timeline, appearing exclusively in the list timeline.
The returned object reflects the updated list.
Added: Mastodon v2.1.0, last changed: Mastodon v4.2.0 (parameters), Mastodon v4.2.0 (return value)
- Mastodon.list_delete(id: UserList | str | int | MaybeSnowflakeIdType | datetime)[source]
Delete a list.
Added: Mastodon v2.1.0, last changed: Mastodon v2.1.0
- Mastodon.list_accounts_add(id: UserList | str | int | MaybeSnowflakeIdType | datetime, account_ids: List[Account | str | int | MaybeSnowflakeIdType | datetime])[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: UserList | str | int | MaybeSnowflakeIdType | datetime, account_ids: List[Account | str | int | MaybeSnowflakeIdType | datetime])[source]
Remove the account(s) given in account_ids from the list.
Added: Mastodon v2.1.0, last changed: Mastodon v2.1.0