Guide for Using Mastodon Search

It’s easier and more powerful than you might think.

Mark Wyner
6 min readJun 11, 2024
Mastodon Search. The Mastodon logo with an illustration of a cute mastodon that’s smiling with its eyes squinting in delight. It’s holding a mobile device and looking off to the side. A search form input is overlaid with placholder text that reads ‘search.’

One of the biggest complaints I hear about Mastodon is that its local search is unusable. It certainly was. But not anymore. Now it’s quite powerful, if you know the basics. So here’s a primer for you. Because I love Mastodon, you, and good UX.

A few notes before we begin:

  • Mastodon is decentralized. This means every instance has its own data that may or may not be known to yours. Search is relative to known data (more on this from Fedi.tips).
  • This primer is in reference to the core search functionality in the main UI, which is what you see when you connect to Mastodon in a desktop or mobile browser. There are a number of mobile apps, each of them treating search wildly different, including the official Mastodon app.
  • What I share here will undoubtedly change. These tips are ephemeral. I’ll do my best to edit this with updates as I noticed changes to the UX/UI. If you notice something I’ve gotten wrong, please reach out to me. I’m friendly and willing to correct mistakes.

Search Anatomy

Mastodon search can be simple or robust. The former is type-and-go, like any search engine. The latter enables you to really fine-tune what you’re seeking, by optimizing specificity.

The Mastodon search UI, showing the search menu open with the options noted in the section below.
Fig 1: search anatomy

You can search by word(s) and then, if you want, further refine the results using the following options:

  1. Has: the post includes media, a poll, or an embed
  2. Is: the post is a reply or marked as sensitive
  3. Language: the actual ISO language code (i.e. Eng or En)
  4. From: the username of the account
  5. Before, during, and after: ISO dates (2024–06–10) which aren’t intuitive but are functional (more on ISO date formats)
  6. In: the post is global or I’ve created/interacted with it (favorited, boosted, or replied)

Search Type

Mastodon supports full-text search or hashtag search. Each yields different results, but there is some overlap, which is helpful. (Read more about hashtag accessibility.)

