Skip to main content
The users module reads and updates user profiles and lets the logged-in user act on the social graph of an arbitrary target user, addressed by userId. In the follow and connection helpers below, userId is always the target — the user being followed, the other party in a connection, or the user whose followers you’re reading. The actor is always the logged-in token holder. To act on your own graph (your own followers, the users you follow, your own connections and pending requests), use the follows and connections modules instead.

​
fetchUserById

Fetches a user by their internal Sublay user ID. 
const user = await sublay.users.fetchUserById({ userId: "usr_abc123" });
​
userId
string
required
The Sublay user ID.
​
include
string
Comma-separated list of associations to populate.
Returns — Promise<User>

​
fetchUserByForeignId

Fetches a user by your application’s own user identifier. 
const user = await sublay.users.fetchUserByForeignId({
  foreignId: "external-user-42",
});
​
foreignId
string
required
Your application’s user identifier.
​
include
string
Comma-separated list of associations to populate.
Returns — Promise<User>

​
fetchUserByUsername

Fetches a user by their username. 
const user = await sublay.users.fetchUserByUsername({ username: "alice" });
​
username
string
required
The user’s unique username.
​
include
string
Comma-separated list of associations to populate.
Returns — Promise<User>

​
fetchUserSuggestions

Returns users whose name or username matches a partial query string. Useful for mention autocomplete. 
const users = await sublay.users.fetchUserSuggestions({ query: "ali" });
​
query
string
required
Partial name or username to search for.
Returns — Promise<User[]>

​
checkUsernameAvailability

Checks whether a username is available. 
const { available } = await sublay.users.checkUsernameAvailability({
  username: "alice",
});
​
username
string
required
The username to check.
Returns — Promise<{ available: boolean }>

​
updateUser

Updates a user’s profile, optionally uploading a new avatar and/or banner image. A user token may only update its own profile. 
const updatedUser = await sublay.users.updateUser({
  userId: "usr_abc123",
  name: "Alice Updated",
  bio: "New bio",
  location: { latitude: 37.7749, longitude: -122.4194 },
});
​
userId
string
required
The Sublay user ID to update. A user token may only update itself.
​
name
string
New display name.
​
username
string
New username. Must be available.
​
avatar
string
New avatar URL.
​
bio
string
New bio text.
​
birthdate
string
ISO 8601 date string for the user’s birthdate.
​
location
object
Geographic location { latitude: number; longitude: number }, or null to clear it.
​
metadata
object
Updated public metadata (Record<string, any>).
​
secureMetadata
object
Updated secure metadata (Record<string, any>, not exposed in public responses).
​
avatarFile
object
A new avatar image to upload: { file: Blob | File; options: ImageOptions }.
​
bannerFile
object
A new banner image to upload: { file: Blob | File; options: ImageOptions }.
When avatarFile or bannerFile is supplied the request is sent as multipart/form-data carrying the browser File/Blob. The image options (an ImageOptions object whose mode selects a processing strategy) are sent alongside the file.
// Uploading an avatar from an <input type="file"> element
const input = document.querySelector<HTMLInputElement>("#avatar-input");
const file = input.files[0];

const updatedUser = await sublay.users.updateUser({
  userId: "usr_abc123",
  avatarFile: {
    file,
    options: {
      mode: "exact-dimensions",
      dimensions: { default: { width: 256, height: 256 } },
      format: "webp",
    },
  },
});
Returns — Promise<AuthUser>

​
fetchFollowersByUserId

Returns a paginated list of users following the target user. 
const { data, pagination } = await sublay.users.fetchFollowersByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
​
userId
string
required
The Sublay user ID whose followers to fetch.
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
Returns — Promise<PaginatedResponse<FollowListItem>>

​
fetchFollowersCountByUserId

Returns the total number of followers for the target user. 
const { count } = await sublay.users.fetchFollowersCountByUserId({
  userId: "usr_abc123",
});
​
userId
string
required
The Sublay user ID.
Returns — Promise<{ count: number }>

​
fetchFollowingByUserId

Returns a paginated list of users that the target user is following. 
const { data, pagination } = await sublay.users.fetchFollowingByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
​
userId
string
required
The Sublay user ID whose following list to fetch.
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
Returns — Promise<PaginatedResponse<FollowListItem>>

​
fetchFollowingCountByUserId

Returns the number of users the target user is following. 
const { count } = await sublay.users.fetchFollowingCountByUserId({
  userId: "usr_abc123",
});
​
userId
string
required
The Sublay user ID.
Returns — Promise<{ count: number }>

​
fetchConnectionsByUserId

Returns a paginated list of the target user’s established connections. 
const { data, pagination } = await sublay.users.fetchConnectionsByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
​
userId
string
required
The Sublay user ID whose connections to fetch.
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
Returns — Promise<PaginatedResponse<EstablishedConnection>>

​
fetchConnectionsCountByUserId

Returns the number of established connections for the target user. 
const { count } = await sublay.users.fetchConnectionsCountByUserId({
  userId: "usr_abc123",
});
​
userId
string
required
The Sublay user ID.
Returns — Promise<{ count: number }>

​
createFollow

The logged-in user follows the target user. 
const follow = await sublay.users.createFollow({ userId: "usr_target" });
​
userId
string
required
The user being followed (the target).
Returns — Promise<Follow>

​
deleteFollow

The logged-in user unfollows the target user. 
await sublay.users.deleteFollow({ userId: "usr_target" });
​
userId
string
required
The user being unfollowed (the target).
This unfollows by the target’s userId. To delete one of your own follow relationships by its record ID, use follows.deleteFollow, which takes a followId.
Returns — Promise<void>

​
fetchFollowStatus

Returns whether the logged-in user follows the target user. 
const { isFollowing, followId } = await sublay.users.fetchFollowStatus({
  userId: "usr_target",
});
​
userId
string
required
The user whose follow relationship is being checked (the target).
Returns — Promise<{ isFollowing: boolean; followId?: string; followedAt?: string }>

​
requestConnection

Sends a connection request from the logged-in user to the target user. 
const connection = await sublay.users.requestConnection({
  userId: "usr_target",
  message: "Let's connect!",
});
​
userId
string
required
The user the connection is requested with (the target).
​
message
string
Optional message to include with the request.
Returns — Promise<ConnectionRequestResponse> — the created/pending connection.

​
fetchConnectionStatus

Returns the connection status between the logged-in user and the target user. 
const status = await sublay.users.fetchConnectionStatus({
  userId: "usr_target",
});
​
userId
string
required
The other user in the connection (the target).
Returns — Promise<ConnectionStatusResponse>

​
removeConnectionByUserId

Removes the connection with the target user — withdrawing a sent request, declining a received one, or disconnecting an established connection, depending on the current state. 
const result = await sublay.users.removeConnectionByUserId({
  userId: "usr_target",
});
​
userId
string
required
The other user in the connection (the target).
Returns — Promise<RemoveConnectionByUserIdResponse>