# Search for users

Performs an administrative search for users with multiple filter criteria. Can search by user ID, account ID, username, domain, display name, state, email, IP address, country, or role. Supports mixed search across username, display name, and email simultaneously. Results include detailed user information and support pagination and sorting. IP addresses are matched exactly, and country codes should use ISO 3166-1 alpha-2 format.

RBAC: requires Users.Manage

Endpoint: GET /api/v1/admin/search
Version: 1.0
Security: header

## Query parameters:

  - `accountId` (string,null)
    Account id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `country` (string,null)
    Country

  - `displayName` (string,null)
    Display name

  - `domain` (string,null)
    Domain

  - `email` (string,null)
    Email

  - `entityType` (string,null)
    Entity type to filter by (USER, BOT, APPLICATION, GROUP_CHANNEL). Defaults to USER.
    Enum: "USER", "BOT", "APPLICATION", "GROUP_CHANNEL"

  - `ip` (string,null)
    IP address

  - `kind` (string,null)
    Result kind: CHANNEL for only global channels, USER for only users, ALL for both. Default ALL
    Enum: "CHANNEL", "USER", "ALL"

  - `lastId` (string,null)
    Get older records (records with IDs less than this value) Alias maxId/max_id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `limit` (integer,null)

  - `offset` (integer,null)

  - `role` (string,null)
    Role
    Example: "\n        'admin',\n        'System:admin',\n        'rr_01hxcvk1hjexere4pvtrj0ymqq',\n        'System:rr_01hxcvk1hjexere4pvtrj0ymqq',\n        'gr_1lkjvfdoibb126576:rr_01hxcvk1hjexere4pvtrj0ymqq',\n    "

  - `search` (string,null)
    Mixed search across username, display name or email

  - `sortBy` (string,null)

  - `sortOrder` (string,null)
    Sort order. Supported values: ASC or DESC

  - `state` (string,null)
    State
    Enum: "REGULAR", "SENSITIVE", "LIMITED", "SUSPENDED"

  - `untilId` (string,null)
    Get newer records (records with IDs greater than this value) Alias minId/min_id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `userId` (string,null)
    userId
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `username` (string,null)
    Username

