> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/mastodon/servers-host-emojis>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/mastodon/servers-host-emojis.mdx>

---

# Mastodon Custom Emoji API

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

`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`.

## Request

- **Endpoint:** `GET /v1/mastodon/servers/{host}/emojis`
- **Credits:** 2 credits
Failed requests are free
- **Input:** by host
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v1/mastodon/servers/host/emojis/get)
- **Platform page:** [/platforms/mastodon](https://www.socialfetch.dev/platforms/mastodon)

## 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.