Instance-wide data and search
Instance information
These functions allow you to fetch information associated with the current instance as well as data from the instance-wide profile directory.
- Mastodon.instance() Instance | InstanceV2[source]
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 v4.0.0
- Mastodon.instance_activity() NonPaginatableList[Activity][source]
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.
Added: Mastodon v2.1.2, last changed: Mastodon v2.1.2
- Mastodon.instance_peers() NonPaginatableList[str][source]
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() bool[source]
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: str = 'http://nodeinfo.diaspora.software/ns/schema/2.0') Nodeinfo | AttribAccessDict[source]
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, for which we have a well defined return object. If you go outside of that, all bets are off.
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() NonPaginatableList[Rule][source]
Retrieve instance rules.
Added: Mastodon v3.4.0, last changed: Mastodon v3.4.0
Profile directory
- Mastodon.directory(offset: int | None = None, limit: int | None = None, order: str | None = None, local: bool | None = None) NonPaginatableList[Account][source]
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 (usually the default) or
“new” to sort by most recently created profiles.
local True to return only local accounts.
Uses offset/limit pagination, not currently handled by the pagination utility functions, do it manually if you have to.
Added: Mastodon v3.0.0, last changed: Mastodon v3.0.0
Emoji
Announcements
These functions allow you to fetch announcements, mark annoucements read and modify reactions.
Reading
Writing
- Mastodon.announcement_dismiss(id: Announcement | str | int | MaybeSnowflakeIdType)[source]
Set the given annoucement to read.
Added: Mastodon v3.1.0, last changed: Mastodon v3.1.0
- Mastodon.announcement_reaction_create(id: Announcement | str | int | MaybeSnowflakeIdType, reaction: str)[source]
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
Trends
These functions, when enabled, allow you to fetch trending tags, statuses and links.
- Mastodon.trending_tags(limit: int | None = None, lang: str | None = None) NonPaginatableList[Tag][source]
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.
The results are sorted by the instances’s trending algorithm, descending.
Added: Mastodon v3.5.0, last changed: Mastodon v3.5.0
- Mastodon.trending_statuses(limit: int | None = None, offset: int | None = None, lang: str | None = None) NonPaginatableList[Status][source]
Fetch trending-status information, if the instance provides such information.
Specify limit to limit how many results are returned (default 20, the maximum number of results is 40).
Specify offset to paginate results. Default 0.
Pass lang to override the global locale parameter, which may affect trend ordering.
The results are sorted by the instances’s trending algorithm, descending.
Added: Mastodon v3.5.0, last changed: Mastodon v3.5.0
- Mastodon.trending_links(limit: int | None = None, lang: str | None = None) NonPaginatableList[PreviewCard][source]
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).
The results are sorted by the instances’s trending algorithm, descending.
Added: Mastodon v3.5.0, last changed: Mastodon v3.5.0
- Mastodon.trends(limit: int | None = None)[source]
Old alias for trending_tags()
Deprecated. Please use trending_tags() instead.
Added: Mastodon v2.4.3, last changed: Mastodon v3.5.0
Search
These functions allow you to search for users, tags and, when enabled, full text, by default within your own posts and those you have interacted with.
- Mastodon.search(q: str, resolve: bool = True, result_type: str | None = None, account_id: Account | str | int | MaybeSnowflakeIdType | None = None, offset: int | None = None, min_id: str | int | MaybeSnowflakeIdType | None = None, max_id: str | int | MaybeSnowflakeIdType | None = None, exclude_unreviewed: bool = True) Search | SearchV2[source]
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.
Added: Mastodon v1.1.0, last changed: Mastodon v2.8.0
- Mastodon.search_v2(q, resolve: bool = True, result_type: str | None = None, account_id: Account | str | int | MaybeSnowflakeIdType | None = None, offset: int | None = None, min_id: str | int | MaybeSnowflakeIdType | None = None, max_id: str | int | MaybeSnowflakeIdType | None = None, exclude_unreviewed: bool = True) SearchV2[source]
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