## Response 200 fields (application/json):

  - `list` (array, required)
    List of user details matching the search criteria

  - `list.userId` (string, required)
    Internal ID of this user
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `list.accountId` (string,null)
    ID of the account this user belongs to, empty for remote users
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `list.username` (string, required)
    Unique username
    Example: "john_smith"

  - `list.displayName` (string, required)
    Full name of the user
    Example: "John Smith"

  - `list.email` (string,null)
    User's email address
    Example: "john@example.com"

  - `list.domain` (string,null)
    User's domain
    Example: "domain.net"

  - `list.local` (boolean, required)
    Whether this user is local to this server

  - `list.numPosts` (integer, required)
    Number of posts by this user

  - `list.numFollowers` (integer, required)
    Number of followers this user has

  - `list.createdAt` (string, required)
    When this user was created
    Example: "2022-03-10T16:15:50Z"

  - `list.deletedAt` (string,null)
    When this user was deleted, if applicable
    Example: "2022-03-10T16:15:50Z"

  - `list.lastActive` (string,null)
    When this user was last active
    Example: "2022-03-10T16:15:50Z"

  - `list.lastIP` (object,null)
    Last IP address used by this user

  - `list.lastIP.multicastAddress` (boolean)

  - `list.lastIP.anyLocalAddress` (boolean)

  - `list.lastIP.loopbackAddress` (boolean)

  - `list.lastIP.linkLocalAddress` (boolean)

  - `list.lastIP.siteLocalAddress` (boolean)

  - `list.lastIP.MCGlobal` (boolean)

  - `list.lastIP.MCNodeLocal` (boolean)

  - `list.lastIP.MCLinkLocal` (boolean)

  - `list.lastIP.MCSiteLocal` (boolean)

  - `list.lastIP.MCOrgLocal` (boolean)

  - `list.lastIP.hostName` (string)

  - `list.lastIP.address` (string)

  - `list.lastIP.hostAddress` (string)

  - `list.lastGeoData` (object,null)
    Last geo data from which this user accessed the system

  - `list.lastGeoData.countryCode` (string,null)
    ISO country code

  - `list.lastGeoData.country` (string,null)
    Country name

  - `list.lastGeoData.subdivision` (string,null)
    Subdivision or state/province name

  - `list.lastGeoData.city` (string,null)
    City name

  - `list.lastGeoData.timeZone` (string,null)
    IANA timezone identifier

  - `list.state` (string, required)
    User's moderation state
    Enum: "REGULAR", "SENSITIVE", "LIMITED", "SUSPENDED"

  - `list.entityType` (string)
    Entity type: USER, BOT, APPLICATION, GROUP_CHANNEL
    Enum: "USER", "BOT", "APPLICATION", "GROUP_CHANNEL"

  - `list.actorType` (string, required)
    Actor type derived from entity type
    Enum: "Application", "Group", "Organization", "Person", "Service"

  - `list.groupId` (string,null)
    Group id if this user is a group channel
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `list.roles` (array)
    Roles assigned to this user

  - `list.roles.roleId` (string, required)
    Internal ID of this role

  - `list.roles.name` (string, required)
    Name of the role
    Example: "ADMIN"

  - `list.roles.description` (string,null)
    The description of the role
    Example: "The Admin role in the \"system\" scope"

  - `list.avatar` (object,null)
    User's avatar

  - `list.avatar.uploadId` (string, required)
    Internal id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `list.avatar.uploaderId` (string,null)
    User who physically uploaded this file. Null for platform-owned uploads (e.g., default covers). This is an audit/meta field — use ownerId for authorization.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `list.avatar.ownerId` (string, required)
    Entity that owns this upload (user, channel/group, or event). TypeID prefix indicates the owner type.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `list.avatar.attachedToId` (string,null)
    Entity this upload is attached to (e.g., a post or event). NULL for standalone uploads like avatars, covers, or media library items.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `list.avatar.uploadType` (string, required)
    Type of the upload
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `list.avatar.meta` (object)
    Meta data

  - `list.avatar.meta.blurhash` (string,null)

  - `list.avatar.meta.name` (string,null)

  - `list.avatar.meta.altText` (string,null)

  - `list.avatar.size` (integer, required)
    Size in bytes of all the files in this upload

  - `list.avatar.files` (array, required)
    List of all the files this upload has

  - `list.avatar.files.uri` (string,null, required)
    Full url of the file

  - `list.avatar.files.fileId` (string, required)
    File id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `list.avatar.files.extension` (string, required)
    File extension
    Example: "mp4"

  - `list.avatar.files.original` (boolean, required)
    true if this file is original, false if it is a derivative

  - `list.avatar.files.meta` (object, required)
    File metadata. Contains optional values for width, height etc.

  - `list.avatar.files.meta.duration` (number,null)
    Video duration in seconds

  - `list.avatar.files.meta.width` (integer,null)
    Media width

  - `list.avatar.files.meta.height` (integer,null)
    Media height

  - `list.avatar.files.meta.codec` (string,null)
    Video codec

  - `list.avatar.files.meta.rotate` (integer,null)
    Rotation in degrees

  - `list.avatar.files.size` (integer, required)
    File size in bytes

  - `list.avatar.files.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `list.avatar.files.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `list.avatar.files.type` (string, required)
    File type
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `list.avatar.tags` (array, required)
    List of tags attached to upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `list.avatar.error` (string,null)
    Upload processing error

  - `list.avatar.cached` (boolean)
    true if cached

  - `list.avatar.logs` (string,null)
    Logs

  - `list.avatar.remote` (boolean)
    true if this upload is remote

  - `list.avatar.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `list.avatar.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `list.channel` (boolean)
    Whether this is a channel. Deprecated: use 'entityType' instead.

  - `total` (integer, required)
    Total number of results for the current search

  - `totalUsers` (integer, required)
    Total number of users in the system

## Response 400 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 403 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation