Querying multiple users

Privy also allows you to query all of your users and their linked accounts.

WARNING

Privy rate limits REST API endpoints that you may call from your server. If you suspect your team will require an increased rate limit, please reach out to support!

Using `@privy-io/server-auth`

Use the PrivyClient's getUsers method to get a list of all of your users. Do not pass any parameters to the method.

const users = await privy.getUsers();

This method will return an array of User objects. This method automatically handles the pagination of the Privy API, and the array will include all of your users.

Using the REST API

Make a GET request to:

https://auth.privy.io/api/v1/users

You should specify the app ID you are querying in your request headers.

This is a paginated query, and the API will return up to 100 users for a single request.

Parameters

In the request query parameters, specify the following fields:

cursor (optional)
- When you request a batch of users from Privy, the API will return a cursor for the next batch of users in the next_cursor field of the response. This will be a Privy DID (e.g. 'did:privy:123456').
- If you are requesting the first batch of users for your app, do not include a cursor in your request parameters.
- If you have already requested a batch of users and want to request the next batch, set the cursor in your request parameters to be the next_cursor returned by the API in your previous query. If the provided cursor is not a valid Privy DID, the API will return an error.
limit (optional): The number of users you would like the API to return. Defaults to and may not exceed 100.

As an example, to get the first 100 users for your app, you should include no URL query parameters:

curl --request GET https://auth.privy.io/api/v1/users \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"

Then, to get the next 100 users for your app, you should pass the next_cursor field of the last response as the cursor in your request query parameters:

# Replace 'did:privy:123456' below with the `next_cursor` returned by the last query
curl --request GET https://auth.privy.io/api/v1/users?cursor=did:privy:123456 \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"

Response

A successful response will include:

data: the user objects for your users as an array
next_cursor: the cursor to be used in your next request to this API

TIP

Looking for the types of LinkedAccounts?

See a list of the different account types and the data they include

Note:

Each account should be a JSON object including all the necessary fields for that account type.
- Valid account types are apple_oauth, 'custom_auth', 'discord_oauth', 'farcaster', 'github_oauth', 'google_oauth', 'instagram_oauth', 'linkedin_oauth', 'spotify_oauth', 'telegram', 'tiktok_oauth', 'twitter_oauth', 'email', 'phone' and 'wallet'.
If importing a user with a custom_auth account, the custom_auth account must be the only element of the linked_accounts array. It is not permitted to import a user with a custom_auth account and other linked_accounts.
You must exclude the verifiedAt field.
The SDK and REST API have different naming conventions. The SDK uses camelCase and the API uses snake_case.

CustomJwtAccount

Field	Type	Description
`type`	`'custom_auth'`	N/A
API: `custom_user_id` SDK: `customUserId`	`string`	ID of user from custom auth provider.

DiscordAccount

Field	Type	Description
`type`	`'discord_oauth'`	N/A
`subject`	`string`	ID of user from Discord user API response.
`email`	`string`	Email of user from Discord user API response.
`username`	`string`	Username of user from Discord user API response.

(See Discord docs)

EmailAccount

Field	Type	Description
`type`	`'email'`	N/A
`address`	`string`	Email address of user account.

FarcasterAccount

Field	Type	Description
`type`	`'farcaster'`	N/A
`fid`	`number`	FID of the user from Farcaster user API response.
API: `owner_address` SDK: `ownerAddress`	`string`	Wallet address of the user from Farcaster user API response. Note that this is the Farcaster wallet address, and not the Privy embedded wallet address.
`username`	`string`	(Optional) Username of user from Farcaster user API response. Do not include the '@'.
API: `display_name` SDK: `displayName`	`string`	(Optional) Display name of user from Farcaster user API response.
`bio`	`string`	(Optional) Bio of user from Farcaster user API response.
API: `profile_picture_url` SDK: `profilePictureUrl`	`string`	(Optional) Profile picture URL of the user from Farcaster user API response. Must be a valid image URL.
API: `homepage_url` SDK: `homepageUrl`	`string`	(Optional) Profile URL of the user from Farcaster user API response.

(See Farcaster docs. Note that the Privy import interface differs slightly from the Farcaster public interface in order to maintain consistency with other Privy LinkedAccount types.)

GithubAccount

Field	Type	Description
`type`	`'github_oauth'`	N/A
`subject`	`string`	ID of user from GitHub user API response.
`email`	`string`	Email of user from GitHub user API response
`name`	`string`	Name of user from GitHub user API response
`username`	`string`	Username of user from GitHub user API response

(See GitHub docs)

GoogleAccount