Both types can target profiles, hashtags, and posts. Or a query can simply be submitted, and the results will be grouped into each of these. They match as follows:

  1. Profiles: returns all accounts who have the search query in their bio or their username
  2. Hashtags: returns a list of case-insensitive hashtags that match or are close to the search query (i.e. “product design” returns #ProductDesign and #Product_Design, while “typography” returns #Typography and #TypographyInTheWild)
  3. Posts: returns every post that includes the search query

As mentioned, there’s a lot of overlap. But there are good reasons to use one over the other.

The Mastodon search UI, showing the query ‘typography’ populated in the search input. Below it are four quick actions: ‘go to the hashtag #typography,’ ‘go to the profile @typography,’ ‘posts matching typography,’ and ‘profiles matching typography.’ The search results show the beginning of a scrollable column of grouped profiles, hashtags, and posts.
Fig 2: full-text search

The main reason to use full-text search is because it yields a larger pool of results. The ratio of words vs hashtags in a post is almost always in favor of the former (at least they should be). And some folks use hashtags scarcely or simply don’t use them at all.

The Mastodon search UI, showing the query ‘#DogsOfMastodon’ populated in the search input. Below it are three quick actions: ‘go to the hashtag #DogsOfMastodon,’ ‘posts matching #DogsOfMastodon,’ and ‘profiles matching #DogsOfMastodon.’ The search results show the beginning of a scrollable column of grouped profiles, hashtags, and posts.
Fig 3: hashtag search

Hashtag searches are more explicit in what they return, even though they return results in the same way. The primary reason to search by hashtag is to tap into that shared ecosystem.

“#DogsOfMastodon” won’t return the same thing as “dogs of Mastodon.” The former will return Nicole Sandler’s account (Laffy) because she uses the hashtag in her profile (see fig 4 below). The latter will not, because she doesn’t use that phrase in her profile.

The Mastodon search UI, showing ‘#DogsOfMastodon’ populated in the search input. The main content column shows a profile for the user ‘Laffy’ who has the hashtag #DogsOfMastodon in her bio.
Fig 4: profile match

So it’s a little nuanced, but there is a difference between them. The one thing that full-text search offers that hashtags do not, is the option of exact matches for usernames. In fig 2 above, you’ll see a “quick actions” option for “go to profile @typography.” Because there is an account by that name, you can go straight to it.

You can also go straight to any of the targets by choosing one from the “quick actions” options. If you want to explicitly find posts matching your search query, you don’t have to key/submit. You can key your term then select your target.

Keying “#DogsOfMastodon” and submitting will return the “all” results, grouped by target. If you’re only interested in posts you can type your query and then choose “go to hashtag” or “posts matching” (see fig 5 below).

The Mastodon search UI, showing the query ‘#DogsOfMastodon’ populated in the search input. Below it are three quick actions: ‘go to the hashtag #DogsOfMastodon,’ ‘posts matching #DogsOfMastodon,’ and ‘profiles matching #DogsOfMastodon,’ with the first option highlighted. The search results show the beginning of a scrollable column of posts matching the hashtag. It’s preceded by some respective metadata and a button with the label ‘follow hashtag.’
Fig 5: results target

Targeting Hashtags vs Targeting Posts

The UX for this is quite ambiguous. You’d think that both would yield the same results, because if a hashtag is used in the post it would be relevant in either scenario. However, that’s not the case.

So why have both? It’s complicated…

Choosing “go to hashtag” from “quick actions” will take you to the actual URI for that hashtag (i.e. “#DogsOfMastodon” returns /tags/DogsOfMastodon on my instance). So it’s not necessarily search results, per se, but a link to that hashtag.

Yes, hashtags have their own URIs. There are two reasons for this. First, there’s metadata associated with hashtags. Second, and more importantly, you can follow hashtags on Mastodon in the same way you can follow accounts. (See these in fig 5.)

Note: choosing “go to hashtag” from the menu is not the same as choosing “hashtags” from the target tabs. The latter simply shows you a list of hashtags matching and related to your search query.

If you’re searching for posts, I strongly recommend using the “go to hashtag” instead of “posts matching.” The hashtag view yields far more results than the latter.

In All or Library

While most of the search options are intuitive, this one is not. But it’s simple once you understand it.

The Mastodon search UI, showing the query ‘design in:all’ populated in the search input. Below it are two quick actions: ‘posts matching design in:all,’ and ‘profiles matching design in:all.’ The search results show the beginning of a scrollable column of posts.
Fig 6: in all

In “all” is basically an open search through all posts. I haven’t been able to find the real purpose for it, because it simply returns posts that match the query. So I believe it’s not really helpful.

The Mastodon search UI, showing the query ‘design in:library’ populated in the search input. Below it are two quick actions: ‘posts matching design in:library,’ and ‘profiles matching design in:library.’ The search results show the beginning of a scrollable column of posts. The first one is a reply with the ‘favorites’ icon highlighted, and the second is my post.
Fig 7: in library

However, in “library” can be quite useful. Choosing this means it only returns posts you’ve interacted with. If it’s your post or someone else’s that you’ve favorited, boosted, or replied to it, it’s in your “library.” As seen in fig 7, the results show a reply that I favorited as well as one of my own posts.

With Great Power Comes Great…Results

The real power in the Mastodon search is being able to mix and match the search options.

As mentioned, searching in Mastodon can be really simple: type and send. But using the search options for a detailed search is very powerful.

Fig 8: mix and match

Want to find a poll you posted two years ago? Easy (see fig 8). Want to find a reply to you from someone that may have included a link? Easy. Connect the dots and create your recipe. Mastodon search has you covered.

Conclusion

Mastodon didn’t invent anything new here. In fact, these options may look familiar to you. But robust search is relatively new to Mastodon. It’s a game changer that fixes what was one of the most frustrating aspects of Mastodon. It’s something that people have (rightfully) complained about en masse.

New to Mastodon? Don’t be a stranger. It’s the best social network you never knew you needed. If you’re ready to dive in, find me on mas.to and I’ll be happy to help you find your way.

Happy searching!

(Thanks to Stn for prompting this piece and also helping me with some technical tips.)

  1. Please click or tap that clap if you enjoyed this article.
  2. View my site to learn more about me and my work in UX/IA/research.
  3. Say hello or hire me to write for your publication or speak at your event.

--

--

Mark Wyner

Activist, family man, creative professional, technologist, soccer fanatic, meditator, lover, hater, potty mouth, mostly vegan.