User Search

Search for users by nickname, first name, last name, or numeric ID.

Search Users

Request:

{
  "id": "47",
  "type": "user.search",
  "data": {
    "query": "John",
    "limit": 10,
    "offset": 0
  }
}

Field	Type	Required	Description
`query`	string	Yes	Search string (minimum 2 characters)
`limit`	number	No	Max results to return (default: 20, max: 50)
`offset`	number	No	Offset for pagination (default: 0)

The query is matched against:

Numeric user ID — exact match (if query is a number)
Nickname — substring match
First name — substring match
Last name — substring match
Full name — substring match (first name + last name combined)

Results are ranked by match quality: exact ID match first, then prefix matches on nick, first name, and last name.

The requesting user is excluded from results.

Success:

{
  "id": "47",
  "type": "user.search",
  "ok": true,
  "data": {
    "users": [
      {
        "user_id": 67890,
        "nick": "Johnny",
        "first_name": "John",
        "last_name": "Doe",
        "about": "Hello!",
        "gender": "male",
        "avatar_hash": "a1b2c3d4"
      }
    ],
    "has_more": false
  }
}

Field	Type	Description
`users`	array	Matching users (may be empty)
`has_more`	boolean	`true` if there are more results beyond the current page

Each user object:

Field	Type	Description
`user_id`	number	User's numeric ID
`nick`	string	Display name / nickname
`first_name`	string	First name
`last_name`	string	Last name
`about`	string	About / bio text
`gender`	string	Gender: `"male"`, `"female"`, or `""`
`avatar_hash`	string	Avatar hash (empty if no avatar)
`bot`	boolean	`true` for a bot; absent for a person
`official`	boolean	`true` for one of the server's own accounts, as in a profile

Note: birthday is not included in search results for privacy. Users separated by a block are omitted from search, and direct profile lookups for them return user_not_found.

Failure (query too short):

{
  "id": "47",
  "type": "user.search",
  "ok": false,
  "error": {
    "code": "invalid_format",
    "message": "Query must be at least 2 characters"
  }
}