---
title: "Search guild members"
method: POST
path: "/guilds/{guild_id}/members-search"
tags: ["Guilds"]
---

# Search guild members

`POST /guilds/{guild_id}/members-search`

Search and filter guild members with pagination support.

## Path parameters

- `guild_id` string, snowflake, required

## Request body

- GuildMemberSearchRequest
  - `query` string — Text to search for in usernames, global names, and nicknames
  - `limit` integer — Maximum number of results to return
  - `offset` integer — Number of results to skip for pagination
  - `role_ids` string[] — Filter by role IDs (member must have all specified roles)
  - `joined_at_gte` integer — Filter members who joined at or after this unix timestamp
  - `joined_at_lte` integer — Filter members who joined at or before this unix timestamp
  - `join_source_type` JoinSourceType[] — Filter by join source types
  - `source_invite_code` string[] — Filter by invite codes used to join
  - `is_bot` boolean — Filter by bot status
  - `user_created_at_gte` integer — Filter members whose account was created at or after this unix timestamp
  - `user_created_at_lte` integer — Filter members whose account was created at or before this unix timestamp
  - `sort_by` 'joinedAt' | 'relevance' — Sort results by field
  - `sort_order` 'asc' | 'desc' — Sort order

## Response `200`

Success

- GuildMemberSearchResponse
  - `guild_id` string, required — Guild ID
  - `members` GuildMemberSearchResult[], required — Matching members
    - `id` string, required — Composite ID (guildId:userId)
    - `guild_id` string, required — Guild ID
    - `user_id` string, required — User ID
    - `username` string, required — Username
    - `discriminator` string, required — Zero-padded 4-digit discriminator
    - `global_name` string, nullable, required — Global display name
    - `nickname` string, nullable, required — Guild nickname
    - `role_ids` string[], required — Role IDs
    - `joined_at` number, required — Unix timestamp of when the member joined
    - `supplemental` object, required — Supplemental members-search-only metadata that is not part of the base guild member payload
      - `join_source_type` 0 | 1 | 2 | 3 | 4 | 6 — How the member joined the guild
      - `source_invite_code` string, nullable, required — Invite code used to join
      - `inviter_id` string, nullable, required — User ID of the member who sent the invite
    - `is_bot` boolean, required — Whether the user is a bot
  - `page_result_count` integer, required — Number of results in this page
  - `total_result_count` integer, required — Total number of matching results
  - `indexing` boolean, required — Whether the guild members are currently being indexed

## Other responses

- `400` — Bad Request - The request was malformed or contained invalid data
- `401` — Unauthorized - Authentication is required or the token is invalid
- `403` — Forbidden - You do not have permission to perform this action
- `429` — Too Many Requests - You are being rate limited
- `500` — Internal Server Error - An unexpected error occurred

## Changes

- **2026-09-03** `fa36b1b48ca5` — 20 info
  - removed the `INVALID_PACK_TYPE` enum value from the `code` response property for the response status `400`
  - removed the `INVALID_PACK_TYPE` enum value from the `code` response property for the response status `401`
  - removed the `INVALID_PACK_TYPE` enum value from the `code` response property for the response status `403`
  - removed the `INVALID_PACK_TYPE` enum value from the `code` response property for the response status `500`
  - …16 more

[Change history](https://skmtc.dev/fluxer/apis/fluxer-api/changes/guilds/:guild_id/members-search/post.md)

---

[API](https://skmtc.dev/fluxer/apis/fluxer-api.md) · [All operations](https://skmtc.dev/fluxer/apis/fluxer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fluxer/fluxer-api/revisions/f6d51a9b1034/schema)