Social Fetch
Start for freeStart free
Mastodon hub

Mastodon Custom Emoji API

A server's custom emoji, with shortcode, image URLs and category, so :shortcode: renders.

GET /v1/mastodon/servers/{host}/emojis

2 credits Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v1/mastodon/servers/mastodon.social/emojis returns data.emojis. Each entry has shortcode, url, staticUrl, category and visibleInPicker. Use it to resolve the emojis arrays attached to account names and post text, which carry the shortcode but not always the image.

The list is paginated: limit is 1 to 1000 (default 200), totalEmojis is the full count, and page.nextCursor continues while page.hasMore is true. Custom emoji belong to one server. A post from another server can use an emoji that does not exist here, and its URL points at the author's server. Some servers keep the list private: a server that does not offer the route returns lookupStatus: unsupported.

Mastodon Custom Emoji API FAQ

What does shortcode mean?

It is the name between colons in text, without the colons. Match it against the emojis array on the account or post that used it.

How many credits does it cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.

How do I get the whole list?

Follow page.nextCursor while page.hasMore is true. Pass limit up to 1000 to fetch fewer or larger pages, and check totalEmojis for the full count.

Why is an emoji missing from the list?

The list is the server's own catalog. An emoji used by a post from another server belongs to that server and is not in this list.

Does visibleInPicker matter?

It reports whether the server offers the emoji in its own picker. An emoji can still appear in existing posts when the value is false or null.

Other Mastodon endpoints