Skip to content

Get a public profile by ref

GET
/users/by-ref/{ref}

Returns a person’s public profile by account ref, for links that carry a ref rather than a username.

Visitors who aren’t signed in can call this when public mode is on; with it off they get 401. Signed-in callers always can. A ref that isn’t a whole number gets a plain-text 400, after the 401 for visitors when public mode is off, and a ref with no account gets 404.

For visitors who aren’t signed in, the full name is left out and the display name skips it, and a profile whose owner hid it from visitors gets the same 404 as a ref with no account. Signed-in callers get the full name where there is one and also see hidden profiles. Everything else is the same for everyone, including the bio, location, links, language and theme preferences and the post count, and accounts are returned whatever their status.

Unlike getUserPublicByRef, this honours the owner’s choice to hide from visitors and isn’t cached: the profile is read fresh each time. Server errors get a plain-text 500.

ref
required
integer format: int64

The account’s ref.

The profile.

A person’s profile. Which names are included depends on whether you’re signed in; see display_name and fullname.

object
ref
required
integer format: int64
username
required

The account’s username; an empty string if it has none.

string
fullname

The account’s full name. Sent only to signed-in callers, and only when it isn’t empty; profile edits don’t change it.

string
nullable
display_name
required

The name to show, never empty: the profile’s display name, then the account’s full name, then the username, and as a last resort user followed by the account number. For readers who aren’t signed in, the full name is skipped.

string
bio

An empty string when none is set.

string
avatar_url

The stored picture address; the server doesn’t upload, fetch or check it. Left out when unset; clearing it through this API returns an empty string.

string
nullable
location

An empty string when none is set.

string
website_url

The website address as saved; its format isn’t checked. Left out when unset; clearing it through this API returns an empty string.

string format: uri
nullable
social_links

Platform names mapped to handles or links stored in the profile; nothing is checked. Left out when there are none.

object
key
additional properties
string
language

The owner’s language preference as saved, meant to be a tag such as en or es-AR; the server doesn’t check it. Left out when not set.

string
theme

The owner’s theme preference: light, dark or system, which follows each device’s setting. Left out when not set.

string
Allowed values: "" light dark system
member_since
required

When the account was created.

string format: date-time
post_count
required

How many published posts the person has that aren’t deleted. Every one counts, including posts you can’t open, so it can be higher than what you can see.

integer format: int64
origin_server_id

The server a copied profile came from. Left out for this server’s own users; nothing in the API creates copies.

string format: uuid
nullable

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed