Skip to main content

​
Overview

The getClerkUsers function retrieves user information from Clerk based on an array of user IDs (email addresses). It requires authentication and returns formatted user objects with id, name, email, and avatar.

​
Function Signature

export const getClerkUsers = async ({ userIds }: { userIds: string[] })

​
Parameters

​
userIds
string[]
required
Array of email addresses to fetch user details for. The returned users will be sorted in the same order as the input array.

​
Return Value

​
users
User[] | undefined
Array of user objects sorted in the same order as the input userIds. Returns undefined if an error occurs.

​
Code Example

import { getClerkUsers } from '@/lib/actions/user.actions';

// Fetch multiple users by their email addresses
const userEmails = [
  '[email protected]',
  '[email protected]',
  '[email protected]'
];

const users = await getClerkUsers({ userIds: userEmails });

if (users) {
  users.forEach(user => {
    console.log(`${user.name} - ${user.email}`);
  });
}

​
Error Handling

The function handles errors gracefully and logs them to the console. It returns undefined when:
  • The current user is not authenticated (no email found)
  • The Clerk API request fails
  • Any other error occurs during execution
This is a server action and must be called from server components or other server actions. The current user must be authenticated via Clerk.

​
Authentication

The function automatically checks if the current user is authenticated by retrieving their email. If no authenticated user is found, it throws an “Unauthorized to list users” error.

​
Implementation Details

  • Uses clerkClient.users.getUserList() to fetch user data
  • Transforms Clerk user objects into a simplified format
  • Preserves the order of input userIds in the returned array
  • Uses parseStringify utility for serialization

Build docs developers (and LLMs) love

Get started for freeTalk to us