Social Fetch
Start for freeStart free
Mastodon hub

Mastodon Profile API

One account, resolved on its home server, with the flags that decide what else you can read.

GET /v1/mastodon/profiles/{handle}

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v1/mastodon/profiles/{handle} takes user@host, @user@host or a profile URL and returns the account from that server. On found, data.profile carries id, handle, username, displayName, bio, avatar and header, stats.followers, stats.following and stats.posts, createdAt, lastPostDate, fields, emojis and public roles. Flags such as isLocked, isLimited, isSuspended, isDiscoverable, isIndexable, noIndex and hidesNetwork come back as the server reports them, and movedTo names the account this one migrated to.

Add include=featuredTags to also return the hashtags the account features. Use it before pulling posts or followers: hidesNetwork tells you whether those lists are readable, and isLocked does not hide public posts.

Mastodon Profile API FAQ

How do I name the account?

Use the full handle with its home server, for example Gargron@mastodon.social, or a profile URL such as https://mastodon.social/@Gargron. A leading @ is accepted. The server in the handle is the server asked.

How many credits does a profile lookup 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.

What does lookupStatus mean?

found means profile is populated. not_found means the account does not exist on that server. restricted means the account is suspended. not_compatible means the host is not a Mastodon-compatible server. Always branch on lookupStatus before writing.

What do the flags tell me?

isLocked means follow requests need approval, not that posts are private. hidesNetwork means the follower and following lists are hidden. isDiscoverable, isIndexable and noIndex are the owner's directory and search-engine choices. isLimited and isSuspended are moderator actions.

Who is the account's home server in the response?

data.host is the server that was asked and profile.host is where the record came from. They differ when a handle's domain delegates its API to another host. data.profile.handle keeps the home server the owner uses.

Other Mastodon endpoints