Skip to content
Torii docs

Search users

POST
/api/server/v1/users/search
 
curl --request POST \
  --url 'https://api.torii.so/api/server/v1/users/search?limit=50&cursor=01931a73-8b00-7000-8000-000000000000' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Ada", "userIds": [ "01931a73-8b00-7000-8000-000000000000" ], "emailAddresses": [ "ada@example.com" ], "email": "@example.com", "statuses": [ "active" ], "createdAfter": "2026-01-01T00:00:00Z", "createdBefore": "2026-12-31T23:59:59Z" }'

Returns a cursor-paginated page of end-users in the environment matching the optional filters. Uses POST so the filter body can be sent without URL-encoding. Three id-selectors resolve users to a set of ids (userIds, the explicit batch-by-id lookup; emailAddresses, exact and case-insensitive; email, a case-insensitive substring); when more than one is supplied they are combined with AND (intersection). The remaining filters (name, statuses, createdAfter/createdBefore) apply on top.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
limit
integer format: int32
default: 20

Maximum number of items in the returned page (default 20).

Example 
50
cursor
string format: uuid

Opaque cursor returned by the previous page’s nextCursor. Omit to fetch the first page.

Example 
01931a73-8b00-7000-8000-000000000000

Request Body

Section titled “Request Body ”
Media type application/json

Optional filter body for POST /users/search. Every field is tri-state: omit to skip that filter, send a value to apply it. The three id-selectors (userIds, emailAddresses, email) resolve users to a set of ids and, when more than one is supplied, are combined with AND (intersection); a supplied id-selector whose resolved set is empty returns an empty page. name additionally accepts JSON null to match users with no name; an explicit null or blank email contributes no restriction; the non-nullable statuses field rejects null.

object
name

Filter by name (case-insensitive substring match). Send null to require users with no name.

string | null
Example 
Ada
userIds

Restrict to these user ids (the explicit batch-by-id lookup), at most 100. AND-combined with the other id-selectors; an empty list returns an empty page.

Array<string>
Example 
[
  "01931a73-8b00-7000-8000-000000000000"
]
emailAddresses

Resolve users by exact (case-insensitive) email address (one or more, at most 100). Unlike email, never matches a superstring. AND-combined with the other id-selectors; an empty list, or addresses matching nobody, returns an empty page.

Array<string>
Example 
[
  "ada@example.com"
]
email

Filter by primary email (case-insensitive substring match). AND-combined with the other id-selectors. An explicit null or blank value contributes no restriction.

string | null
Example 
@example.com
statuses

Filter by user status. Returns users matching any of the supplied statuses.

Array<string>
unique items
Allowed values: active banned deleted
createdAfter

Only return users created at or after this instant (ISO-8601 UTC).

string | null format: date-time
Example 
2026-01-01T00:00:00Z
createdBefore

Only return users created at or before this instant (ISO-8601 UTC).

string | null format: date-time
Example 
2026-12-31T23:59:59Z

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Page of matching users.

Media type application/json

A single page of results in a cursor-paginated list. Pass nextCursor as the cursor query parameter to fetch the following page.

object
items
required

Items in this page, in stable order.

Array<object>

An end-user, including server-only private metadata. Returned only on the secret-key backend API.

object
id
required

Unique identifier for this user.

string format: uuid
environmentId
required

Identifier of the environment this user belongs to.

string format: uuid
name

Full name on the profile, if any.

string | null
firstName

First (given) name on the profile, if any.

string | null
lastName

Last (family) name on the profile, if any.

string | null
locale

Preferred locale for emails and UI messages.

string | null
Allowed values: en da
status
required

Lifecycle status of the user (e.g. active, banned).

string
Allowed values: active banned deleted
createdAt
required

When this user was created (ISO-8601 UTC).

string format: date-time
updatedAt
required

When this user was last modified (ISO-8601 UTC).

string format: date-time
email

Primary email on the profile, if any.

string | null
emailVerifiedAt

When this user’s primary email was verified, if it has been verified.

string | null format: date-time
deletedAt

When this user was deleted, if soft-deleted. Null for active users.

string | null format: date-time
publicMetadata
required

Public metadata: readable by the SDK, writable only server-side.

object
key
additional properties
any
privateMetadata
required

Private metadata: server-only. Never exposed to the SDK or in a JWT.

object
key
additional properties
any
unsafeMetadata
required

Unsafe metadata: readable and writable by the end-user via the SDK.

object
key
additional properties
any
nextCursor

Cursor to pass to fetch the next page. Null when this is the last page.

string | null format: uuid
hasMore
required

True if more pages are available (equivalent to nextCursor != null).

boolean
Example 
{
  "items": [
    {
      "id": "01931a73-8b00-7000-8000-000000000000",
      "environmentId": "01931a72-0000-7000-8000-000000000000",
      "name": "Ada Lovelace",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "locale": "en",
      "status": "active",
      "createdAt": "2026-05-16T09:30:00Z",
      "updatedAt": "2026-05-16T10:00:00Z",
      "email": "ada@example.com",
      "emailVerifiedAt": "2026-05-16T09:35:00Z",
      "deletedAt": "2026-05-20T12:00:00Z",
      "publicMetadata": {
        "plan": "pro"
      },
      "privateMetadata": {
        "billingCustomerId": "cus_123"
      },
      "unsafeMetadata": {
        "onboardingStep": 2
      }
    }
  ],
  "nextCursor": "01931a73-8b00-7000-8000-000000000000",
  "hasMore": true
}

400

Section titled “400 ”

An id-selector list exceeds 100 entries.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

401

Section titled “401 ”

Missing or invalid secret key.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}