Guild member search¶

Member search filters, sorts and pages a guild's members by name, role, join time and account type. It powers the Members page in guild settings. Each match is a guild member search result.

The route is relative to https://tebhos.com/api/v1, requires authentication and accepts both user sessions and bot tokens. Error bodies follow Errors.

Join source types¶

The search result and the join_source_type filter use these values.

Guild member search result object¶

A matched membership. Account fields are at the top level rather than under user.

{
  "id": "1489002177550843904:1489002177550843906",
  "guild_id": "1489002177550843904",
  "user_id": "1489002177550843906",
  "username": "ada",
  "discriminator": "0042",
  "global_name": "Ada",
  "nickname": null,
  "role_ids": ["1489002177550843910"],
  "joined_at": 1755158400,
  "supplemental": {"join_source_type": null, "source_invite_code": "a1b2c3d4", "inviter_id": "1489002177550843905"},
  "is_bot": false
}

The result has no avatar, timeout or voice fields. Use Get guild member for the full membership.

Guild member search supplemental object¶

Every field is null unless the caller is the guild owner or holds MANAGE_GUILD (or ADMINISTRATOR). A null value therefore does not tell you whether the data exists.

Guild member search response object¶

Search guild members¶

POST /guilds/{guild_id}/members-search

Returns a guild member search response. The caller must be a member and must be the owner or hold at least one of MANAGE_GUILD, MANAGE_ROLES, MANAGE_NICKNAMES, BAN_MEMBERS, MODERATE_MEMBERS, KICK_MEMBERS or ADMINISTRATOR.

Rate limit: guild:members, 40 per 10 seconds per account and guild (shared with the member reads and List guild bans).

JSON body¶

Every field is optional, and an empty object {} returns the first page of all members.

Text matching. Without the search engine, query matches the member's nickname, display name or username (case-insensitive: exact match first, then prefix, then substring) or exactly equals the user ID. With the engine, the engine decides which members match and in what order; the filters above still apply to its matches.

Sorting. With a query and no sort_by, or with sort_by relevance, results are ordered by relevance and then by join time. Otherwise they are ordered by join time, oldest first, or newest first with sort_order desc. Ties are broken by user ID.

curl -X POST https://tebhos.com/api/v1/guilds/1489002177550843904/members-search \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "ada", "role_ids": ["1489002177550843910"], "limit": 50}'