> ## Documentation Index
> Fetch the complete documentation index at: https://replyke-feat-push-rich-payload-fields.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch User Suggestions

> Search for users by username prefix — for @mention autocomplete

Returns up to 5 users whose usernames contain the provided query string, ranked by prefix match first, then alphabetically. Designed for `@mention` autocomplete and user search UIs.

<Note>
  Sensitive fields (email, hash, salt, `isVerified`, `isActive`,
  `lastActive`) are excluded from suggestions results.
</Note>

## Query Parameters

<ParamField query="query" type="string" required>
  The search string. Matches usernames that contain this value
  (case-insensitive). Users whose usernames start with `query` are ranked
  first.
</ParamField>

### Space-scoped reputation

This endpoint has no space in context, so `spaceReputationId` accepts a space **`<uuid>`** or **`none`** only — `context` is rejected (400). It adds a `spaceReputation` field to each returned user, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation).

<ParamField query="spaceReputationId" type="string">
  Adds `spaceReputation` to each returned user. Either a space **`<uuid>`** (that space's bucket) or **`none`** (the project-general bucket). `context`, the empty string, and the legacy `general` / `null` aliases are rejected (400). Missing buckets read as `0`.
</ParamField>

<ParamField query="spaceReputationDescendants" type="boolean">
  Only honored with an explicit space `<uuid>`. When `true`, `spaceReputation` is the subtree sum — the space plus all of its descendants. Ignored for `none`.
</ParamField>

## Response

On success, returns HTTP `200` with an array of up to 5 user objects:

<ResponseField name="id" type="string">
  Unique user ID (UUID).
</ResponseField>

<ResponseField name="foreignId" type="string | null">
  External identifier from your system.
</ResponseField>

<ResponseField name="name" type="string | null">
  Display name.
</ResponseField>

<ResponseField name="username" type="string | null">
  The user's username.
</ResponseField>

<ResponseField name="avatar" type="string | null">
  Avatar image URL.
</ResponseField>

<ResponseField name="bio" type="string | null">
  Short bio text.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Public custom key-value data.
</ResponseField>

<ResponseField name="reputation" type="number">
  Reputation score.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of account creation.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "user/invalid-query"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useFetchUserSuggestions` hook](/hooks/users/use-fetch-user-suggestions)
* [`useUserMentions` hook](/hooks/users/use-user-mentions)