Field	Type	Description
`type`	`'google_oauth'`	N/A
`subject`	`string`	`sub` pulled from Google-provided JWT with "openid" scope.
`email`	`string`	`email` from Google-provided JWT with "email" scope.
`name`	`string`	`name` from Google-provided JWT with "profile" scope.

InstagramAccount

Field	Type	Description
`type`	`'instagram_oauth'`	N/A
`subject`	`string`	ID of user from Instagram user API response.
`username`	`string`	The name displayed on a user's profile from Instagram's `/me` API response.

(See Instagram docs)

LinkedinAccount

Field	Type	Description
`type`	`'linkedin_oauth'`	N/A
`subject`	`string`	ID of user from LinkedIn user API response.
`email`	`string`	Email of user from LinkedIn user API response
`name`	`string`	Name of user from LinkedIn user API response. Do not include the '@'.

(See Linkedin docs)

PhoneAccount

Field	Type	Description
`type`	`'phone'`	N/A
`number`	`string`	Phone number of user account (non-international numbers default to US).

While number is accepted as input, phoneNumber is returned in the response.

SmartWalletAccount

Field	Type	Description
`type`	`'smart_wallet'`	N/A
`address`	`string`	Checksummed smart wallet address.
`smart_wallet_type`	`SmartWalletType`	One of `'kernel'`, `'safe'`, `'biconomy'` or `'light_account'`

SpotifyAccount

Field	Type	Description
`type`	`'spotify_oauth'`	N/A
`subject`	`string`	ID of user from Spotify user API response.
`email`	`string`	Email of user from Spotify user API.
`name`	`string`	The name displayed on a user's profile from Spotify display_name API response.

(See Spotify docs)

TelegramAccount

Field	Type	Description
`type`	`'telegram'`	N/A
`telegram_user_id`	`string`	ID of a user's telegram account.
`first_name`	`string`	The first name displayed on a user's telegram account.
`last_name`	`string`	(Optional) The last name displayed on a user's telegram account.
`username`	`string`	(Optional) The username displayed on a user's telegram account.
`photo_url`	`string`	(Optional) The url of a user's telegram account profile picture.

(See Telegram docs)

TwitterAccount

Field	Type	Description
`type`	`'twitter_oauth'`	N/A
`subject`	`string`	ID of user from Twitter user API response.
`name`	`string`	Name of user from Twitter user API response
`username`	`string`	Username of user from Twitter user API response. Do not include the '@'.
API: `profile_picture_url` SDK: `profilePictureUrl`	`string`	(Optional) Profile picture URL of the user from Twitter user API response. Must be a valid image URL.

(See Twitter docs)

WalletAccount

Field	Type	Description
`type`	`'wallet'`	N/A
API: `chain_type` SDK: `chainType`	`'ethereum'`	Type of chain for the wallet. EVM chains (`'ethereum'`) and Solana (`'solana'`) are currently supported.
`address`	`string`	Checksummed wallet address.

Below is an example:

json

{
  "data": [
    {
      "id": "did:privy:cfbsvtqo2c22202mo08847jdux2z",
      "created_at": 1667165891,
      "linked_accounts": [
        {
          "type": "wallet",
          "address": "0xABCDEFGHIJKL01234567895C5cAe8B9472c14328",
          "chain_type": "ethereum",
          "verified_at": 1667165891
        },
        {
          "type": "email",
          "address": "[email protected]",
          "verified_at": 1667350653
        }
      ]
    }
  ],
  "next_cursor": "did:privy:123456789"
}

Getting all users

To get all of the users for your app, you should iteratively request this API, and with each request, increment the cursor to be the next_cursor returned by the previous query. When there are no more results to return, the API response will return an empty array of users in the data field and the next_cursor field will be null.

Below are JavaScript and Python examples for getting all your users:

jsx

// Helper function to query Privy's API
const fetchPageOfUsers = async (cursor?: string) => {
  // Specify cursor in URL params if a cursor is provided
  const url = 'https://auth.privy.io/api/v1/users' + (cursor ? `?cursor=${cursor}` : '');
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      Authorization: `Basic ${btoa(`${'your-privy-app-id'}:${'your-privy-app-secret'}`)}`,
      'privy-app-id': 'your-privy-app-id',
    },
  });
  return response.json();
};

// Iteratively requesting all users
let cursor;
let query;
let users = [];
// This loop will terminate after there are no more users to request,
// which occurs when the `next_cursor` is null.
do {
  query = await fetchPageOfUsers(cursor);
  users = users.concat(query.data);
  cursor = query.next_cursor;
} while (cursor !== null);

Querying multiple users ​

Using @privy-io/server-auth ​

Using the REST API ​

Parameters ​

Response ​