---
title: "Search users"
method: GET
path: "/api/user/search"
tags: ["User"]
---

# Search users

`GET /api/user/search`

## Request

- Base URL: `https://app.d-sports.org`
- URL: `https://app.d-sports.org/api/user/search`
- Auth: HTTP bearer

Authenticated paginated user search. Default scope matches handle, name, and (for q length >= 2) location. `scope=mention` matches handle and name only and omits users without a handle — use this from @mention typeahead so a city fragment cannot outrank a handle. `limit` is accepted (1–50, default 20). Each row uses `profileUrl` (not `avatar`); there is no `level` field. `handle` is nullable on the default scope and non-empty on `scope=mention`. `location` is always returned as a profile field; only the default scope uses it for matching and ranking.

## Query parameters

- `q` string, required
- `page` integer
- `limit` integer
- `scope` 'mention'

## Response `200`

{ success, data: { users, total, page, totalPages, query } }

- object
  - `success` true, required
  - `data` object, required
    - `users` UserSearchUser[], required
      - `id` string, required
      - `name` string, nullable, required
      - `handle` string, nullable, required
      - `profileUrl` string, nullable, required
      - `profileUrlThumbhash` string, nullable, required
      - `bio` string, nullable, required
      - `location` string, nullable, required
      - `favoriteTeam` string, nullable, required
      - `stats` object, required
        - `followerCount` integer, required
        - `followingCount` integer, required
        - `totalPoints` integer, required
    - `total` integer, required
    - `page` integer, required
    - `totalPages` integer, required
    - `query` string, required

## Other responses

- `400`: Empty q, invalid page/limit, or unknown scope
- `401`: Unauthenticated

## Changes

- **2026-08-26** `2f49601f3886`: 5 breaking, 3 warning, 4 info
  - the `query` request parameter `q` became required
  - for the `query` request parameter `limit`, default value `20` was added
  - for the `query` request parameter `page`, default value `1` was added
  - for the `query` request parameter `q`, the minLength was increased from `0` to `1`
  - …8 more
- **2026-03-08** `120afc4ee72c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/changes/api/user/search/get.md)

---

[API](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api.md) - [All operations](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/llms.txt) - [OpenAPI document](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/revisions/63735cf90a04?raw)
