Statuses, media and polls

Statuses

These functions allow you to get information about single statuses and to post and update them, as well as to favourite, bookmark, mute reblog (“boost”) and to undo all of those. For status pinning, check out TODO and TODO on the accounts page.

Reading

Mastodon.status(id: Status | str | int | MaybeSnowflakeIdType) Status[source]

Fetch information about a single toot.

Does not require authentication for publicly visible statuses.

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

Mastodon.status_context(id: Status | str | int | MaybeSnowflakeIdType) Context[source]

Fetch information about ancestors and descendants of a toot.

Does not require authentication for publicly visible statuses.

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

Mastodon.status_reblogged_by(id: Status | str | int | MaybeSnowflakeIdType) NonPaginatableList[Account][source]

Fetch a list of users that have reblogged a status.

Does not require authentication for publicly visible statuses.

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

Mastodon.status_favourited_by(id: Status | str | int | MaybeSnowflakeIdType) NonPaginatableList[Account][source]

Fetch a list of users that have favourited a status.

Does not require authentication for publicly visible statuses.

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

Mastodon.status_card(id: Status | str | int | MaybeSnowflakeIdType) PreviewCard[source]

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.

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

Mastodon.status_history(id: StatusEdit | str | int | MaybeSnowflakeIdType) NonPaginatableList[StatusEdit][source]

Returns the edit history of a status as a list of StatusEdit objects, 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: Status | str | int | MaybeSnowflakeIdType) StatusSource[source]

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: str | int | MaybeSnowflakeIdType | None = None, min_id: str | int | MaybeSnowflakeIdType | None = None, since_id: str | int | MaybeSnowflakeIdType | None = None, limit: int | None = None) PaginatableList[Status][source]

Fetch the logged-in user’s favourited statuses.

This endpoint uses internal ids for pagination, passing status ids to max_id, min_id, or since_id will not work.

Returns a list of status dicts.

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

Mastodon.bookmarks(max_id: str | int | MaybeSnowflakeIdType | None = None, min_id: str | int | MaybeSnowflakeIdType | None = None, since_id: str | int | MaybeSnowflakeIdType | None = None, limit: int | None = None) PaginatableList[Status][source]

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

This endpoint uses internal ids for pagination, passing status ids to max_id, min_id, or since_id will not work.

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

Writing

Mastodon.status_post(status: str, in_reply_to_id: Status | str | int | MaybeSnowflakeIdType | None = None, media_ids: List[MediaAttachment | str | int | MaybeSnowflakeIdType] | None = None, sensitive: bool = False, visibility: str | None = None, spoiler_text: str | None = None, language: str | None = None, idempotency_key: str | None = None, content_type: str | None = None, scheduled_at: datetime | None = None, poll: Poll | str | int | MaybeSnowflakeIdType | None = None, quote_id: Status | str | int | MaybeSnowflakeIdType | None = None) Status | ScheduledStatus[source]

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, known in Mastodon’s UI as “Mentioned users only”

  • 'private' - post will be visible only to followers, known in Mastodon’s UI as “Followers only”

  • 'unlisted' - post will be public but will not appear on the public timelines

  • 'public' - post will be public and will appear on public timelines

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 | str | int | MaybeSnowflakeIdType, status: str, media_ids: List[MediaAttachment | str | int | MaybeSnowflakeIdType] | None = None, sensitive: bool = False, visibility: str | None = None, spoiler_text: str | None = None, language: str | None = None, idempotency_key: str | None = None, content_type: str | None = None, scheduled_at: datetime | None = None, poll: Poll | str | int | MaybeSnowflakeIdType | None = None, quote_id: Status | str | int | MaybeSnowflakeIdType | None = None, untag: bool = False) Status[source]

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

Note that to_status should be a status dict and not an ID.

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

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

Usage in production code is not recommended.

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

Mastodon.make_poll(options: List[str], expires_in: int, multiple: bool = False, hide_totals: bool = False) Poll[source]

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 - see the instance configuration for the actual value on any given instance, if stated). 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.

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

Mastodon.status_reblog(id: Status | str | int | MaybeSnowflakeIdType, visibility: str | None = None) Status[source]

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 new Status that wraps around the reblogged status.

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

