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 | datetime) → Status

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 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_context(id: Status | str | int | MaybeSnowflakeIdType | datetime) → Context

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 (parameters), Mastodon v0.6.0 (return value)

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

Fetch a list of users that have reblogged a status.

Does not require authentication for publicly visible statuses.

Interesting caveat: If you self-reblog a status with private visibility, this endpoint will not return your account as having reblogged it.

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

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

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 | datetime) → PreviewCard

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 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 (parameters), Mastodon v4.3.0 (return value)

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

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 | datetime) → StatusSource

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.statuses(ids: List[Status | str | int | MaybeSnowflakeIdType | datetime]) → List[Status]

Fetch information from multiple statuses by a list of status id.

Does not require authentication for publicly visible accounts.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Mastodon.favourites(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[Status]

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.

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

Mastodon.bookmarks(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[Status]

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 | datetime | None = None, media_ids: List[MediaAttachment | str | int | MaybeSnowflakeIdType | datetime] | 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 | datetime | None = None, quote_id: Status | str | int | MaybeSnowflakeIdType | datetime | None = None, strict_content_type: bool = False) → Status | ScheduledStatus

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 objects 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 ScheduledStatus 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.

You can use get_status_length() to count how many characters a status you want to post would take up in terms of Mastodons character limit. The limits can be retrieved from the instance information (instance_v2()).

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. If you want to throw an error if the content type is not known to work on the server, set strict_content_type to True.

Specific to “fedibird” feature set:: The quote_id parameter is a non-standard extension that specifies the id of a quoted status.

Returns the new status.

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

Mastodon.status_reply(to_status: Status | str | int | MaybeSnowflakeIdType | datetime, status: str, media_ids: List[MediaAttachment | str | int | MaybeSnowflakeIdType | datetime] | 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 | datetime | None = None, quote_id: Status | str | int | MaybeSnowflakeIdType | datetime | None = None, untag: bool = False, strict_content_type: bool = False) → Status

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 must be a Status and not just 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 (parameters), Mastodon v4.4.0 (return value)

Mastodon.toot(status: str) → Status

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 (parameters), Mastodon v4.4.0 (return value)

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

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 (parameters), Mastodon v2.8.0 (return value)

Mastodon.status_reblog(id: Status | str | int | MaybeSnowflakeIdType | datetime, visibility: str | None = None) → Status

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 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_unreblog(id: Status | str | int | MaybeSnowflakeIdType | datetime) → Status

Un-reblog a status.

Returns the status that used to be reblogged.

Added: Mastodon v1.0.0, last changed: Mastodon v2.0.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_favourite(id: Status | str | int | MaybeSnowflakeIdType | datetime) → Status

Favourite a status.

Returns the favourited status.

Added: Mastodon v1.0.0, last changed: Mastodon v2.0.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_unfavourite(id: Status | str | int | MaybeSnowflakeIdType | datetime) → Status

Un-favourite a status.

Returns the un-favourited status.

Added: Mastodon v1.0.0, last changed: Mastodon v2.0.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_mute(id: Status | str | int | MaybeSnowflakeIdType | datetime) → Status

Mute notifications for a status.

Returns the now muted status

Added: Mastodon v1.4.0, last changed: Mastodon v2.0.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_unmute(id: Status | str | int | MaybeSnowflakeIdType | datetime) → Status

Unmute notifications for a status.

Returns the status that used to be muted.

Added: Mastodon v1.4.0, last changed: Mastodon v2.0.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_bookmark(id: Status | str | int | MaybeSnowflakeIdType | datetime) → Status

Bookmark a status as the logged-in user.

Returns the now bookmarked status

Added: Mastodon v3.1.0, last changed: Mastodon v3.1.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_unbookmark(id: Status | str | int | MaybeSnowflakeIdType | datetime) → Status

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 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_delete(id: Status | str | int | MaybeSnowflakeIdType | datetime, delete_media: bool = None) → Status

Delete a status

Returns the now-deleted status, with an added “text” attribute that contains the text that was used to compose this status (this can be used to power “delete and redraft” functionality) as well as either poll or media_attachments set in the same way. Note that when reattaching media, you have to wait up to several seconds for the media to be un-attached from the original status - that operation is not synchronous with the delete.

Pass delete_media=True to delete the media attachments of the status immediately, instead of just scheduling them for deletion as part of the next media cleanup. If you set this, you will not be able to reuse them in a new status (so if you’re delete-redrafting, you should not set this).

Added: Mastodon v1.0.0, last changed: Mastodon v1.0.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.status_update(id: Status | str | int | MaybeSnowflakeIdType | datetime, status: str, spoiler_text: str | None = None, sensitive: bool | None = None, media_ids: List[MediaAttachment | str | int | MaybeSnowflakeIdType | datetime] | None = None, poll: Poll | str | int | MaybeSnowflakeIdType | datetime | None = None, media_attributes: List[Dict[str, Any]] | None = None) → Status

Edit a status. The meanings of the fields are largely the same as in status_post(), though not every field can be edited. The status parameter is mandatory.

Note that editing a poll will reset the votes.

To edit media metadata, generate a list of dictionaries with the following keys:

Added: Mastodon v3.5.0, last changed: Mastodon v4.1.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.generate_media_edit_attributes(id: MediaAttachment | str | int | MaybeSnowflakeIdType | datetime, description: str | None = None, focus: Tuple[float, float] | None = None, thumbnail: str | PurePath | IO[bytes] | None = None, thumb_mimetype: str | None = None) → Dict[str, Any]

Helper function to generate a single media edit attribute dictionary.

Parameters: - id (str): The ID of the media attachment (mandatory). - description (Optional[str]): A new description for the media. - focus (Optional[Tuple[float, float]]): The focal point of the media. - thumbnail (Optional[PathOrFile]): The thumbnail to be used.

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]

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 | datetime) → ScheduledStatus

