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() InstanceV2 | Instance[source]
Retrieve basic information about the instance, including the URI and administrative contact email.
Does not require authentication unless locked down by the administrator.
Will return the latest available version of the instance information. If you want a specific one, call the _v1 or _v2 variants
Added: Mastodon v1.1.0, last changed: Mastodon v4.0.0
- Mastodon.instance_v1() Instance[source]
Retrieve basic information about the instance, including the URI and administrative contact email.
Does not require authentication unless locked down by the administrator.
This is the explicit v1 version of this function. The v2 version is available through instance_v2(). It contains a bit more information than this one, but does not include whether invites are enabled.
Added: Mastodon v1.1.0, last changed: Mastodon v2.3.0 (parameters), Mastodon v4.0.0 (return value)
- Mastodon.instance_v2() 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. This is the explicit v2 variant.
Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0 (parameters), Mastodon v4.3.0 (return value)
- 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[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 (parameters), Mastodon v3.0.0 (return value)
- Mastodon.instance_rules() NonPaginatableList[Rule][source]
Retrieve instance rules.
Added: Mastodon v3.4.0, last changed: Mastodon v3.4.0
- Mastodon.instance_extended_description() ExtendedDescription[source]
Retrieve the instance’s extended description.
Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0 (parameters), Mastodon v4.0.0 (return value)
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
- Mastodon.custom_emojis() NonPaginatableList[CustomEmoji][source]
Fetch the list of custom emoji the instance has installed.
Does not require authentication unless locked down by the administrator.
Added: Mastodon v2.1.0, last changed: Mastodon v2.1.0
Announcements
These functions allow you to fetch announcements, mark annoucements read and modify reactions.
Reading
- Mastodon.announcements() NonPaginatableList[Announcement][source]
Fetch currently active announcements.
Added: Mastodon v3.1.0, last changed: Mastodon v3.1.0
Writing
- Mastodon.announcement_dismiss(id: Announcement | str | int | MaybeSnowflakeIdType | datetime)[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 | datetime, 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
- Mastodon.announcement_reaction_delete(id: Announcement | str | int | MaybeSnowflakeIdType | datetime, reaction: str)[source]
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
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 | datetime | None = None, offset: int | None = None, min_id: str | int | MaybeSnowflakeIdType | datetime | None = None, max_id: str | int | MaybeSnowflakeIdType | datetime | 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 tags 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 | datetime | None = None, offset: int | None = None, min_id: str | int | MaybeSnowflakeIdType | datetime | None = None, max_id: str | int | MaybeSnowflakeIdType | datetime | None = None, exclude_unreviewed: bool = True) SearchV2[source]
Identical to search_v1(), except in that it returns tags as objects, has more parameters, and resolves by default.
For more details documentation, please see search()
Added: Mastodon v2.4.1, last changed: Mastodon v2.8.0 (parameters), Mastodon v2.4.1 (return value)
Domain blocks
- Mastodon.instance_domain_blocks() NonPaginatableList[DomainBlock][source]
Fetch a list of domains that have been blocked by the instance. Public endpoint, requires authentication if limited to users.
Returns a MastodonAPIError if the admin has chosen to not make the list public, or to now show it at all.
Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0
Translation support
- Mastodon.instance_languages() NonPaginatableList[SupportedLocale][source]
Fetch a list of languages that the instance supports.
Added: Mastodon v4.2.0, last changed: Mastodon v4.2.0