Mastodon.status_unreblog(id: Status | str | int | MaybeSnowflakeIdType) Status[source]

Un-reblog a status.

Returns the status that used to be reblogged.

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

Mastodon.status_favourite(id: Status | str | int | MaybeSnowflakeIdType) Status[source]

Favourite a status.

Returns the favourited status.

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

Mastodon.status_unfavourite(id: Status | str | int | MaybeSnowflakeIdType) Status[source]

Un-favourite a status.

Returns the un-favourited status.

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

Mastodon.status_mute(id: Status | str | int | MaybeSnowflakeIdType) Status[source]

Mute notifications for a status.

Returns the now muted status

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

Mastodon.status_unmute(id: Status | str | int | MaybeSnowflakeIdType) Status[source]

Unmute notifications for a status.

Returns the status that used to be muted.

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

Mastodon.status_bookmark(id: Status | str | int | MaybeSnowflakeIdType) Status[source]

Bookmark a status as the logged-in user.

Returns the now bookmarked status

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

Mastodon.status_unbookmark(id: Status | str | int | MaybeSnowflakeIdType) Status[source]

Unbookmark a bookmarked status for the logged-in user.

Returns the status that used to be bookmarked.

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

Mastodon.status_delete(id: Status | str | int | MaybeSnowflakeIdType) Status[source]

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 | str | int | MaybeSnowflakeIdType, status: str | None = None, spoiler_text: str | None = None, sensitive: bool | None = None, media_ids: List[MediaAttachment | str | int | MaybeSnowflakeIdType] | None = None, poll: Poll | str | int | MaybeSnowflakeIdType | None = None) Status[source]

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.

TODO: Currently doesn’t support editing media descriptions, implement that.

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

Scheduled statuses

These functions allow you to get information about scheduled statuses and to update scheduled statuses that already exist. To create new scheduled statuses, use status_post() with the scheduled_at parameter.

Reading

Mastodon.scheduled_statuses(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[ScheduledStatus][source]

Fetch a list of scheduled statuses

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

Mastodon.scheduled_status(id: ScheduledStatus | str | int | MaybeSnowflakeIdType) ScheduledStatus[source]

Fetch information about the scheduled status with the given id.

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

Writing

Mastodon.scheduled_status_update(id: Status | str | int | MaybeSnowflakeIdType, scheduled_at: datetime) ScheduledStatus[source]

Update the scheduled time of a scheduled status.

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

Returned object reflects the updates to the scheduled status.

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

Mastodon.scheduled_status_delete(id: Status | str | int | MaybeSnowflakeIdType)[source]

Deletes a scheduled status.

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

Media

This function allows you to upload media to Mastodon and update media uploads. The returned media IDs (Up to 4 at the same time on a default configuration Mastodon instance) can then be used with post_status to attach media to statuses.

Mastodon.media_post(media_file: str | PurePath | IO[bytes], mime_type: str | None = None, description: str | None = None, focus: Tuple[float, float] | None = None, file_name: str | None = None, thumbnail: str | PurePath | IO[bytes] | None = None, thumbnail_mime_type: str | None = None, synchronous: bool = False) MediaAttachment[source]

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: MediaAttachment | str | int | MaybeSnowflakeIdType, description: str | None = None, focus: Tuple[float, float] | None = None, thumbnail: str | PurePath | IO[bytes] | None = None, thumbnail_mime_type=None) MediaAttachment[source]

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

The returned dict reflects the updates to the media attachment.

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

Polls

This function allows you to get and refresh information about polls as well as to vote in polls

Reading

Mastodon.poll(id: Poll | str | int | MaybeSnowflakeIdType) Poll[source]

Fetch information about the poll with the given id

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

Writing

Mastodon.poll_vote(id: Poll | str | int | MaybeSnowflakeIdType, choices: int | List[int]) Poll[source]

Vote in the given poll.

choices is the index of the choice you wish to register a vote for (i.e. its index in the corresponding polls options field. In case of a poll that allows selection of more than one option, a list of indices can be passed.

You can only submit choices for any given poll once in case of single-option polls, or only once per option in case of multi-option polls.

The returned object will reflect the updated votes.

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