Fetch information about the scheduled status with the given id.

Added: Mastodon v2.7.0, last changed: Mastodon v2.7.0 (parameters), Mastodon v2.7.0 (return value)

Writing

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

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 (parameters), Mastodon v2.7.0 (return value)

Mastodon.scheduled_status_delete(id: Status | str | int | MaybeSnowflakeIdType | datetime)

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

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.

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.

The returned value (or its id) can be used in a status post as the media_ids parameter.

Added: Mastodon v1.0.0, last changed: Mastodon v3.2.0 (parameters), Mastodon v4.0.0 (return value)

Mastodon.media_update(id: MediaAttachment | str | int | MaybeSnowflakeIdType | datetime, description: str | None = None, focus: Tuple[float, float] | None = None, thumbnail: str | PurePath | IO[bytes] | None = None, thumbnail_mime_type=None) → MediaAttachment

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.

Note: This is for updating the metadata of an unattached media attachment (i.e. one that has not been used in a status yet). For editing media attachment metadata after posting, see status_update and generate_media_edit_attributes.

Added: Mastodon v2.3.0, last changed: Mastodon v3.2.0 (parameters), Mastodon v4.0.0 (return value)

Mastodon.media(id: MediaAttachment | str | int | MaybeSnowflakeIdType | datetime) → MediaAttachment

Get the updated JSON for one non-attached / in progress media upload belonging to the logged-in user.

Added: Mastodon v3.1.4, last changed: Mastodon v3.1.4 (parameters), Mastodon v4.0.0 (return value)

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 | datetime) → Poll

Fetch information about the poll with the given id

Added: Mastodon v2.8.0, last changed: Mastodon v2.8.0 (parameters), Mastodon v2.8.0 (return value)

Writing

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

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 (parameters), Mastodon v2.8.0 (return value)

Translation

These functions allow you to get machine translations for statuses, if the instance supports it.

Mastodon.status_translate(id: Status | str | int | MaybeSnowflakeIdType | datetime, lang: str | None = None) → Translation

Translate the status content into some language.

Raises a MastodonAPIError if the server can’t perform the requested translation, for any reason (doesn’t support translation, unsupported language pair, etc.).

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0 (parameters), Mastodon v4.0.0 (return value)