Home Mastodon API - Media Only Parameters

Mastodon API - Media Only Parameters

A handy reference for understanding which Mastodon API endpoints have an option to return only posts that contain media attachments. Syndication

The official Mastodon API documentation has many endpoints that return collections of Status objects, but not all have the same parameters.

An interesting one is the ability to request only posts that contain media attachments - audio, video, or images.

This parameter is called “only_media” in each instance and can be set to true or false. The default is false. You currently can’t filter to a specific media type, like only returning video.

The issue is that not all of the endpoints HAVE the option to return only media attachments.

I noticed that Masto.js has a common “listParameters” object that includes an “onlyMedia?” optional flag, even on the Home and List timelines, which don’t have this filter.

Here’s the list. Note that some endpoints are listed twice, with different parameters passed through. I’ve listed as such because on the front-end, this is often how they are displayed to an end user.

It’s disappointing that the home timeline doesn’t have the only_media flag. Imagine building a timeline of only videos, like a TikTok feed. That would be cool!

Mastodon API EndPoints Returning Status Collections

Media Flag Docs Description  
NO Home timeline The default feed of followed posts and hashtags  
YES Local timeline All local posts, using the public timeline with local set to true  
YES Public timeline All federated posts known to your instance  
YES My account posts Usually seen on the profile page, a feed of the posts you have created  
NO My favourites Usually seen on the profile page, a feed of posts you have favourited  
NO My bookmarks Usually seen on the profile page, a feed of posts you have bookmarked  
YES Hashtag posts A feed of posts for a single hashtag, followed or not followed  
NO My lists A feed of posts related to a specific List.  
YES My followed tags I have not seen this used anywhere, requires some configuration to create the search parameters, not just a direct call.  
This post is licensed under CC BY 4.0 by the author.

Apple Shortcut for Hide my Email

Touch Tone your Funny Bone


Total Interactions: 9
4 Likes 0 Links 0 Posts 3 Re-posts 0 Bookmarks 2 Replies


Posts, Re-Posts and Bookmarks


  1. @supernovae Yes! Been following along on this one. I know it’s probably a limitation of the API or how Mastodon works, but it would be nice to also be able to limit to “has:video, has:audio, has:image”. Just as you mentioned in you post, that would allow creators to build feed UIs similar to TikTok or a PodCast browser within Mastodon.